@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/adapters/agent-browser/assertions.js

@@ -0,0 +1,47 @@
+import { E_BROWSER_VERIFICATION_RESULT_INVALID } from "../../core/error-codes.js";
+
+export function actualValue(data) {
+  if (typeof data === "string" || typeof data === "number" || typeof data === "boolean") return String(data);
+  if (!data || typeof data !== "object" || Array.isArray(data)) return "";
+  for (const key of ["text", "value", "attribute", "url", "title", "visible"]) {
+    if (data[key] !== undefined && data[key] !== null) return String(data[key]);
+  }
+  return "";
+}
+
+export function observedScalar(data, label = "Agent Browser observation") {
+  if (typeof data === "string" || typeof data === "number" || typeof data === "boolean") {
+    return String(data);
+  }
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    for (const key of ["text", "value", "attribute", "url", "title", "visible"]) {
+      if (Object.prototype.hasOwnProperty.call(data, key) && data[key] !== undefined && data[key] !== null) {
+        const value = data[key];
+        if (["string", "number", "boolean"].includes(typeof value)) return String(value);
+      }
+    }
+  }
+  const error = new Error(`${label} was malformed`);
+  error.code = E_BROWSER_VERIFICATION_RESULT_INVALID;
+  throw error;
+}
+
+export function matchesAssertion(kind, actual, expected) {
+  if (kind === "VISIBLE") return actual === "true";
+  if (kind === "HIDDEN") return actual !== "true";
+  if (kind === "TEXT_CONTAINS") return actual.includes(expected);
+  if (kind === "TEXT_EQUALS" || kind === "VALUE_EQUALS" || kind === "ATTRIBUTE_EQUALS" || kind === "TITLE_EQUALS") return actual === expected;
+  if (kind === "URL_IS") return actual === expected;
+  if (kind === "URL_PREFIX") return actual.startsWith(expected);
+  return false;
+}
+
+export function assertionResult(assertion, status, actual, message) {
+  return {
+    id: assertion.id,
+    kind: assertion.kind,
+    status,
+    ...(actual !== undefined ? { actual: String(actual) } : {}),
+    ...(message ? { message } : {}),
+  };
+}

package/src/adapters/agent-browser/commands.js

@@ -0,0 +1,54 @@
+const SAFE_GLOBAL_FLAGS = Object.freeze(["--content-boundaries", "--no-webmcp"]);
+
+function globalArgs({ sessionId, allowedOrigins, maxOutputChars = 50_000 } = {}) {
+  const domains = [...new Set((allowedOrigins ?? []).map((origin) => new URL(origin).hostname.toLowerCase()))].join(",");
+  return [
+    "--session", sessionId,
+    "--allowed-domains", domains,
+    "--max-output", String(maxOutputChars),
+    ...SAFE_GLOBAL_FLAGS,
+  ];
+}
+
+function command({ sessionId, allowedOrigins, maxOutputChars, name, args = [], json = true }) {
+  return [
+    ...globalArgs({ sessionId, allowedOrigins, maxOutputChars }),
+    name,
+    ...args,
+    ...(json ? ["--json"] : []),
+  ];
+}
+
+export function versionCommand() { return ["--version"]; }
+export function openCommand(input) { return command({ ...input, name: "open", args: [input.url] }); }
+export function clickCommand(input) { return command({ ...input, name: "click", args: [input.selector] }); }
+export function focusCommand(input) { return command({ ...input, name: "focus", args: [input.selector] }); }
+export function fillCommand(input) { return command({ ...input, name: "fill", args: [input.selector, input.text] }); }
+export function pressCommand(input) { return command({ ...input, name: "press", args: [input.key] }); }
+export function snapshotCommand(input) { return command({ ...input, name: "snapshot", args: ["-i"] }); }
+export function visibleCommand(input) { return command({ ...input, name: "is", args: ["visible", input.selector] }); }
+export function textCommand(input) { return command({ ...input, name: "get", args: ["text", input.selector] }); }
+export function valueCommand(input) { return command({ ...input, name: "get", args: ["value", input.selector] }); }
+export function attributeCommand(input) { return command({ ...input, name: "get", args: ["attr", input.selector, input.attribute] }); }
+export function urlCommand(input) { return command({ ...input, name: "get", args: ["url"] }); }
+export function titleCommand(input) { return command({ ...input, name: "get", args: ["title"] }); }
+export function screenshotCommand(input) { return command({ ...input, name: "screenshot", args: [input.outputPath], json: true }); }
+export function closeCommand(input) { return command({ ...input, name: "close", args: [] }); }
+
+export const AGENT_BROWSER_COMMANDS = Object.freeze({
+  version: versionCommand,
+  open: openCommand,
+  click: clickCommand,
+  focus: focusCommand,
+  fill: fillCommand,
+  press: pressCommand,
+  snapshot: snapshotCommand,
+  visible: visibleCommand,
+  text: textCommand,
+  value: valueCommand,
+  attribute: attributeCommand,
+  url: urlCommand,
+  title: titleCommand,
+  screenshot: screenshotCommand,
+  close: closeCommand,
+});

