@ap3x/browser-agent 0.1.0

package/dist/index.js

@@ -0,0 +1,1070 @@
+import {
+  agentStep,
+  collectingLogger,
+  emptyLlmResponse,
+  invalidLlmResponse,
+  scriptedLlm,
+  transportErrorResponse,
+  truncatedLlmResponse
+} from "./chunk-32HNRAQS.js";
+import {
+  Agent,
+  AgentEventStream,
+  AgentHistoryList,
+  BUILTIN_ACTIONS,
+  COMPACT_EVERY_N_STEPS,
+  COMPACT_TRIGGER_CHARS,
+  CaptchaWatchdog,
+  FileParseError,
+  FileSystem,
+  JudgementResultSchema,
+  LoopDetector,
+  MessageManager,
+  Registry,
+  StepLoop,
+  UsageLedger,
+  anySignal,
+  applicablePlaceholders,
+  assembleNarration,
+  budgetNudge,
+  buildAgentOutputSchema,
+  createBrowserMcpServer,
+  createDefaultRegistry,
+  createLogger,
+  defineAction,
+  detectCaptcha,
+  doneResult,
+  encodeFramesToGif,
+  generateRunGif,
+  generateRunVideoGif,
+  isDoneResult,
+  judgeRun,
+  logStderr,
+  maskOutbound,
+  maskSecretMap,
+  multiAct,
+  parseAction,
+  perceive,
+  readExternalFile,
+  registerBuiltins,
+  resolveSecretsForUrl,
+  resultsAreDone,
+  runBrowserMcpServer,
+  sanitizeFilename,
+  sensitiveDataDescription,
+  silentLogger,
+  stepDurationSeconds,
+  stepResult,
+  substituteSecrets,
+  toTypedAction,
+  totp
+} from "./chunk-UZALZUEE.js";
+
+// src/agent/backend.ts
+var EMPTY_USAGE = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+};
+function mapUsage(summary) {
+  if (!summary) return EMPTY_USAGE;
+  let input = 0;
+  let output = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  for (const model of summary.perModel) {
+    input += model.input;
+    output += model.output;
+    cacheRead += model.cacheRead;
+    cacheWrite += model.cacheWrite;
+  }
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    totalTokens: summary.totalTokens,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: summary.totalCost }
+  };
+}
+function toTaskText(task) {
+  if (typeof task === "string") return task;
+  const parts = [];
+  for (const message of task) {
+    const content = message.content;
+    if (typeof content === "string") {
+      parts.push(content);
+    } else if (Array.isArray(content)) {
+      for (const block of content) {
+        if (block && typeof block === "object" && "text" in block) {
+          parts.push(String(block.text));
+        }
+      }
+    }
+  }
+  return parts.join("\n");
+}
+function toToolResult(event) {
+  const { result } = event;
+  const text = result.error ?? result.extractedContent ?? result.longTermMemory ?? "";
+  return {
+    role: "toolResult",
+    toolCallId: `${event.step}:${event.index}`,
+    toolName: event.name,
+    content: text ? [{ type: "text", text }] : [],
+    isError: result.error !== void 0,
+    timestamp: Date.now()
+  };
+}
+function bridgeEvent(event) {
+  switch (event.type) {
+    case "run-started":
+      return { type: "agent_start" };
+    case "step-started":
+      return { type: "turn_start" };
+    case "action-started":
+      return {
+        type: "tool_execution_start",
+        toolCallId: `${event.step}:${event.index}`,
+        toolName: event.name,
+        args: event.params
+      };
+    case "action-finished":
+      return {
+        type: "tool_execution_end",
+        toolCallId: `${event.step}:${event.index}`,
+        toolName: event.name,
+        result: toToolResult(event),
+        isError: event.result.error !== void 0
+      };
+    case "done":
+    case "error":
+      return { type: "agent_end", messages: [] };
+    case "model-thought":
+      return void 0;
+    case "step-finished":
+      return void 0;
+    case "paused":
+    case "resumed":
+      return void 0;
+    case "captcha-detected":
+      return void 0;
+    default:
+      return event;
+  }
+}
+var BrowserAgentBackend = class {
+  source;
+  model;
+  listeners = /* @__PURE__ */ new Set();
+  active;
+  constructor(source) {
+    this.source = source;
+    this.model = source instanceof Agent ? source.currentModel : source.llm.model;
+  }
+  agentFor(task) {
+    return this.source instanceof Agent ? this.source : new Agent(task, this.source);
+  }
+  async run(task, opts) {
+    const taskText = toTaskText(task);
+    const agent = this.agentFor(taskText);
+    this.active = agent;
+    const pump = this.listeners.size > 0 ? this.pumpEvents(agent) : void 0;
+    try {
+      const history = await agent.run({ signal: opts?.signal });
+      await pump;
+      return this.toRunResult(taskText, history, opts?.signal?.aborted === true);
+    } finally {
+      this.active = void 0;
+    }
+  }
+  /** Drain the O2 stream, translating each event to a subscribed agent-core listener. */
+  async pumpEvents(agent) {
+    for await (const event of agent.events()) {
+      const mapped = bridgeEvent(event);
+      if (!mapped) continue;
+      for (const listener of this.listeners) await listener(mapped);
+    }
+  }
+  toRunResult(task, history, aborted) {
+    const finalText = history.finalResult() ?? "";
+    const usage = mapUsage(history.usage);
+    const stopReason = stopReasonFor(history, aborted);
+    const failed = stopReason !== "stop";
+    return {
+      messages: buildMessages(task, finalText, this.model, usage, stopReason),
+      finalText,
+      usage,
+      stopReason,
+      errorMessage: failed ? finalText || `run stopped: ${stopReason}` : void 0
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  abort() {
+    this.active?.stop();
+  }
+  supports(capability) {
+    return capability === "subscribe" || capability === "abort";
+  }
+  getCurrentModel() {
+    return this.model;
+  }
+};
+function stopReasonFor(history, aborted) {
+  if (aborted || history.terminationReason === "aborted") return "aborted";
+  if (!history.isDone()) return "error";
+  if (history.terminationReason === "max_steps" || history.terminationReason === "run_timeout")
+    return "length";
+  return "stop";
+}
+function buildMessages(task, finalText, model, usage, stopReason) {
+  const now = Date.now();
+  return [
+    { role: "user", content: task, timestamp: now },
+    {
+      role: "assistant",
+      content: finalText ? [{ type: "text", text: finalText }] : [],
+      api: model.api,
+      provider: model.provider,
+      model: model.id,
+      usage,
+      stopReason,
+      timestamp: now
+    }
+  ];
+}
+
+// src/mcp/client.ts
+import { AgentMCPConnectionError } from "@ap3x/agent-core";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Type } from "@sinclair/typebox";
+var UNCONVERTIBLE_KEYS = ["$ref", "allOf", "anyOf", "oneOf", "not"];
+function leafSchema(prop) {
+  const type = typeof prop === "object" && prop !== null ? prop.type : void 0;
+  switch (type) {
+    case "string":
+      return Type.String();
+    case "number":
+      return Type.Number();
+    case "integer":
+      return Type.Integer();
+    case "boolean":
+      return Type.Boolean();
+    case "array":
+      return Type.Array(Type.Unknown());
+    case "object":
+      return Type.Object({}, { additionalProperties: true });
+    default:
+      return Type.Unknown();
+  }
+}
+function synthesizeParamSchema(inputSchema) {
+  if (typeof inputSchema !== "object" || inputSchema === null) return void 0;
+  const schema = inputSchema;
+  if (schema.type !== "object") return void 0;
+  if (UNCONVERTIBLE_KEYS.some((key) => key in schema)) return void 0;
+  const properties = typeof schema.properties === "object" && schema.properties !== null ? schema.properties : {};
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const shape = {};
+  for (const [key, prop] of Object.entries(properties)) {
+    const leaf = leafSchema(prop);
+    shape[key] = required.includes(key) ? leaf : Type.Optional(leaf);
+  }
+  return Type.Object(shape, { additionalProperties: schema.additionalProperties === true });
+}
+function flattenContent(content) {
+  const parts = Array.isArray(content) ? content : [];
+  const texts = [];
+  const images = [];
+  for (const part of parts) {
+    if (typeof part !== "object" || part === null) continue;
+    const p = part;
+    if (p.type === "text" && typeof p.text === "string") texts.push(p.text);
+    else if (p.type === "image" && typeof p.data === "string")
+      images.push({ name: "image", data: p.data });
+  }
+  return { text: texts.join("\n"), images };
+}
+function mcpToolAction(client, toolName, description, schema, prefix) {
+  return defineAction({
+    name: `${prefix}${toolName}`,
+    description,
+    schema,
+    async execute(params, _ctx) {
+      try {
+        const result = await client.callTool({
+          name: toolName,
+          arguments: params ?? {}
+        });
+        const { text, images } = flattenContent(result.content);
+        if (result.isError === true) {
+          return stepResult({ error: text || `MCP tool "${toolName}" reported an error` });
+        }
+        return stepResult({
+          extractedContent: text,
+          includeExtractedContentOnlyOnce: true,
+          longTermMemory: `Used MCP tool "${toolName}"`,
+          images: images.length > 0 ? images : void 0
+        });
+      } catch (error) {
+        return stepResult({
+          error: `MCP tool "${toolName}" failed: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+    }
+  });
+}
+async function importMcpTools(client, options = {}) {
+  const prefix = options.prefix ?? "";
+  const { tools } = await client.listTools();
+  const actions = [];
+  for (const tool of tools) {
+    if (options.toolFilter && !options.toolFilter(tool.name)) continue;
+    const schema = synthesizeParamSchema(tool.inputSchema);
+    if (!schema) {
+      logStderr(`skipping MCP tool "${tool.name}": input schema could not be converted`);
+      continue;
+    }
+    actions.push(
+      mcpToolAction(
+        client,
+        tool.name,
+        tool.description ?? `MCP tool "${tool.name}"`,
+        schema,
+        prefix
+      )
+    );
+  }
+  return actions;
+}
+async function connectMcpClient(connection) {
+  const client = new Client(
+    {
+      name: connection.clientInfo?.name ?? "ap3x-browser-agent",
+      version: connection.clientInfo?.version ?? "0.1.0"
+    },
+    { capabilities: {} }
+  );
+  const transport = new StdioClientTransport({
+    command: connection.command,
+    args: connection.args,
+    env: connection.env
+  });
+  try {
+    await client.connect(transport);
+  } catch (error) {
+    throw new AgentMCPConnectionError(
+      `Failed to connect to MCP server "${connection.command}": ${error instanceof Error ? error.message : String(error)}`,
+      error
+    );
+  }
+  return client;
+}
+
+// src/agent/rematch.ts
+import {
+  MatchLevel,
+  elementHash,
+  xpath as nodeXpath,
+  parentBranchHash,
+  stableHash
+} from "@ap3x/browser";
+var UNIQUE_ATTRIBUTES = ["name", "id", "aria-label"];
+var DIAGNOSTIC_CANDIDATE_LIMIT = 5;
+function findBy(selectorMap, predicate) {
+  for (const entry of selectorMap) {
+    if (predicate(entry[1])) return entry;
+  }
+  return void 0;
+}
+function candidateLabel(node) {
+  const label = node.axNode?.name ?? node.attributes["aria-label"] ?? node.attributes.name ?? node.attributes.id ?? "";
+  return `[${node.backendNodeId}]<${node.nodeName.toLowerCase()}>${label ? ` "${label}"` : ""}`;
+}
+function diagnosticFor(recorded, selectorMap) {
+  const tag = recorded.nodeName.toLowerCase();
+  const sought = recorded.axName ?? recorded.attributes["aria-label"] ?? recorded.attributes.name ?? recorded.attributes.id ?? recorded.xpath;
+  const similar = [...selectorMap.values()].filter((node) => node.nodeName.toLowerCase() === tag).slice(0, DIAGNOSTIC_CANDIDATE_LIMIT).map(candidateLabel);
+  const similarText = similar.length > 0 ? `Similar <${tag}> elements present: ${similar.join(", ")}.` : `No <${tag}> elements found on the current page.`;
+  return `Could not re-match recorded element <${tag}> "${sought}" (xpath: ${recorded.xpath}). ${similarText}`;
+}
+function rematchElement(recorded, selectorMap) {
+  const exact = findBy(selectorMap, (node) => elementHash(node) === recorded.elementHash);
+  if (exact) return { level: MatchLevel.Exact, backendNodeId: exact[0], node: exact[1] };
+  const stable = findBy(selectorMap, (node) => stableHash(node) === recorded.stableHash);
+  if (stable) return { level: MatchLevel.Stable, backendNodeId: stable[0], node: stable[1] };
+  const xp = findBy(selectorMap, (node) => nodeXpath(node) === recorded.xpath);
+  if (xp) return { level: MatchLevel.Xpath, backendNodeId: xp[0], node: xp[1] };
+  const recordedTag = recorded.nodeName.toLowerCase();
+  if (recorded.axName) {
+    const byAx = findBy(
+      selectorMap,
+      (node) => node.nodeName.toLowerCase() === recordedTag && node.axNode?.name === recorded.axName
+    );
+    if (byAx) return { level: MatchLevel.AxName, backendNodeId: byAx[0], node: byAx[1] };
+  }
+  for (const attr of UNIQUE_ATTRIBUTES) {
+    const wanted = recorded.attributes[attr];
+    if (!wanted) continue;
+    const matches = [];
+    for (const entry of selectorMap) {
+      if (entry[1].attributes[attr] === wanted && entry[1].nodeName.toLowerCase() === recordedTag)
+        matches.push(entry);
+    }
+    if (matches.length === 1) {
+      const [backendNodeId, node] = matches[0];
+      return { level: MatchLevel.Attribute, backendNodeId, node };
+    }
+  }
+  if (recorded.parentBranchHash) {
+    const structuralMatches = [];
+    for (const entry of selectorMap) {
+      if (parentBranchHash(entry[1]) === recorded.parentBranchHash) structuralMatches.push(entry);
+    }
+    if (structuralMatches.length === 1) {
+      const [backendNodeId, node] = structuralMatches[0];
+      return { level: MatchLevel.Structural, backendNodeId, node };
+    }
+  }
+  return { level: void 0, diagnostic: diagnosticFor(recorded, selectorMap) };
+}
+function looksLikeMenuOpener(el) {
+  const attrs = el.attributes;
+  if (attrs["aria-haspopup"] !== void 0 || attrs["aria-expanded"] !== void 0) return true;
+  const cls = (attrs.class ?? "").toLowerCase();
+  return cls.includes("menu") || cls.includes("dropdown");
+}
+function looksLikeMenuItem(el) {
+  const role = el.attributes.role?.toLowerCase();
+  if (role === "menuitem" || role === "option") return true;
+  const cls = (el.attributes.class ?? "").toLowerCase();
+  return cls.includes("menu-item") || cls.includes("dropdown-item");
+}
+
+// src/agent/variable-detector.ts
+var HTML5_TYPE_NAMES = {
+  email: "email",
+  tel: "phone",
+  date: "date",
+  number: "number",
+  url: "url"
+};
+var KEYWORD_MAP = [
+  ["billing_address", "address"],
+  ["billing-address", "address"],
+  ["shipping_address", "address"],
+  ["shipping-address", "address"],
+  ["address", "address"],
+  ["comment", "comment"],
+  ["email", "email"],
+  ["phone", "phone"],
+  ["first_name", "first_name"],
+  ["firstname", "first_name"],
+  ["last_name", "last_name"],
+  ["lastname", "last_name"],
+  ["full_name", "full_name"],
+  ["fullname", "full_name"],
+  ["city", "city"],
+  ["state", "state"],
+  ["country", "country"],
+  ["postal", "zip"],
+  ["zip", "zip"],
+  ["company", "company"],
+  ["date", "date"],
+  ["name", "full_name"]
+];
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var CAPITALIZED_WORDS_RE = /^[A-Z][a-zA-Z]{1,29}(\s[A-Z][a-zA-Z]{1,29})?$/;
+function digitsOnly(value) {
+  return value.replace(/\D/g, "");
+}
+function attributeBasedName(el) {
+  if (!el) return void 0;
+  const type = el.attributes.type?.toLowerCase();
+  if (type && HTML5_TYPE_NAMES[type]) return HTML5_TYPE_NAMES[type];
+  const haystacks = [
+    el.attributes.id,
+    el.attributes.name,
+    el.attributes.placeholder,
+    el.attributes["aria-label"]
+  ].filter((v) => !!v).map((v) => v.toLowerCase());
+  for (const [keyword, varName] of KEYWORD_MAP) {
+    if (haystacks.some((h) => h.includes(keyword))) return varName;
+  }
+  return void 0;
+}
+function patternBasedName(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  if (EMAIL_RE.test(trimmed)) return "email";
+  if (digitsOnly(trimmed).length >= 10) return "phone";
+  if (DATE_RE.test(trimmed)) return "date";
+  if (CAPITALIZED_WORDS_RE.test(trimmed)) return trimmed.includes(" ") ? "full_name" : "first_name";
+  if (/^\d{1,9}$/.test(trimmed)) return "number";
+  return void 0;
+}
+function detectVariables(history) {
+  const detected = [];
+  const nameForValue = /* @__PURE__ */ new Map();
+  const usedNames = /* @__PURE__ */ new Set();
+  const nameFor = (base, value) => {
+    const existing = nameForValue.get(value);
+    if (existing) return existing;
+    let candidate = base;
+    let n = 2;
+    while (usedNames.has(candidate)) {
+      candidate = `${base}_${n}`;
+      n += 1;
+    }
+    usedNames.add(candidate);
+    nameForValue.set(value, candidate);
+    return candidate;
+  };
+  history.history.forEach((step, stepIndex) => {
+    const actions = step.modelOutput?.action ?? [];
+    actions.forEach((raw, actionIndex) => {
+      const parsed = parseAction(raw);
+      if (!parsed) return;
+      const param = typeof parsed.params.text === "string" ? "text" : typeof parsed.params.query === "string" ? "query" : void 0;
+      if (!param) return;
+      const value = parsed.params[param];
+      if (!value) return;
+      const el = step.state.interactedElements?.[actionIndex];
+      const base = attributeBasedName(el) ?? patternBasedName(value);
+      if (!base) return;
+      detected.push({ name: nameFor(base, value), value, stepIndex, actionIndex, param });
+    });
+  });
+  return detected;
+}
+function substituteVariables(history, detected, values) {
+  const copy = history.toJSON();
+  const clone = structuredClone(copy);
+  for (const variable of detected) {
+    const replacement = values[variable.name];
+    if (replacement === void 0) continue;
+    const step = clone.history[variable.stepIndex];
+    const action = step?.modelOutput?.action[variable.actionIndex];
+    if (!action) continue;
+    const parsed = parseAction(action);
+    if (!parsed) continue;
+    const current = parsed.params[variable.param];
+    if (typeof current !== "string") continue;
+    parsed.params[variable.param] = current.split(variable.value).join(replacement);
+  }
+  return AgentHistoryList.fromJSON(clone);
+}
+
+// src/agent/replay.ts
+import { readFile, writeFile } from "fs/promises";
+import {
+  complete,
+  generateObject
+} from "@ap3x/ai";
+import { Type as Type2 } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_MS = 5e3;
+var DEFAULT_RETRY_CAP_MS = 3e4;
+var DEFAULT_STEP_DELAY_MS = 2e3;
+var DEFAULT_MAX_STEP_INTERVAL_MS = 45e3;
+var MENU_REOPEN_SETTLE_MS = 500;
+var DEFAULT_STEP_TIMEOUT_MS = 18e4;
+function realSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function abortableSleep(ms, sleep, signal) {
+  if (!signal) return sleep(ms);
+  if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(new DOMException("Aborted", "AbortError"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    sleep(ms).then(
+      () => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+var StepMetadataSchema = Type2.Object({
+  stepStartTime: Type2.Number(),
+  stepEndTime: Type2.Number(),
+  stepNumber: Type2.Number(),
+  stepInterval: Type2.Optional(Type2.Number())
+});
+var ActionResultSchema = Type2.Object({
+  isDone: Type2.Optional(Type2.Boolean()),
+  success: Type2.Optional(Type2.Boolean()),
+  error: Type2.Optional(Type2.String()),
+  extractedContent: Type2.Optional(Type2.String()),
+  includeExtractedContentOnlyOnce: Type2.Optional(Type2.Boolean()),
+  longTermMemory: Type2.Optional(Type2.String()),
+  attachments: Type2.Optional(Type2.Array(Type2.String())),
+  images: Type2.Optional(Type2.Array(Type2.Object({ name: Type2.String(), data: Type2.String() }))),
+  metadata: Type2.Optional(Type2.Record(Type2.String(), Type2.Unknown())),
+  includeInMemory: Type2.Optional(Type2.Boolean())
+});
+var InteractedElementSchema = Type2.Object({
+  nodeId: Type2.Number(),
+  backendNodeId: Type2.Number(),
+  frameId: Type2.Optional(Type2.String()),
+  nodeType: Type2.Number(),
+  nodeValue: Type2.String(),
+  nodeName: Type2.String(),
+  attributes: Type2.Record(Type2.String(), Type2.String()),
+  bounds: Type2.Optional(
+    Type2.Object({
+      x: Type2.Number(),
+      y: Type2.Number(),
+      width: Type2.Number(),
+      height: Type2.Number()
+    })
+  ),
+  xpath: Type2.String(),
+  elementHash: Type2.String(),
+  stableHash: Type2.String(),
+  axName: Type2.Optional(Type2.String()),
+  // Optional: absent on history files recorded before W13c (structural rematch
+  // level has nothing to fall back to for those — the cascade just skips it).
+  parentBranchHash: Type2.Optional(Type2.String())
+});
+var BrowserStateHistorySchema = Type2.Object({
+  url: Type2.String(),
+  title: Type2.String(),
+  tabs: Type2.Array(
+    Type2.Object({
+      id: Type2.String(),
+      url: Type2.String(),
+      title: Type2.String(),
+      parentId: Type2.Optional(Type2.String())
+    })
+  ),
+  screenshot: Type2.Optional(Type2.String()),
+  // `undefined` array entries (non-indexed actions: scroll/navigate/wait/done/…)
+  // serialize through `JSON.stringify` as `null` — `Type.Optional` inside
+  // `Type.Array` does NOT accept that (Optional only applies to object
+  // properties), so a real save→load round-trip must accept `null` explicitly.
+  // `AgentHistoryList.fromJSON` normalizes `null` back to `undefined` on load.
+  interactedElements: Type2.Optional(Type2.Array(Type2.Union([InteractedElementSchema, Type2.Null()])))
+});
+var AgentHistoryItemSchema = Type2.Object({
+  modelOutput: Type2.Optional(
+    Type2.Object({
+      thinking: Type2.Optional(Type2.String()),
+      evaluation_previous_goal: Type2.Optional(Type2.String()),
+      memory: Type2.Optional(Type2.String()),
+      next_goal: Type2.Optional(Type2.String()),
+      action: Type2.Array(Type2.Record(Type2.String(), Type2.Unknown()))
+    })
+  ),
+  result: Type2.Array(ActionResultSchema),
+  state: BrowserStateHistorySchema,
+  metadata: Type2.Optional(StepMetadataSchema),
+  stateMessage: Type2.Optional(Type2.String())
+});
+var HistoryFileSchema = Type2.Object({
+  version: Type2.Literal(1),
+  history: Type2.Array(AgentHistoryItemSchema),
+  terminationReason: Type2.Optional(Type2.String())
+});
+function firstSchemaError(value) {
+  const [error] = [...Value.Errors(HistoryFileSchema, value)];
+  return error ? `${error.path || "/"}: ${error.message}` : "does not match the history-file schema";
+}
+async function saveHistoryToFile(history, filePath) {
+  await writeFile(filePath, JSON.stringify(history.toJSON(), null, 2), "utf8");
+}
+async function loadHistoryFromFile(filePath) {
+  const raw = await readFile(filePath, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `History file "${filePath}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!Value.Check(HistoryFileSchema, parsed)) {
+    throw new Error(
+      `History file "${filePath}" failed schema validation: ${firstSchemaError(parsed)}`
+    );
+  }
+  const file = parsed;
+  file.history.forEach((item, i) => {
+    const stepNumber = item.metadata?.stepNumber ?? i + 1;
+    for (const action of item.modelOutput?.action ?? []) {
+      if (!parseAction(action)) {
+        throw new Error(
+          `History file "${filePath}" step ${stepNumber} has a malformed action (expected exactly one key): ${JSON.stringify(action)}`
+        );
+      }
+    }
+  });
+  return AgentHistoryList.fromJSON(file);
+}
+var RerunSummarySchema = Type2.Object({
+  summary: Type2.String(),
+  success: Type2.Boolean(),
+  completionStatus: Type2.Union([
+    Type2.Literal("full"),
+    Type2.Literal("partial"),
+    Type2.Literal("failed")
+  ])
+});
+function nonLlmSummary(succeeded, total) {
+  const completionStatus = total === 0 || succeeded === total ? "full" : succeeded === 0 ? "failed" : "partial";
+  return {
+    summary: `${succeeded}/${total} steps succeeded.`,
+    success: total > 0 && succeeded === total,
+    completionStatus
+  };
+}
+async function buildRerunSummary(task, steps, succeeded, total, model, signal, streamOptions) {
+  const fallback = nonLlmSummary(succeeded, total);
+  if (!model) return { ...fallback, summarySource: "fallback" };
+  const statLines = steps.map((s) => `Step ${s.stepNumber}: ${s.outcome}${s.error ? ` (${s.error})` : ""}`).join("\n");
+  const prompt = [
+    "You are summarizing a REPLAY of a previously recorded browser-agent run.",
+    `Original task: ${task}`,
+    `Result: ${succeeded}/${total} steps replayed successfully.`,
+    "Per-step outcomes:",
+    statLines,
+    "Write a short summary of what happened, whether the replay succeeded overall, and a completion status."
+  ].join("\n\n");
+  const messages = [{ role: "user", content: prompt, timestamp: Date.now() }];
+  try {
+    const { object } = await generateObject(model, messages, RerunSummarySchema, {
+      ...streamOptions,
+      signal
+    });
+    return { ...object, summarySource: "llm" };
+  } catch {
+    try {
+      const response = await complete(model, { messages }, { ...streamOptions, signal });
+      const text = response.content.filter((b) => b.type === "text").map((b) => b.text).join("").trim();
+      if (text)
+        return {
+          summary: text,
+          success: fallback.success,
+          completionStatus: fallback.completionStatus,
+          summarySource: "plain-text"
+        };
+    } catch {
+    }
+    return { ...fallback, summarySource: "fallback" };
+  }
+}
+var ReplayStepError = class extends Error {
+  constructor(message, results, matchLevels) {
+    super(message);
+    this.results = results;
+    this.matchLevels = matchLevels;
+    this.name = "ReplayStepError";
+  }
+  results;
+  matchLevels;
+};
+function buildCtx(deps, pageUrl, signal) {
+  return {
+    session: deps.session,
+    driver: deps.driver,
+    pageUrl,
+    fileSystem: deps.fileSystem,
+    extractionLlm: deps.extractionLlm,
+    availableFilePaths: deps.availableFilePaths ?? [],
+    hasSensitiveData: false,
+    signal
+  };
+}
+function stepIdentity(item) {
+  const actions = item.modelOutput?.action ?? [];
+  if (actions.length !== 1) return void 0;
+  const parsed = parseAction(actions[0]);
+  if (!parsed) return void 0;
+  const element = item.state.interactedElements?.[0];
+  if (!element) return void 0;
+  return { actionName: parsed.name, element };
+}
+function sameElement(a, b) {
+  return a.elementHash === b.elementHash || a.stableHash === b.stableHash || a.xpath === b.xpath;
+}
+async function replayStepOnce(item, deps, previousOpener, signal, sleep, reopenState) {
+  const actions = item.modelOutput?.action ?? [];
+  const state = await deps.driver.getState();
+  const matchLevels = [];
+  const results = [];
+  let queued = [];
+  const ctx = buildCtx(deps, state.url, signal);
+  const flush = async () => {
+    if (queued.length === 0) return;
+    const batch = queued;
+    queued = [];
+    const batchResults = await multiAct({
+      actions: batch,
+      registry: deps.registry,
+      ctx,
+      session: deps.session,
+      signal
+    });
+    results.push(...batchResults);
+    const failed = batchResults.find((r) => r.error !== void 0);
+    if (failed) throw new ReplayStepError(failed.error, results, matchLevels);
+  };
+  for (let i = 0; i < actions.length; i++) {
+    const raw = actions[i];
+    const parsed = parseAction(raw);
+    if (!parsed) {
+      matchLevels.push(void 0);
+      continue;
+    }
+    if (parsed.name === "extract_content") {
+      await flush();
+      const result = await deps.registry.execute("extract_content", parsed.params, ctx);
+      results.push(result);
+      matchLevels.push(void 0);
+      if (result.error !== void 0) throw new ReplayStepError(result.error, results, matchLevels);
+      continue;
+    }
+    const recorded = item.state.interactedElements?.[i];
+    if (recorded && typeof parsed.params.index === "number") {
+      let match = rematchElement(recorded, state.selectorMap);
+      if (!match.level && !reopenState.done && previousOpener && looksLikeMenuItem(recorded)) {
+        reopenState.done = true;
+        const openerMatch = rematchElement(previousOpener.recorded, state.selectorMap);
+        if (openerMatch.level) {
+          await deps.registry.execute(
+            "click",
+            { ...previousOpener.params, index: openerMatch.backendNodeId },
+            ctx
+          );
+          await abortableSleep(MENU_REOPEN_SETTLE_MS, sleep, signal);
+          const fresh = await deps.driver.getState();
+          match = rematchElement(recorded, fresh.selectorMap);
+        }
+      }
+      if (!match.level) {
+        matchLevels.push(void 0);
+        throw new ReplayStepError(
+          match.diagnostic,
+          [...results, stepResult({ error: match.diagnostic })],
+          matchLevels
+        );
+      }
+      matchLevels.push(match.level);
+      queued.push({ ...raw, [parsed.name]: { ...parsed.params, index: match.backendNodeId } });
+    } else {
+      matchLevels.push(void 0);
+      queued.push(raw);
+    }
+  }
+  await flush();
+  return { matchLevels, results };
+}
+function backoffMs(attempt, base, cap) {
+  return Math.min(base * 2 ** (attempt - 1), cap);
+}
+async function rerunHistory(history, deps, options = {}) {
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const retryBaseMs = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+  const retryCapMs = options.retryCapMs ?? DEFAULT_RETRY_CAP_MS;
+  const defaultStepDelayMs = options.defaultStepDelayMs ?? DEFAULT_STEP_DELAY_MS;
+  const maxStepIntervalMs = options.maxStepIntervalMs ?? DEFAULT_MAX_STEP_INTERVAL_MS;
+  const stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+  const skipFailures = options.skipFailures ?? false;
+  const sleep = options.sleep ?? realSleep;
+  const signal = options.signal;
+  const log = deps.logger ?? silentLogger;
+  const steps = [];
+  let lastSuccessful;
+  let previousOpener;
+  for (let i = 0; i < history.history.length; i++) {
+    const item = history.history[i];
+    const stepNumber = item.metadata?.stepNumber ?? i + 1;
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    if (skipFailures && item.result.some((r) => r.error !== void 0)) {
+      steps.push({ stepNumber, outcome: "skipped-original-error", matchLevels: [], attempts: 0 });
+      continue;
+    }
+    const actions = item.modelOutput?.action ?? [];
+    if (actions.length === 0) {
+      steps.push({ stepNumber, outcome: "skipped-no-actions", matchLevels: [], attempts: 0 });
+      continue;
+    }
+    const identity = stepIdentity(item);
+    if (identity && lastSuccessful && identity.actionName === lastSuccessful.actionName && sameElement(identity.element, lastSuccessful.element)) {
+      steps.push({ stepNumber, outcome: "skipped-redundant", matchLevels: [], attempts: 0 });
+      continue;
+    }
+    if (i > 0) {
+      const savedMs = (item.metadata?.stepInterval ?? 0) * 1e3;
+      await abortableSleep(
+        savedMs > 0 ? Math.min(savedMs, maxStepIntervalMs) : defaultStepDelayMs,
+        sleep,
+        signal
+      );
+    }
+    let attempt = 0;
+    let outcome;
+    const reopenState = { done: false };
+    while (!outcome) {
+      const attemptSignal = anySignal(signal, AbortSignal.timeout(stepTimeoutMs));
+      try {
+        const { matchLevels, results } = await replayStepOnce(
+          item,
+          deps,
+          previousOpener,
+          attemptSignal,
+          sleep,
+          reopenState
+        );
+        outcome = { stepNumber, outcome: "replayed", matchLevels, results, attempts: attempt + 1 };
+        lastSuccessful = identity;
+        const openerCandidate = item.state.interactedElements?.[0];
+        previousOpener = actions.length === 1 && openerCandidate && looksLikeMenuOpener(openerCandidate) ? {
+          params: parseAction(actions[0])?.params ?? {},
+          recorded: openerCandidate
+        } : void 0;
+      } catch (error) {
+        if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+        const stepError = attemptSignal?.aborted && !(error instanceof ReplayStepError) ? new ReplayStepError(
+          `step ${stepNumber} attempt timed out after ${stepTimeoutMs}ms`,
+          [],
+          []
+        ) : error;
+        if (!(stepError instanceof ReplayStepError)) throw stepError;
+        attempt += 1;
+        log.warn("replay step failed", { step: stepNumber, attempt, error: stepError.message });
+        if (attempt >= maxRetries) {
+          lastSuccessful = void 0;
+          const message = `step ${stepNumber} failed after ${attempt} attempt(s): ${stepError.message}`;
+          if (!skipFailures) {
+            throw new Error(`Replay aborted: ${message}`);
+          }
+          outcome = {
+            stepNumber,
+            outcome: "failed",
+            matchLevels: stepError.matchLevels,
+            results: stepError.results,
+            error: stepError.message,
+            attempts: attempt
+          };
+        } else {
+          await abortableSleep(backoffMs(attempt, retryBaseMs, retryCapMs), sleep, signal);
+        }
+      }
+    }
+    steps.push(outcome);
+  }
+  const succeededSteps = steps.filter((s) => s.outcome === "replayed").length;
+  const totalSteps = steps.length;
+  const { summary, success, completionStatus, summarySource } = await buildRerunSummary(
+    deps.task ?? "",
+    steps,
+    succeededSteps,
+    totalSteps,
+    deps.model,
+    signal,
+    deps.streamOptions
+  );
+  return { steps, succeededSteps, totalSteps, summary, success, completionStatus, summarySource };
+}
+async function loadAndRerun(filePath, deps, options = {}) {
+  const loaded = await loadHistoryFromFile(filePath);
+  const detected = detectVariables(loaded);
+  const history = options.variables ? substituteVariables(loaded, detected, options.variables) : loaded;
+  const report = await rerunHistory(history, deps, options);
+  return { ...report, detectedVariables: detected };
+}
+
+// src/index.ts
+var PACKAGE = "@ap3x/browser-agent";
+var VERSION = "0.1.0";
+export {
+  Agent,
+  AgentEventStream,
+  AgentHistoryList,
+  BUILTIN_ACTIONS,
+  BrowserAgentBackend,
+  COMPACT_EVERY_N_STEPS,
+  COMPACT_TRIGGER_CHARS,
+  CaptchaWatchdog,
+  FileParseError,
+  FileSystem,
+  HistoryFileSchema,
+  JudgementResultSchema,
+  LoopDetector,
+  MessageManager,
+  PACKAGE,
+  Registry,
+  StepLoop,
+  UsageLedger,
+  VERSION,
+  agentStep,
+  anySignal,
+  applicablePlaceholders,
+  assembleNarration,
+  budgetNudge,
+  buildAgentOutputSchema,
+  collectingLogger,
+  connectMcpClient,
+  createBrowserMcpServer,
+  createDefaultRegistry,
+  createLogger,
+  defineAction,
+  detectCaptcha,
+  detectVariables,
+  doneResult,
+  emptyLlmResponse,
+  encodeFramesToGif,
+  generateRunGif,
+  generateRunVideoGif,
+  importMcpTools,
+  invalidLlmResponse,
+  isDoneResult,
+  judgeRun,
+  loadAndRerun,
+  loadHistoryFromFile,
+  looksLikeMenuItem,
+  looksLikeMenuOpener,
+  maskOutbound,
+  maskSecretMap,
+  multiAct,
+  parseAction,
+  perceive,
+  readExternalFile,
+  registerBuiltins,
+  rematchElement,
+  rerunHistory,
+  resolveSecretsForUrl,
+  resultsAreDone,
+  runBrowserMcpServer,
+  sanitizeFilename,
+  saveHistoryToFile,
+  scriptedLlm,
+  sensitiveDataDescription,
+  silentLogger,
+  stepDurationSeconds,
+  stepResult,
+  substituteSecrets,
+  substituteVariables,
+  synthesizeParamSchema,
+  toTypedAction,
+  totp,
+  transportErrorResponse,
+  truncatedLlmResponse
+};