package/src/adapters/agent-browser/index.js

@@ -0,0 +1,3 @@
+export { createAgentBrowserVerificationProvider } from "./provider.js";
+export { AGENT_BROWSER_PROCESS_LIMITS, parseAgentBrowserJson, runAgentBrowserCommand } from "./process.js";
+export * from "./commands.js";

package/src/adapters/agent-browser/locator.js

@@ -0,0 +1,40 @@
+import { E_BROWSER_VERIFICATION_RESULT_INVALID } from "../../core/error-codes.js";
+
+function locatorError(message) {
+  const error = new Error(message);
+  error.code = E_BROWSER_VERIFICATION_RESULT_INVALID;
+  error.kind = "BLOCKED";
+  return error;
+}
+
+function refsFromSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) return [];
+  const refs = snapshot.refs;
+  if (!refs || typeof refs !== "object" || Array.isArray(refs)) return [];
+  return Object.entries(refs).map(([ref, value]) => ({ ref, ...(value && typeof value === "object" ? value : { name: value }) }));
+}
+
+function candidateText(value) {
+  return [value?.name, value?.text, value?.label, value?.value].filter((item) => typeof item === "string");
+}
+
+export function resolveSnapshotLocator(locator, snapshot) {
+  if (!locator || typeof locator !== "object") throw locatorError("Browser locator is invalid");
+  if (locator.kind === "CSS") return locator.value;
+  const refs = refsFromSnapshot(snapshot);
+  const needle = locator.value;
+  const matches = refs.filter((entry) => {
+    const values = candidateText(entry);
+    if (locator.kind === "TEXT" || locator.kind === "LABEL") return values.some((value) => value === needle);
+    if (locator.kind === "ROLE") {
+      return entry.role === needle || values.some((value) => `${entry.role ?? ""} ${value}`.trim() === needle);
+    }
+    return false;
+  });
+  if (matches.length !== 1) {
+    throw locatorError(matches.length === 0 ? "Browser locator was not found" : "Browser locator was ambiguous");
+  }
+  return matches[0].ref;
+}
+
+export function snapshotRefs(snapshot) { return refsFromSnapshot(snapshot); }

package/src/adapters/agent-browser/process.js

@@ -0,0 +1,215 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  E_BROWSER_VERIFICATION_OUTPUT_LIMIT,
+  E_BROWSER_VERIFICATION_CANCELLED,
+  E_BROWSER_VERIFICATION_EXECUTION_FAILED,
+  E_BROWSER_VERIFICATION_PROVIDER_INVALID,
+  E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE,
+  E_BROWSER_VERIFICATION_RESULT_INVALID,
+  E_BROWSER_VERIFICATION_TIMEOUT,
+} from "../../core/error-codes.js";
+
+export const AGENT_BROWSER_PROCESS_LIMITS = Object.freeze({
+  maxStdoutBytes: 1024 * 1024,
+  maxStderrBytes: 64 * 1024,
+  terminationGraceMs: 150,
+  maxVersionBytes: 64 * 1024,
+  maxOutputChars: 50_000,
+});
+
+function processError(code, message) {
+  const error = new Error(message);
+  error.name = "AgentBrowserProcessError";
+  error.code = code;
+  return error;
+}
+
+function portableString(value, label) {
+  if (typeof value !== "string" || value.length === 0 || /\p{Cc}/u.test(value)) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, `${label} must be a non-empty portable string`);
+  }
+  return value;
+}
+
+export function assertAbsoluteRegularFile(value, label, fsImpl = fs) {
+  portableString(value, label);
+  if (!path.isAbsolute(value)) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, `${label} must be an absolute path`);
+  }
+  let link;
+  let stat;
+  try {
+    link = fsImpl.lstatSync(value);
+    stat = fsImpl.statSync(value);
+  } catch {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE, `${label} is unavailable`);
+  }
+  if (link.isSymbolicLink?.() || !stat.isFile?.()) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, `${label} must be a regular file without symlink indirection`);
+  }
+  return value;
+}
+
+function bytes(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk.byteLength : Buffer.byteLength(String(chunk));
+}
+
+function terminate(child) {
+  if (!child || typeof child.kill !== "function") return;
+  try { child.kill("SIGTERM"); } catch { /* exited between checks */ }
+  const timer = setTimeout(() => {
+    try { child.kill("SIGKILL"); } catch { /* preserve original failure */ }
+  }, AGENT_BROWSER_PROCESS_LIMITS.terminationGraceMs);
+  timer.unref?.();
+}
+
+function waitForClose(child) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve();
+    };
+    child?.once?.("close", finish);
+    const timer = setTimeout(finish, AGENT_BROWSER_PROCESS_LIMITS.terminationGraceMs + 500);
+    timer.unref?.();
+  });
+}
+
+function filteredEnvironment(overrides = {}, trustedEnvKeys = new Set()) {
+  const forbidden = new Set([
+    "AGENT_BROWSER_PROVIDER", "AGENT_BROWSER_PROFILE", "AGENT_BROWSER_RESTORE", "AGENT_BROWSER_STATE",
+    "AGENT_BROWSER_CDP", "AGENT_BROWSER_AUTO_CONNECT", "AGENT_BROWSER_PLUGINS", "AGENT_BROWSER_INIT_SCRIPTS",
+    "AGENT_BROWSER_EXTENSIONS", "AGENT_BROWSER_ALLOWED_DOMAINS", "AGENT_BROWSER_MAX_OUTPUT",
+    "AGENT_BROWSER_CONTENT_BOUNDARIES", "AGENT_BROWSER_NO_WEBMCP", "AGENT_BROWSER_EXECUTABLE_PATH",
+    "AGENT_BROWSER_SESSION", "AGENT_BROWSER_SCREENSHOT_DIR", "AGENT_BROWSER_DOWNLOAD_PATH",
+    "AGENT_BROWSER_ACTION_POLICY", "AGENT_BROWSER_CONFIRM_ACTIONS", "AGENT_BROWSER_ENGINE",
+    "AI_GATEWAY_API_KEY", "AI_GATEWAY_MODEL", "AI_GATEWAY_URL", "BROWSERBASE_API_KEY",
+    "BROWSERLESS_API_KEY", "BROWSER_USE_API_KEY", "KERNEL_API_KEY", "AGENT_BROWSER_CONFIG",
+  ]);
+  const env = {};
+  for (const [key, value] of Object.entries({ ...process.env, ...overrides })) {
+    if ((!forbidden.has(key) || trustedEnvKeys.has(key)) && typeof value === "string") env[key] = value;
+  }
+  return env;
+}
+
+export async function runAgentBrowserCommand(executablePath, args, {
+  cwd,
+  timeoutMs,
+  signal,
+  spawnImpl = nodeSpawn,
+  env,
+  maxStdoutBytes = AGENT_BROWSER_PROCESS_LIMITS.maxStdoutBytes,
+  maxStderrBytes = AGENT_BROWSER_PROCESS_LIMITS.maxStderrBytes,
+  fsImpl = fs,
+  trustedEnvKeys = [],
+} = {}) {
+  assertAbsoluteRegularFile(executablePath, "Agent Browser executable", fsImpl);
+  portableString(cwd, "Agent Browser cwd");
+  if (!path.isAbsolute(cwd)) throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser cwd must be absolute");
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || /\p{Cc}/u.test(arg))) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser argv must be a portable string array");
+  }
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser timeout must be a positive integer");
+  }
+  if (signal?.aborted) throw processError(E_BROWSER_VERIFICATION_CANCELLED, "Agent Browser verification was cancelled");
+
+  let child;
+  try {
+    child = spawnImpl(executablePath, [...args], {
+      cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: filteredEnvironment(env, new Set(trustedEnvKeys)),
+    });
+  } catch (error) {
+    throw processError(
+      error?.code === "ENOENT" ? E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE : E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE,
+      "Agent Browser executable could not be started",
+    );
+  }
+  if (!child?.stdout || !child?.stderr || typeof child.on !== "function") {
+    terminate(child);
+    throw processError(E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE, "Agent Browser process did not expose safe output streams");
+  }
+
+  return new Promise((resolve, reject) => {
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const stdout = [];
+    let settled = false;
+    const timerRef = { value: null };
+    const cleanup = () => {
+      if (timerRef.value) clearTimeout(timerRef.value);
+      signal?.removeEventListener?.("abort", abortListener);
+      child.stdout.removeAllListeners?.("data");
+      child.stderr.removeAllListeners?.("data");
+    };
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      terminate(child);
+      child.stdout.resume?.();
+      child.stderr.resume?.();
+      waitForClose(child).then(() => reject(error));
+    };
+    const finish = (code, signalName) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (code !== 0) {
+        reject(processError(E_BROWSER_VERIFICATION_EXECUTION_FAILED, `Agent Browser command failed (${code ?? "null"}/${signalName ?? "none"})`));
+        return;
+      }
+      resolve({
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stdoutBytes,
+        stderrBytes,
+      });
+    };
+    const abortListener = () => fail(processError(E_BROWSER_VERIFICATION_CANCELLED, "Agent Browser verification was cancelled"));
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += bytes(chunk);
+      if (stdoutBytes > maxStdoutBytes) {
+        fail(processError(E_BROWSER_VERIFICATION_OUTPUT_LIMIT, "Agent Browser stdout exceeded its bound"));
+        return;
+      }
+      stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += bytes(chunk);
+      if (stderrBytes > maxStderrBytes) fail(processError(E_BROWSER_VERIFICATION_OUTPUT_LIMIT, "Agent Browser stderr exceeded its bound"));
+    });
+    child.once?.("error", () => fail(processError(E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE, "Agent Browser process failed")));
+    child.once?.("close", finish);
+    signal?.addEventListener?.("abort", abortListener, { once: true });
+    timerRef.value = setTimeout(() => fail(processError(E_BROWSER_VERIFICATION_TIMEOUT, "Agent Browser command timed out")), timeoutMs);
+    timerRef.value.unref?.();
+  });
+}
+
+export function parseAgentBrowserJson(stdout, label = "Agent Browser response") {
+  if (typeof stdout !== "string" || stdout.length > AGENT_BROWSER_PROCESS_LIMITS.maxStdoutBytes) {
+    throw processError(E_BROWSER_VERIFICATION_OUTPUT_LIMIT, `${label} exceeded its bound`);
+  }
+  let value;
+  try { value = JSON.parse(stdout); } catch { throw processError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} was not valid JSON`); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw processError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} must be a JSON object`);
+  }
+  if (value.success !== true || !Object.prototype.hasOwnProperty.call(value, "data")
+    || Object.keys(value).some((key) => !["success", "data"].includes(key))) {
+    throw processError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} had an unsupported response envelope`);
+  }
+  return value.data === undefined ? value : value.data;
+}
+
+export { filteredEnvironment, processError as agentBrowserProcessError };

package/src/adapters/agent-browser/provider.js

@@ -0,0 +1,313 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  E_BROWSER_VERIFICATION_ORIGIN_DENIED,
+  E_BROWSER_VERIFICATION_CANCELLED,
+  E_BROWSER_VERIFICATION_EXECUTION_FAILED,
+  E_BROWSER_VERIFICATION_PROVIDER_INVALID,
+  E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE,
+  E_BROWSER_VERIFICATION_RESULT_INVALID,
+  E_BROWSER_VERIFICATION_TIMEOUT,
+  E_BROWSER_VERIFICATION_VERSION_UNSUPPORTED,
+} from "../../core/error-codes.js";
+import { assertAbsoluteRegularFile, parseAgentBrowserJson, runAgentBrowserCommand, AGENT_BROWSER_PROCESS_LIMITS } from "./process.js";
+import {
+  attributeCommand, clickCommand, closeCommand, fillCommand, focusCommand, openCommand,
+  pressCommand, screenshotCommand, snapshotCommand, textCommand, titleCommand, urlCommand, valueCommand,
+  versionCommand, visibleCommand,
+} from "./commands.js";
+import { resolveSnapshotLocator } from "./locator.js";
+import { observedScalar, assertionResult, matchesAssertion } from "./assertions.js";
+
+function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "AgentBrowserProviderError";
+  error.code = code;
+  return error;
+}
+
+function expectedVersion(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length === 0 || value.length > 64 || !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/u.test(value)) {
+    throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser expectedVersion is invalid");
+  }
+  return value;
+}
+
+function parseVersion(stdout) {
+  const match = /^\s*agent-browser\s+([^\s]+)(?:\s|$)/iu.exec(stdout);
+  if (!match) throw providerError(E_BROWSER_VERIFICATION_RESULT_INVALID, "Agent Browser version output was not qualified");
+  return match[1];
+}
+
+function remaining(deadline) {
+  const value = deadline - Date.now();
+  if (value < 1) throw providerError(E_BROWSER_VERIFICATION_TIMEOUT, "Agent Browser verification deadline expired");
+  return value;
+}
+
+function originOf(value) {
+  const parsed = new URL(value);
+  return `${parsed.protocol}//${parsed.hostname.toLowerCase()}${parsed.port ? `:${parsed.port}` : ""}`;
+}
+
+function verifyOrigin(value, allowedOrigins) {
+  let origin;
+  try { origin = originOf(value); } catch { throw providerError(E_BROWSER_VERIFICATION_ORIGIN_DENIED, "Agent Browser reported an invalid URL"); }
+  if (!allowedOrigins.includes(origin)) throw providerError(E_BROWSER_VERIFICATION_ORIGIN_DENIED, "Agent Browser left the allowed origins");
+  return value;
+}
+
+function dataValue(data, label) { return observedScalar(data, label); }
+
+function assertBooleanObservation(data, label) {
+  const value = dataValue(data, label);
+  if (value !== "true" && value !== "false") {
+    throw providerError(E_BROWSER_VERIFICATION_RESULT_INVALID, `${label} was not boolean`);
+  }
+  return value;
+}
+
+function isWithin(parent, child) {
+  const relative = path.relative(path.resolve(parent), path.resolve(child));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+
+function assertTempRootOutsideTarget(root, target) {
+  if (typeof target !== "string" || !path.isAbsolute(target)) return;
+  if (isWithin(target, root)) {
+    throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser tempRoot must be outside the verification target");
+  }
+}
+
+function resultWithAssertions(assertions, finalUrl, navigations, diagnostics = [], snapshots = [], artifacts = []) {
+  return { assertions, finalUrl, navigations, diagnostics, snapshots, artifacts };
+}
+
+function blockedAssertions(request, message) {
+  return request.assertions.map((assertion) => assertionResult(assertion, "BLOCKED", undefined, message));
+}
+
+async function createCwd(tempRoot, fsImpl, target) {
+  const root = tempRoot ?? os.tmpdir();
+  if (typeof root !== "string" || !path.isAbsolute(root)) throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser tempRoot must be absolute");
+  assertTempRootOutsideTarget(root, target);
+  const make = fsImpl?.mkdtemp ?? mkdtemp;
+  const cwd = await make(path.join(root, "forgeloop-agent-browser-"));
+  try {
+    if (typeof cwd !== "string" || !path.isAbsolute(cwd)) {
+      throw providerError(E_BROWSER_VERIFICATION_PROVIDER_INVALID, "Agent Browser temporary cwd is invalid");
+    }
+    assertTempRootOutsideTarget(cwd, target);
+  } catch (error) {
+    try { await fsImpl?.rm?.(cwd, { recursive: true, force: true }); } catch { /* preserve the boundary failure */ }
+    throw error;
+  }
+  return cwd;
+}
+
+function screenshotRef(verificationId, digest) { return `agent-browser/${verificationId}/${digest}.png`; }
+
+async function executeWait(step, { invoke, resolve, readUrl, deadline, clock }) {
+  const waitDeadline = Math.min(deadline, clock.now() + Math.max(100, Math.min(remaining(deadline), 5000)));
+  let satisfied = false;
+  while (!satisfied) {
+    if (clock.now() >= waitDeadline) throw providerError(E_BROWSER_VERIFICATION_TIMEOUT, "Agent Browser wait condition timed out");
+    if (step.condition === "VISIBLE" || step.condition === "HIDDEN") {
+      const visible = assertBooleanObservation(
+        await invoke(visibleCommand, { selector: await resolve(step.locator) }),
+        "Agent Browser visibility",
+      ) === "true";
+      satisfied = step.condition === "VISIBLE" ? visible : !visible;
+    } else if (step.condition === "TEXT_CONTAINS") {
+      const text = dataValue(await invoke(textCommand, { selector: await resolve(step.locator) }), "Agent Browser wait text");
+      satisfied = text.includes(step.expected ?? "");
+    } else {
+      const url = await readUrl();
+      satisfied = step.condition === "URL_IS" ? url === step.expected : url.startsWith(step.expected);
+    }
+    if (!satisfied) await new Promise((resolvePromise) => setTimeout(resolvePromise, Math.min(50, Math.max(1, waitDeadline - clock.now()))));
+  }
+}
+
+async function executeStep(step, helpers, navigations) {
+  const { invoke, resolve, readUrl } = helpers;
+  if (step.kind === "NAVIGATE") {
+    await invoke(openCommand, { url: step.url });
+    const observed = await readUrl();
+    navigations.push({ url: step.url, kind: "NAVIGATE" });
+    if (observed !== step.url) navigations.push({ url: observed, kind: "REDIRECT" });
+  } else if (step.kind === "CLICK") {
+    await invoke(clickCommand, { selector: await resolve(step.locator) });
+    await readUrl();
+  } else if (step.kind === "FILL") {
+    await invoke(fillCommand, { selector: await resolve(step.locator), text: step.text });
+    await readUrl();
+  } else if (step.kind === "PRESS") {
+    await invoke(focusCommand, { selector: await resolve(step.locator) });
+    await invoke(pressCommand, { key: step.key });
+    await readUrl();
+  } else if (step.kind === "WAIT_FOR") {
+    await executeWait(step, helpers);
+  }
+}
+
+async function executeSteps(request, helpers, navigations) {
+  for (const step of request.steps) await executeStep(step, helpers, navigations);
+}
+
+async function readAssertionValue(assertion, { invoke, resolve, readUrl }) {
+  if (assertion.kind === "VISIBLE" || assertion.kind === "HIDDEN") {
+    return assertBooleanObservation(await invoke(visibleCommand, { selector: await resolve(assertion.locator) }), "Agent Browser visibility");
+  }
+  if (assertion.kind === "TEXT_CONTAINS" || assertion.kind === "TEXT_EQUALS") {
+    return dataValue(await invoke(textCommand, { selector: await resolve(assertion.locator) }), "Agent Browser text");
+  }
+  if (assertion.kind === "VALUE_EQUALS") return dataValue(await invoke(valueCommand, { selector: await resolve(assertion.locator) }), "Agent Browser value");
+  if (assertion.kind === "ATTRIBUTE_EQUALS") {
+    return dataValue(await invoke(attributeCommand, { selector: await resolve(assertion.locator), attribute: assertion.attribute }), "Agent Browser attribute");
+  }
+  if (assertion.kind === "URL_IS" || assertion.kind === "URL_PREFIX") return readUrl();
+  return dataValue(await invoke(titleCommand), "Agent Browser title");
+}
+
+async function executeAssertions(request, helpers) {
+  const results = [];
+  for (const assertion of request.assertions) {
+    try {
+      const actual = await readAssertionValue(assertion, helpers);
+      results.push(assertionResult(assertion, matchesAssertion(assertion.kind, actual, assertion.expected) ? "PASS" : "FAIL", actual));
+    } catch (error) {
+      if (error.code === E_BROWSER_VERIFICATION_TIMEOUT) throw error;
+      results.push(assertionResult(assertion, "BLOCKED", undefined, "Browser observation was unavailable"));
+    }
+  }
+  return results;
+}
+
+async function captureScreenshot(request, { cwd, run, globals, fileSystem }, results, artifacts) {
+  const capture = request.capture?.screenshot ?? "NEVER";
+  const shouldCapture = capture === "ALWAYS" || (capture === "ON_FAILURE" && results.some((item) => item.status !== "PASS"));
+  if (!shouldCapture) return;
+  const outputPath = path.join(cwd, "verification.png");
+  await run(screenshotCommand({ ...globals, outputPath }));
+  const content = await fileSystem.readFile(outputPath);
+  const digest = crypto.createHash("sha256").update(content).digest("hex");
+  artifacts.push({ kind: "SCREENSHOT", mimeType: "image/png", byteLength: content.byteLength, sha256: digest, ref: screenshotRef(request.verificationId, digest) });
+}
+
+export function createAgentBrowserVerificationProvider({
+  executablePath,
+  expectedVersion: expected,
+  browserExecutablePath,
+  spawnImpl,
+  env,
+  fsImpl = null,
+  tempRoot,
+  clock = Date,
+} = {}) {
+  const fileSystem = fsImpl ?? {
+    lstatSync: fs.lstatSync.bind(fs),
+    statSync: fs.statSync.bind(fs),
+    mkdtemp,
+    readFile,
+    rm,
+  };
+  const executable = assertAbsoluteRegularFile(executablePath, "Agent Browser executable", fileSystem);
+  const expectedVersionValue = expectedVersion(expected);
+  if (browserExecutablePath !== undefined) assertAbsoluteRegularFile(browserExecutablePath, "Browser executable", fileSystem);
+
+  return Object.freeze({
+    id: "agent-browser",
+    async verify(request) {
+      const deadline = clock.now() + request.timeoutMs;
+      const sessionId = `forgeloop-${crypto.randomUUID()}`;
+      let cwd;
+      let closed = false;
+      const run = async (args, limit = AGENT_BROWSER_PROCESS_LIMITS.maxStdoutBytes) => {
+        const output = await runAgentBrowserCommand(executable, args, {
+          cwd,
+          timeoutMs: remaining(deadline),
+          signal: request.signal,
+          spawnImpl,
+          env: {
+            ...env,
+            ...(browserExecutablePath ? { AGENT_BROWSER_EXECUTABLE_PATH: browserExecutablePath } : {}),
+            AGENT_BROWSER_CONTENT_BOUNDARIES: "1",
+            AGENT_BROWSER_MAX_OUTPUT: String(AGENT_BROWSER_PROCESS_LIMITS.maxOutputChars),
+          },
+          maxStdoutBytes: limit,
+          fsImpl: fileSystem,
+          trustedEnvKeys: browserExecutablePath ? ["AGENT_BROWSER_EXECUTABLE_PATH"] : [],
+        });
+        return parseAgentBrowserJson(output.stdout);
+      };
+      const globals = { sessionId, allowedOrigins: request.allowedOrigins, maxOutputChars: AGENT_BROWSER_PROCESS_LIMITS.maxOutputChars };
+      const invoke = (builder, input = {}) => run(builder({ ...globals, ...input }));
+      const snapshots = [];
+      const navigations = [];
+      const diagnostics = [];
+      const artifacts = [];
+      let currentUrl = request.startUrl;
+      try {
+        cwd = await createCwd(tempRoot, fileSystem, request.target);
+        const versionOutput = await runAgentBrowserCommand(executable, versionCommand(), {
+          cwd, timeoutMs: remaining(deadline), signal: request.signal, spawnImpl, env,
+          maxStdoutBytes: AGENT_BROWSER_PROCESS_LIMITS.maxVersionBytes,
+          fsImpl: fileSystem,
+        });
+        const version = parseVersion(versionOutput.stdout);
+        if (expectedVersionValue !== undefined && version !== expectedVersionValue) {
+          throw providerError(E_BROWSER_VERIFICATION_VERSION_UNSUPPORTED, "Agent Browser version does not match expectedVersion");
+        }
+
+        const readUrl = async () => {
+          const value = dataValue(await invoke(urlCommand), "Agent Browser URL");
+          currentUrl = verifyOrigin(value, request.allowedOrigins);
+          return currentUrl;
+        };
+        const readSnapshot = async () => {
+          const value = await invoke(snapshotCommand);
+          snapshots.push({ kind: "ACCESSIBILITY", text: typeof value === "string" ? value : JSON.stringify(value) });
+          return value;
+        };
+        const resolve = async (locator) => resolveSnapshotLocator(locator, await readSnapshot());
+        const helpers = { invoke, resolve, readUrl, deadline, clock };
+        await invoke(openCommand, { url: request.startUrl });
+        const initialUrl = await readUrl();
+        navigations.push({ url: request.startUrl, kind: "NAVIGATE" });
+        if (initialUrl !== request.startUrl) navigations.push({ url: initialUrl, kind: "REDIRECT" });
+        await executeSteps(request, helpers, navigations);
+        const results = await executeAssertions(request, helpers);
+        await captureScreenshot(request, { cwd, run, globals, fileSystem }, results, artifacts);
+        currentUrl = await readUrl();
+        return resultWithAssertions(results, currentUrl, navigations, diagnostics, snapshots, artifacts);
+      } catch (error) {
+        if ([E_BROWSER_VERIFICATION_TIMEOUT, E_BROWSER_VERIFICATION_CANCELLED, E_BROWSER_VERIFICATION_ORIGIN_DENIED,
+          E_BROWSER_VERIFICATION_PROVIDER_INVALID, E_BROWSER_VERIFICATION_VERSION_UNSUPPORTED].includes(error.code)) throw error;
+        if (error.code === E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE) throw error;
+        if (error.code === E_BROWSER_VERIFICATION_EXECUTION_FAILED) throw error;
+        return { assertions: blockedAssertions(request, "Browser verification could not complete"), finalUrl: currentUrl, navigations, diagnostics, snapshots, artifacts };
+      } finally {
+        if (cwd && !closed) {
+          closed = true;
+          try {
+            await runAgentBrowserCommand(executable, closeCommand({ ...globals }), {
+              cwd,
+              timeoutMs: Math.max(1, Math.min(Math.max(1, deadline - Date.now()), 1000)),
+              signal: undefined,
+              spawnImpl,
+              env,
+              fsImpl: fileSystem,
+            });
+          } catch { /* cleanup is best effort and never leaks process data */ }
+          try { await fileSystem.rm(cwd, { recursive: true, force: true }); } catch { /* temp cleanup is bounded and non-authoritative */ }
+        }
+      }
+    },
+  });
+}