@ap3x/browser-agent 0.1.0

package/dist/chunk-UZALZUEE.js

@@ -0,0 +1,2907 @@
+// src/tools/types.ts
+function stepResult(fields = {}) {
+  return { ...fields, isDone: false };
+}
+function doneResult(success, fields = {}) {
+  return { ...fields, isDone: true, success };
+}
+function isDoneResult(result) {
+  return result.isDone === true;
+}
+
+// src/tools/sensitive.ts
+import { createHmac } from "crypto";
+import { matchUrlWithDomainPattern } from "@ap3x/browser";
+function domainApplies(pattern, url) {
+  if (pattern === "*") return true;
+  return matchUrlWithDomainPattern(url, pattern);
+}
+function isPresent(value) {
+  if (typeof value === "string") return value.length > 0;
+  return typeof value.totpSeed === "string" && value.totpSeed.length > 0;
+}
+function resolveSecretsForUrl(data, url) {
+  const out = {};
+  for (const [pattern, entries] of Object.entries(data)) {
+    if (!domainApplies(pattern, url)) continue;
+    for (const [key, value] of Object.entries(entries)) {
+      if (isPresent(value)) out[key] = value;
+    }
+  }
+  return out;
+}
+function applicablePlaceholders(data, url) {
+  return Object.keys(resolveSecretsForUrl(data, url)).sort();
+}
+function sensitiveDataDescription(data, url) {
+  const keys = applicablePlaceholders(data, url);
+  if (keys.length === 0) return void 0;
+  const list = keys.map((k) => `  - ${k}`).join("\n");
+  return `The following placeholders hold sensitive values for this page. To use one, write it as <secret>key</secret> where you want the value typed; the system substitutes the real value at execution time. Never write the raw value.
+${list}`;
+}
+function maskOutbound(text, data) {
+  const pairs = [];
+  for (const entries of Object.values(data)) {
+    for (const [key, value] of Object.entries(entries)) {
+      if (typeof value === "string" && value.length > 0) pairs.push({ key, value });
+    }
+  }
+  pairs.sort((a, b) => b.value.length - a.value.length);
+  let out = text;
+  for (const { key, value } of pairs) {
+    out = out.split(value).join(`<secret>${key}</secret>`);
+  }
+  return out;
+}
+function maskSecretMap(text, secrets) {
+  const pairs = [];
+  for (const [key, value] of Object.entries(secrets)) {
+    if (typeof value === "string" && value.length > 0) pairs.push({ key, value });
+  }
+  pairs.sort((a, b) => b.value.length - a.value.length);
+  let out = text;
+  for (const { key, value } of pairs) {
+    out = out.split(value).join(`<secret>${key}</secret>`);
+  }
+  return out;
+}
+var SECRET_TAG = /<secret>([^<]+)<\/secret>/g;
+function realValue(value) {
+  return typeof value === "string" ? value : totp(value.totpSeed);
+}
+function substituteSecrets(params, secrets) {
+  const unresolved = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (typeof node === "string") return substituteString(node);
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === "object") {
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
+      return out;
+    }
+    return node;
+  };
+  const substituteString = (text) => {
+    if (Object.hasOwn(secrets, text)) return realValue(secrets[text]);
+    return text.replace(SECRET_TAG, (match, key) => {
+      if (Object.hasOwn(secrets, key)) return realValue(secrets[key]);
+      unresolved.add(key);
+      return match;
+    });
+  };
+  return { value: walk(params), unresolved: [...unresolved] };
+}
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function base32Decode(input) {
+  const clean = input.replace(/[\s=]/g, "").toUpperCase();
+  const bytes = [];
+  let bits = 0;
+  let acc = 0;
+  for (const char of clean) {
+    const index = BASE32_ALPHABET.indexOf(char);
+    if (index < 0) throw new Error(`invalid base32 character: ${char}`);
+    acc = acc << 5 | index;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push(acc >> bits & 255);
+    }
+  }
+  return Buffer.from(bytes);
+}
+function totp(seed, options = {}) {
+  const step = options.step ?? 30;
+  const digits = options.digits ?? 6;
+  const time = options.time ?? Math.floor(Date.now() / 1e3);
+  const counter = Math.floor(time / step);
+  const buf = Buffer.alloc(8);
+  buf.writeBigUInt64BE(BigInt(counter));
+  const hmac = createHmac("sha1", base32Decode(seed)).update(buf).digest();
+  const offset = hmac[hmac.length - 1] & 15;
+  const binary = (hmac[offset] & 127) << 24 | (hmac[offset + 1] & 255) << 16 | (hmac[offset + 2] & 255) << 8 | hmac[offset + 3] & 255;
+  return (binary % 10 ** digits).toString().padStart(digits, "0");
+}
+
+// src/tools/registry.ts
+import { matchUrlWithDomainPattern as matchUrlWithDomainPattern2 } from "@ap3x/browser";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+function defineAction(def) {
+  return def;
+}
+function isAvailable(action, pageUrl) {
+  if (!action.domains || action.domains.length === 0) return true;
+  if (pageUrl === void 0) return false;
+  return action.domains.some((pattern) => matchUrlWithDomainPattern2(pageUrl, pattern));
+}
+function firstError(schema, value) {
+  const [error] = [...Value.Errors(schema, value)];
+  return error ? `${error.path || "/"}: ${error.message}` : "does not match schema";
+}
+var Registry = class _Registry {
+  actions = /* @__PURE__ */ new Map();
+  excluded = /* @__PURE__ */ new Set();
+  unionCache = /* @__PURE__ */ new Map();
+  /** Register an action. Later registration of an excluded name is a no-op. */
+  register(def) {
+    if (this.excluded.has(def.name)) return;
+    if (this.actions.has(def.name)) {
+      throw new Error(`Action "${def.name}" is already registered`);
+    }
+    this.actions.set(def.name, {
+      name: def.name,
+      description: def.description,
+      schema: def.schema,
+      domains: def.domains,
+      terminatesSequence: def.terminatesSequence ?? false,
+      execute: def.execute
+    });
+    this.unionCache.clear();
+  }
+  /**
+   * A shallow copy sharing the same action definitions. The step loop clones a
+   * caller's registry before applying a vision filter so the caller's object is
+   * never mutated (E7). Excluded names carry over.
+   */
+  clone() {
+    const copy = new _Registry();
+    for (const [name, action] of this.actions) copy.actions.set(name, action);
+    for (const name of this.excluded) copy.excluded.add(name);
+    return copy;
+  }
+  /** Remove an action and block it from being re-registered. */
+  exclude(name) {
+    this.excluded.add(name);
+    if (this.actions.delete(name)) this.unionCache.clear();
+  }
+  get(name) {
+    return this.actions.get(name);
+  }
+  /** Actions available on `pageUrl` (unfiltered + domain-matching), name-sorted. */
+  available(pageUrl) {
+    return [...this.actions.values()].filter((a) => isAvailable(a, pageUrl)).sort((a, b) => a.name.localeCompare(b.name));
+  }
+  /**
+   * The per-page union of single-key action objects for structured output (A8).
+   * Cached by the set of admitted action names (so equivalent URLs share one).
+   */
+  actionUnion(pageUrl) {
+    const admitted = this.available(pageUrl);
+    const key = admitted.map((a) => a.name).join("|");
+    const cached = this.unionCache.get(key);
+    if (cached) return cached;
+    const members = admitted.map(
+      (a) => Type.Object({ [a.name]: a.schema }, { additionalProperties: false, title: a.name })
+    );
+    const union = members.length === 0 ? Type.Never() : members.length === 1 ? members[0] : Type.Union(members);
+    this.unionCache.set(key, union);
+    return union;
+  }
+  /** `name: description (param=type, ...)` lines for the prompt. */
+  promptDescriptions(pageUrl) {
+    return this.available(pageUrl).map((a) => {
+      const props = a.schema.properties ?? {};
+      const params = Object.keys(props).join(", ");
+      return `${a.name}: ${a.description}${params ? ` (${params})` : ""}`;
+    }).join("\n");
+  }
+  /**
+   * Execute one action. `<secret>key</secret>` tags are substituted (enforcement
+   * point 3) and — ALWAYS, even with no secrets configured — scanned for
+   * survivors: any unresolved `<secret>…</secret>` short-circuits to an
+   * `ActionResult.error` and the action never runs, so a literal tag can never be
+   * typed (C5). Params are then validated against the action's schema before
+   * `execute`; afterwards every result string is masked against the resolved
+   * secrets so a real substituted value can never land in history.
+   *
+   * `allSensitiveData` (M8 follow-up), when provided, masks results against
+   * EVERY domain's secret values (mirroring `maskOutbound`'s all-domains
+   * approach), not just `secrets` (the current-URL-scoped subset used for
+   * substitution). Page content is not domain-sandboxed the way secret
+   * substitution is — a domain-B secret echoed while acting on domain A must
+   * still be masked on this method's outbound text (narration / event stream /
+   * ToolResultMessage), the same way the LLM-prompt path already masks via
+   * `maskOutbound` in the message manager. Without it, masking falls back to
+   * `secrets` alone (the pre-M11 behavior — still correct for the single-domain
+   * case, just narrower).
+   */
+  async execute(name, rawParams, ctx, secrets, allSensitiveData) {
+    const action = this.actions.get(name);
+    if (!action) return stepResult({ error: `Action "${name}" not found` });
+    const resolved = secrets ?? {};
+    const { value: params, unresolved } = substituteSecrets(rawParams, resolved);
+    if (unresolved.length > 0) {
+      return stepResult({
+        error: `Unresolved secret placeholder(s): ${unresolved.join(", ")}. No such key in sensitive data for this page \u2014 the value was not typed.`
+      });
+    }
+    if (!Value.Check(action.schema, params)) {
+      return stepResult({
+        error: `Invalid parameters for "${name}": ${firstError(action.schema, params)}`
+      });
+    }
+    try {
+      const result = await action.execute(params, ctx);
+      return maskResultSecrets(result, resolved, allSensitiveData);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return maskResultSecrets(stepResult({ error: message }), resolved, allSensitiveData);
+    }
+  }
+};
+function maskResultSecrets(result, secrets, allSensitiveData) {
+  const mask = (text) => {
+    if (text === void 0) return void 0;
+    return allSensitiveData ? maskOutbound(text, allSensitiveData) : maskSecretMap(text, secrets);
+  };
+  const masked = { ...result };
+  if (masked.longTermMemory !== void 0) masked.longTermMemory = mask(masked.longTermMemory);
+  if (masked.extractedContent !== void 0)
+    masked.extractedContent = mask(masked.extractedContent);
+  if (masked.error !== void 0) masked.error = mask(masked.error);
+  return masked;
+}
+
+// src/filesystem/external-read.ts
+import { readFile as fsReadFile } from "fs/promises";
+import { strFromU8, unzipSync } from "fflate";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+var MAX_CHARS = 6e4;
+function truncate(text) {
+  return text.length <= MAX_CHARS ? text : `${text.slice(0, MAX_CHARS)}
+[...truncated]`;
+}
+var MAX_DOCX_INFLATED_BYTES = 32 * 1024 * 1024;
+var FileParseError = class extends Error {
+  constructor(path, message, options) {
+    super(message, options);
+    this.path = path;
+  }
+  path;
+  name = "FileParseError";
+};
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function parsePdf(buf, path) {
+  let doc;
+  try {
+    doc = await getDocument({
+      data: new Uint8Array(buf),
+      isEvalSupported: false,
+      useSystemFonts: true,
+      verbosity: 0
+      // ERRORS only — silence pdf.js's recovery-mode console noise
+    }).promise;
+  } catch (err) {
+    throw new FileParseError(path, `Could not parse PDF '${path}': ${errorMessage(err)}`, {
+      cause: err
+    });
+  }
+  try {
+    const pages = [];
+    for (let i = 1; i <= doc.numPages; i++) {
+      const page = await doc.getPage(i);
+      const content = await page.getTextContent();
+      const text = content.items.map((item) => "str" in item ? item.str : "").join(" ").trim();
+      pages.push(text);
+    }
+    return pages.join("\n\n");
+  } catch (err) {
+    throw new FileParseError(
+      path,
+      `Could not read PDF page text in '${path}': ${errorMessage(err)}`,
+      { cause: err }
+    );
+  } finally {
+    await doc.destroy().catch(() => {
+    });
+  }
+}
+var DOCX_PARAGRAPH = /<w:p[ >][\s\S]*?<\/w:p>/g;
+var DOCX_TEXT_RUN = /<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>/g;
+var DOCX_LINE_BREAK = /<w:(?:br|tab|cr)\s*\/>/g;
+function decodeXmlEntities(text) {
+  return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function parseDocx(buf, path) {
+  let xml;
+  try {
+    const entries = unzipSync(new Uint8Array(buf), {
+      // Checked against the local header's declared uncompressed size BEFORE
+      // inflation — a bomb entry never gets decompressed at all.
+      filter: (info) => info.name === "word/document.xml" && info.originalSize <= MAX_DOCX_INFLATED_BYTES
+    });
+    const bytes = entries["word/document.xml"];
+    if (!bytes) {
+      throw new Error(
+        `missing word/document.xml, or it exceeds the ${MAX_DOCX_INFLATED_BYTES}-byte inflate cap \u2014 not a valid (or safe) .docx file`
+      );
+    }
+    xml = strFromU8(bytes);
+  } catch (err) {
+    throw new FileParseError(path, `Could not parse DOCX '${path}': ${errorMessage(err)}`, {
+      cause: err
+    });
+  }
+  const paragraphs = xml.match(DOCX_PARAGRAPH) ?? [];
+  const lines = paragraphs.map((paragraph) => {
+    const withBreaks = paragraph.replace(DOCX_LINE_BREAK, "\n");
+    const runs = [...withBreaks.matchAll(DOCX_TEXT_RUN)].map((m) => decodeXmlEntities(m[1] ?? ""));
+    return runs.join("");
+  });
+  return lines.join("\n").trim();
+}
+async function readExternalFile(path) {
+  const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+  if (ext === "pdf") return truncate(await parsePdf(await fsReadFile(path), path));
+  if (ext === "docx") return truncate(parseDocx(await fsReadFile(path), path));
+  return truncate(await fsReadFile(path, "utf8"));
+}
+
+// src/tools/actions.ts
+import { basename, join } from "path";
+import { InteractionError, PAGE_SCROLL_PX, asElementIndex, isPathContained } from "@ap3x/browser";
+import { Type as Type2 } from "@sinclair/typebox";
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function nodeAt(ctx, index) {
+  const node = ctx.session.getElementByIndex(index);
+  if (!node) {
+    return {
+      ok: false,
+      result: stepResult({
+        error: `Element ${index} not found \u2014 the page may have changed. Re-read the page state to re-index.`
+      })
+    };
+  }
+  return { ok: true, node };
+}
+var navigate = defineAction({
+  name: "navigate",
+  description: "Navigate the current tab to a URL (opens a new tab when newTab is true).",
+  schema: Type2.Object({ url: Type2.String(), newTab: Type2.Optional(Type2.Boolean()) }),
+  terminatesSequence: true,
+  async execute(params, ctx) {
+    if (params.newTab) {
+      await ctx.session.openTab(params.url);
+      return stepResult({ longTermMemory: `Opened new tab at ${params.url}` });
+    }
+    await ctx.driver.navigate(params.url, { signal: ctx.signal });
+    return stepResult({ longTermMemory: `Navigated to ${params.url}` });
+  }
+});
+var goBack = defineAction({
+  name: "go_back",
+  description: "Go back one entry in the browser history.",
+  schema: Type2.Object({}),
+  terminatesSequence: true,
+  async execute(_params, ctx) {
+    await ctx.session.goBack();
+    return stepResult({ longTermMemory: "Navigated back" });
+  }
+});
+var click = defineAction({
+  name: "click",
+  description: "Click an interactive element by its [index].",
+  schema: Type2.Object({ index: Type2.Integer({ minimum: 1 }) }),
+  async execute(params, ctx) {
+    const resolved = nodeAt(ctx, params.index);
+    if (!resolved.ok) return resolved.result;
+    await ctx.driver.click(asElementIndex(params.index), { signal: ctx.signal });
+    return stepResult({ longTermMemory: `Clicked element ${params.index}` });
+  }
+});
+var inputText = defineAction({
+  name: "input_text",
+  description: "Type text into an element by its [index]. clear=false appends; text='' clears.",
+  schema: Type2.Object({
+    index: Type2.Integer({ minimum: 0 }),
+    text: Type2.String(),
+    clear: Type2.Optional(Type2.Boolean())
+  }),
+  async execute(params, ctx) {
+    const resolved = nodeAt(ctx, params.index);
+    if (!resolved.ok) return resolved.result;
+    await ctx.driver.type(asElementIndex(params.index), params.text, {
+      clear: params.clear ?? true,
+      // Suppress value read-back when a secret is in play so it never round-trips out.
+      sensitive: ctx.hasSensitiveData,
+      signal: ctx.signal
+    });
+    const shown = ctx.hasSensitiveData ? "<sensitive>" : params.text;
+    return stepResult({ longTermMemory: `Typed "${shown}" into element ${params.index}` });
+  }
+});
+var scroll = defineAction({
+  name: "scroll",
+  description: "Scroll the page (or an element by [index]) up/down by a number of pages.",
+  schema: Type2.Object({
+    down: Type2.Optional(Type2.Boolean()),
+    pages: Type2.Optional(Type2.Number()),
+    index: Type2.Optional(Type2.Integer({ minimum: 1 }))
+  }),
+  async execute(params, ctx) {
+    const pages = params.pages ?? 1;
+    const amount = Math.round(pages * PAGE_SCROLL_PX) * (params.down === false ? -1 : 1);
+    if (params.index !== void 0) {
+      const resolved = nodeAt(ctx, params.index);
+      if (!resolved.ok) return resolved.result;
+      await ctx.session.input.scroll({ amount, node: resolved.node, signal: ctx.signal });
+    } else {
+      await ctx.driver.scroll(amount, { signal: ctx.signal });
+    }
+    return stepResult({
+      longTermMemory: `Scrolled ${params.down === false ? "up" : "down"} ${pages} page(s)`
+    });
+  }
+});
+var scrollToText = defineAction({
+  name: "scroll_to_text",
+  description: "Scroll to the first occurrence of the given text.",
+  schema: Type2.Object({ text: Type2.String() }),
+  async execute(params, ctx) {
+    try {
+      await ctx.session.input.scrollToText(params.text, { signal: ctx.signal });
+      return stepResult({ longTermMemory: `Scrolled to text "${params.text}"` });
+    } catch (error) {
+      if (error instanceof InteractionError && error.reason === "text_not_found") {
+        return stepResult({ extractedContent: `Text "${params.text}" not found on the page.` });
+      }
+      throw error;
+    }
+  }
+});
+var sendKeys = defineAction({
+  name: "send_keys",
+  description: "Dispatch raw keyboard keys or a shortcut (e.g. 'Enter', 'Control+a').",
+  schema: Type2.Object({ keys: Type2.String() }),
+  async execute(params, ctx) {
+    await ctx.session.input.sendKeys(params.keys, { signal: ctx.signal });
+    return stepResult({ longTermMemory: `Sent keys ${params.keys}` });
+  }
+});
+var selectDropdown = defineAction({
+  name: "select_dropdown",
+  description: "Select a dropdown option by its exact text, on the element at [index].",
+  schema: Type2.Object({ index: Type2.Integer({ minimum: 1 }), text: Type2.String() }),
+  async execute(params, ctx) {
+    const resolved = nodeAt(ctx, params.index);
+    if (!resolved.ok) return resolved.result;
+    const result = await ctx.session.input.selectDropdownOption(resolved.node, params.text, {
+      signal: ctx.signal
+    });
+    if (!result.success) {
+      return stepResult({ error: result.message ?? `Could not select "${params.text}"` });
+    }
+    return stepResult({
+      longTermMemory: `Selected "${params.text}" (value=${result.value ?? ""})`
+    });
+  }
+});
+var getDropdownOptions = defineAction({
+  name: "get_dropdown_options",
+  description: "List the available options of the dropdown element at [index].",
+  schema: Type2.Object({ index: Type2.Integer({ minimum: 1 }) }),
+  async execute(params, ctx) {
+    const resolved = nodeAt(ctx, params.index);
+    if (!resolved.ok) return resolved.result;
+    const options = await ctx.session.input.getDropdownOptions(resolved.node, {
+      signal: ctx.signal
+    });
+    return stepResult({
+      extractedContent: `Options: ${options.join(", ")}. Use the exact text string to select.`,
+      includeExtractedContentOnlyOnce: true
+    });
+  }
+});
+var switchTab = defineAction({
+  name: "switch_tab",
+  description: "Focus another tab by its 4-char id.",
+  schema: Type2.Object({ tabId: Type2.String() }),
+  terminatesSequence: true,
+  async execute(params, ctx) {
+    await ctx.driver.switchTab(params.tabId);
+    return stepResult({ longTermMemory: `Switched to tab ${params.tabId}` });
+  }
+});
+var openTab = defineAction({
+  name: "open_tab",
+  description: "Open a new tab at a URL.",
+  schema: Type2.Object({ url: Type2.String() }),
+  terminatesSequence: true,
+  async execute(params, ctx) {
+    const tabId = await ctx.session.openTab(params.url);
+    return stepResult({ longTermMemory: `Opened tab ${tabId} at ${params.url}` });
+  }
+});
+var closeTab = defineAction({
+  name: "close_tab",
+  description: "Close a tab by its 4-char id.",
+  schema: Type2.Object({ tabId: Type2.String() }),
+  async execute(params, ctx) {
+    await ctx.driver.closeTab(params.tabId);
+    return stepResult({ longTermMemory: `Closed tab ${params.tabId}` });
+  }
+});
+var uploadFile = defineAction({
+  name: "upload_file",
+  description: "Set a file on the file-input element at [index]. Path must be available.",
+  schema: Type2.Object({ index: Type2.Integer({ minimum: 0 }), path: Type2.String() }),
+  async execute(params, ctx) {
+    let uploadPath;
+    const base = basename(params.path);
+    if (ctx.fileSystem.listFiles().includes(base)) {
+      uploadPath = join(ctx.fileSystem.getDir(), base);
+      if (!await isPathContained(uploadPath, ctx.fileSystem.getDir())) {
+        return stepResult({ error: `Upload of "${params.path}" escapes the workspace; refusing.` });
+      }
+    } else if (ctx.availableFilePaths.includes(params.path)) {
+      uploadPath = params.path;
+    } else {
+      return stepResult({ error: `Path "${params.path}" is not available for upload.` });
+    }
+    const resolved = nodeAt(ctx, params.index);
+    if (!resolved.ok) return resolved.result;
+    await ctx.session.input.uploadFile(resolved.node, uploadPath, { signal: ctx.signal });
+    return stepResult({ longTermMemory: `Uploaded ${uploadPath} to element ${params.index}` });
+  }
+});
+var wait = defineAction({
+  name: "wait",
+  description: "Wait for a number of seconds (capped at 30).",
+  schema: Type2.Object({ seconds: Type2.Optional(Type2.Number()) }),
+  async execute(params) {
+    const requested = params.seconds ?? 3;
+    await sleep(Math.min(Math.max(requested - 1, 0), 30) * 1e3);
+    return stepResult({ longTermMemory: `Waited for ${requested} seconds` });
+  }
+});
+var extractContent = defineAction({
+  name: "extract_content",
+  description: "Extract the page's readable content, guided by a query.",
+  schema: Type2.Object({
+    query: Type2.String()
+  }),
+  async execute(params, ctx) {
+    const text = await ctx.driver.extract(params.query, { signal: ctx.signal });
+    const content = ctx.extractionLlm ? await ctx.extractionLlm.extract(`Query: ${params.query}
+
+${text}`, { signal: ctx.signal }) : text;
+    const once = content.length > 1e4;
+    return stepResult({
+      extractedContent: once ? content : `<query>${params.query}</query>
+${content}`,
+      includeExtractedContentOnlyOnce: once
+    });
+  }
+});
+var writeFile = defineAction({
+  name: "write_file",
+  description: "Write (replacing) a file in the agent workspace.",
+  schema: Type2.Object({
+    fileName: Type2.String(),
+    content: Type2.String(),
+    append: Type2.Optional(Type2.Boolean())
+  }),
+  async execute(params, ctx) {
+    const message = params.append ? await ctx.fileSystem.appendFile(params.fileName, params.content) : await ctx.fileSystem.writeFile(params.fileName, params.content);
+    return stepResult({ extractedContent: message, longTermMemory: message });
+  }
+});
+var appendFile = defineAction({
+  name: "append_file",
+  description: "Append content to a file in the agent workspace.",
+  schema: Type2.Object({ fileName: Type2.String(), content: Type2.String() }),
+  async execute(params, ctx) {
+    const message = await ctx.fileSystem.appendFile(params.fileName, params.content);
+    return stepResult({ extractedContent: message, longTermMemory: message });
+  }
+});
+var replaceFile = defineAction({
+  name: "replace_file",
+  description: "Replace a substring in a workspace file (the todo.md checkbox primitive).",
+  schema: Type2.Object({ fileName: Type2.String(), oldStr: Type2.String(), newStr: Type2.String() }),
+  async execute(params, ctx) {
+    const message = await ctx.fileSystem.replaceFileStr(
+      params.fileName,
+      params.oldStr,
+      params.newStr
+    );
+    return stepResult({ extractedContent: message, longTermMemory: message });
+  }
+});
+var readFile = defineAction({
+  name: "read_file",
+  description: "Read a workspace file, or a whitelisted external file (text, .pdf, or .docx).",
+  schema: Type2.Object({ fileName: Type2.String() }),
+  async execute(params, ctx) {
+    const managed = ctx.fileSystem.getFile(params.fileName);
+    if (managed !== void 0) {
+      return stepResult({ extractedContent: ctx.fileSystem.readFile(params.fileName) });
+    }
+    const external = ctx.availableFilePaths.find((p) => basename(p) === basename(params.fileName));
+    if (external) {
+      try {
+        const content = await readExternalFile(external);
+        return stepResult({ extractedContent: `Read from file ${params.fileName}.
+${content}` });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return stepResult({ error: `Could not read external file ${params.fileName}: ${message}` });
+      }
+    }
+    return stepResult({ error: `File '${params.fileName}' not found.` });
+  }
+});
+var done = defineAction({
+  name: "done",
+  description: "Finish the task. success=true ONLY when fully complete. text must report only observed facts.",
+  schema: Type2.Object({
+    text: Type2.String(),
+    success: Type2.Boolean(),
+    filesToDisplay: Type2.Optional(Type2.Array(Type2.String()))
+  }),
+  execute(params, ctx) {
+    const attachments = (params.filesToDisplay ?? []).map((name) => ctx.fileSystem.displayFile(name) !== void 0 ? name : void 0).filter((n) => n !== void 0);
+    return doneResult(params.success, {
+      extractedContent: params.text,
+      attachments: attachments.length > 0 ? attachments : void 0
+    });
+  }
+});
+var BUILTIN_ACTIONS = [
+  navigate,
+  goBack,
+  click,
+  inputText,
+  scroll,
+  scrollToText,
+  sendKeys,
+  selectDropdown,
+  getDropdownOptions,
+  switchTab,
+  openTab,
+  closeTab,
+  uploadFile,
+  wait,
+  extractContent,
+  writeFile,
+  appendFile,
+  replaceFile,
+  readFile,
+  done
+];
+function registerBuiltins(registry) {
+  for (const action of BUILTIN_ACTIONS) registry.register(action);
+}
+function createDefaultRegistry() {
+  const registry = new Registry();
+  registerBuiltins(registry);
+  return registry;
+}
+
+// src/filesystem/file-system.ts
+import { mkdir, rm, writeFile as writeFile2 } from "fs/promises";
+import { basename as basename2, join as join2 } from "path";
+var SUPPORTED_EXTENSIONS = ["md", "txt", "json", "jsonl", "csv", "html", "xml"];
+var STUBBED_EXTENSIONS = ["pdf", "docx"];
+var SUPPORTED = new Set(SUPPORTED_EXTENSIONS);
+var STUBBED = new Set(STUBBED_EXTENSIONS);
+var DATA_DIR_NAME = "ap3x_agent_data";
+var DEFAULT_FILE = "todo.md";
+var DESCRIBE_WHOLE_LIMIT = 600;
+var DESCRIBE_PREVIEW_CHARS = 200;
+function splitName(raw) {
+  const base = basename2(raw);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return null;
+  return { stem: base.slice(0, dot), ext: base.slice(dot + 1).toLowerCase() };
+}
+var WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+function sanitizeStem(stem) {
+  const cleaned = stem.replace(/\s+/g, "-").replace(/[^\p{L}\p{N}_().-]/gu, "").replace(/-+/g, "-");
+  if (cleaned === "") return "file";
+  return WINDOWS_RESERVED.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+function sanitizeFilename(name) {
+  const split = splitName(name);
+  if (!split) return name;
+  return `${sanitizeStem(split.stem)}.${split.ext}`;
+}
+function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charAt(i);
+    if (inQuotes) {
+      if (c === '"') {
+        if (text.charAt(i + 1) === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += c;
+      }
+      continue;
+    }
+    if (c === '"') inQuotes = true;
+    else if (c === ",") {
+      row.push(field);
+      field = "";
+    } else if (c === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else if (c !== "\r") field += c;
+  }
+  row.push(field);
+  rows.push(row);
+  return rows;
+}
+function serializeCsvField(field) {
+  return /[",\n]/.test(field) ? `"${field.replace(/"/g, '""')}"` : field;
+}
+function normalizeCsv(content) {
+  let text = content;
+  if (!text.includes("\n") && text.includes("\\n")) {
+    text = text.replace(/\\"/g, '"').replace(/\\n/g, "\n");
+  }
+  const rows = parseCsv(text);
+  while (rows.length > 0 && rows[0].length === 1 && rows[0][0] === "") rows.shift();
+  while (rows.length > 0 && rows[rows.length - 1].length === 1 && rows[rows.length - 1][0] === "")
+    rows.pop();
+  return rows.map((r) => r.map(serializeCsvField).join(",")).join("\n");
+}
+function normalizeContent(ext, content) {
+  return ext === "csv" ? normalizeCsv(content) : content;
+}
+var FileSystem = class _FileSystem {
+  files = /* @__PURE__ */ new Map();
+  extractedContentCount = 0;
+  baseDir;
+  dataDir;
+  constructor(baseDir) {
+    this.baseDir = baseDir;
+    this.dataDir = join2(baseDir, DATA_DIR_NAME);
+  }
+  /** Create a fresh filesystem. The data dir is wiped and recreated. */
+  static async create(baseDir, options = {}) {
+    const fs = new _FileSystem(baseDir);
+    await rm(fs.dataDir, { recursive: true, force: true });
+    await mkdir(fs.dataDir, { recursive: true });
+    if (options.createDefaultFiles ?? true) {
+      fs.files.set(DEFAULT_FILE, { stem: "todo", ext: "md", content: "" });
+      await fs.syncFile(DEFAULT_FILE);
+    }
+    return fs;
+  }
+  /** Restore from a checkpoint at the same base dir; unknown types skipped. */
+  static async fromState(state) {
+    const fs = new _FileSystem(state.baseDir);
+    await rm(fs.dataDir, { recursive: true, force: true });
+    await mkdir(fs.dataDir, { recursive: true });
+    fs.extractedContentCount = state.extractedContentCount;
+    for (const [full, { type, data }] of Object.entries(state.files)) {
+      if (!SUPPORTED.has(type)) continue;
+      const split = splitName(full);
+      if (!split) continue;
+      fs.files.set(full, { stem: split.stem, ext: type, content: data });
+      await fs.syncFile(full);
+    }
+    return fs;
+  }
+  /** Serialize for checkpoint. */
+  getState() {
+    const files = {};
+    for (const [full, entry] of this.files) files[full] = { type: entry.ext, data: entry.content };
+    return { files, baseDir: this.baseDir, extractedContentCount: this.extractedContentCount };
+  }
+  getAllowedExtensions() {
+    return SUPPORTED_EXTENSIONS;
+  }
+  getDir() {
+    return this.dataDir;
+  }
+  listFiles() {
+    return [...this.files.keys()];
+  }
+  /** Raw content of a managed file, or undefined. */
+  getFile(name) {
+    return this.files.get(name)?.content;
+  }
+  /** The always-present todo.md content. */
+  getTodoContents() {
+    return this.files.get(DEFAULT_FILE)?.content ?? "";
+  }
+  /** Write (replacing) a managed file. Returns an LLM-facing message. */
+  async writeFile(name, content) {
+    const resolved = this.resolve(name);
+    if ("error" in resolved) return resolved.error;
+    const { full, stem, ext, note } = resolved;
+    this.files.set(full, { stem, ext, content: normalizeContent(ext, content) });
+    await this.syncFile(full);
+    return `Data written to file ${full} successfully.${note}`;
+  }
+  /** Append to a managed file (creating it if new). */
+  async appendFile(name, content) {
+    const resolved = this.resolve(name);
+    if ("error" in resolved) return resolved.error;
+    const { full, stem, ext, note } = resolved;
+    const existing = this.files.get(full)?.content ?? "";
+    this.files.set(full, { stem, ext, content: normalizeContent(ext, existing + content) });
+    await this.syncFile(full);
+    return `Data appended to file ${full} successfully.${note}`;
+  }
+  /** Targeted string replace — the todo.md checkbox-update primitive. */
+  async replaceFileStr(name, oldStr, newStr) {
+    if (oldStr === "") return "Cannot replace with an empty search string.";
+    const full = sanitizeFilename(name);
+    const entry = this.files.get(full);
+    if (!entry) return `File '${full}' not found.`;
+    entry.content = normalizeContent(entry.ext, entry.content.split(oldStr).join(newStr));
+    await this.syncFile(full);
+    return `Successfully replaced text in ${full}.`;
+  }
+  /** Read a managed file; formatted message. */
+  readFile(name) {
+    const full = sanitizeFilename(name);
+    const entry = this.files.get(full);
+    if (!entry) return `File '${full}' not found.`;
+    return `Read from file ${full}.
+<content>
+${entry.content}
+</content>`;
+  }
+  /** Raw content for done attachments. */
+  displayFile(name) {
+    return this.files.get(sanitizeFilename(name))?.content;
+  }
+  /** Save extracted content to an auto-numbered file; returns the filename. */
+  async saveExtractedContent(content) {
+    const full = `extracted_content_${this.extractedContentCount}.md`;
+    this.extractedContentCount++;
+    this.files.set(full, { stem: full.slice(0, -3), ext: "md", content });
+    await this.syncFile(full);
+    return full;
+  }
+  /** Remove the data dir from disk (in-memory state untouched). */
+  async nuke() {
+    await rm(this.dataDir, { recursive: true, force: true });
+  }
+  /**
+   * Prompt-friendly listing of every file EXCEPT todo.md (which is surfaced whole
+   * elsewhere). Small files shown whole; large files previewed head+tail.
+   */
+  describe() {
+    const blocks = [];
+    for (const [full, entry] of this.files) {
+      if (full === DEFAULT_FILE) continue;
+      const lines = entry.content === "" ? 0 : entry.content.split("\n").length;
+      const body = entry.content.length < DESCRIBE_WHOLE_LIMIT ? entry.content : this.preview(entry.content, lines);
+      blocks.push(`<file>
+${full} - ${lines} lines
+${body}
+</file>`);
+    }
+    return blocks.join("\n");
+  }
+  preview(content, totalLines) {
+    const head = content.slice(0, DESCRIBE_PREVIEW_CHARS);
+    const tail = content.slice(-DESCRIBE_PREVIEW_CHARS);
+    const shownLines = head.split("\n").length + tail.split("\n").length;
+    const omitted = Math.max(0, totalLines - shownLines);
+    return `${head}
+... ${omitted} more lines ...
+${tail}`;
+  }
+  /** Validate + sanitize a target name, or return an LLM-facing error. */
+  resolve(name) {
+    const split = splitName(name);
+    if (!split) {
+      return { error: `File '${basename2(name)}' has no extension. Try a name like 'notes.md'.` };
+    }
+    if (isBinaryExtension(split.ext)) {
+      return {
+        error: `Cannot write '${split.ext}' \u2014 that is a binary/image extension. Only text files are supported (screenshots are captured automatically).`
+      };
+    }
+    if (STUBBED.has(split.ext)) {
+      return { error: `Writing '.${split.ext}' files is not supported in this version yet.` };
+    }
+    if (!SUPPORTED.has(split.ext)) {
+      return {
+        error: `Unsupported file extension '.${split.ext}'. Allowed: ${SUPPORTED_EXTENSIONS.join(", ")}.`
+      };
+    }
+    const full = sanitizeFilename(name);
+    const changed = full !== name;
+    const note = changed ? ` (Note: filename auto-corrected to ${full})` : "";
+    return {
+      full,
+      stem: full.slice(0, full.lastIndexOf(".")),
+      ext: split.ext,
+      note
+    };
+  }
+  async syncFile(full) {
+    const entry = this.files.get(full);
+    if (!entry) return;
+    await writeFile2(join2(this.dataDir, full), entry.content, "utf8");
+  }
+};
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "bmp",
+  "ico",
+  "svg",
+  "zip",
+  "gz",
+  "tar",
+  "exe",
+  "dll",
+  "mp3",
+  "mp4",
+  "wav",
+  "mov"
+]);
+function isBinaryExtension(ext) {
+  return BINARY_EXTENSIONS.has(ext);
+}
+
+// src/agent/output-schema.ts
+import { Type as Type3 } from "@sinclair/typebox";
+function buildAgentOutputSchema(actionUnion, variant) {
+  const action = Type3.Array(actionUnion, { minItems: 1 });
+  if (variant === "flash") {
+    return Type3.Object(
+      { memory: Type3.String(), action },
+      { additionalProperties: false, title: "AgentOutput" }
+    );
+  }
+  const fields = {
+    evaluation_previous_goal: Type3.String(),
+    memory: Type3.String(),
+    next_goal: Type3.String(),
+    action
+  };
+  if (variant === "thinking") {
+    return Type3.Object(
+      { thinking: Type3.Optional(Type3.String()), ...fields },
+      { additionalProperties: false, title: "AgentOutput" }
+    );
+  }
+  return Type3.Object(fields, { additionalProperties: false, title: "AgentOutput" });
+}
+function parseAction(entry) {
+  const keys = Object.keys(entry);
+  if (keys.length !== 1) return void 0;
+  const name = keys[0];
+  const params = entry[name];
+  return { name, params: params ?? {} };
+}
+
+// src/agent/message-manager.ts
+var COMPACT_EVERY_N_STEPS = 25;
+var COMPACT_TRIGGER_CHARS = 4e4;
+var KEEP_LAST_ITEMS = 6;
+var SUMMARY_MAX_CHARS = 6e3;
+var ERROR_TRUNCATE_CHARS = 200;
+var MAX_READ_STATE_CHARS = 6e4;
+function truncateContent(text) {
+  return text.length <= MAX_READ_STATE_CHARS ? text : `${text.slice(0, MAX_READ_STATE_CHARS)}
+... [Content truncated at 60k characters]`;
+}
+function truncateError(error) {
+  if (error.length <= ERROR_TRUNCATE_CHARS) return error;
+  const half = ERROR_TRUNCATE_CHARS / 2;
+  return `${error.slice(0, half)}\u2026\u2026${error.slice(-half)}`;
+}
+function renderItem(item) {
+  const tag = item.stepNumber ?? 0;
+  if (item.systemMessage) return `<step_${tag}>
+<sys>${item.systemMessage}</sys>
+</step_${tag}>`;
+  const lines = [];
+  if (item.evaluationPreviousGoal) lines.push(`Evaluation: ${item.evaluationPreviousGoal}`);
+  if (item.memory) lines.push(`Memory: ${item.memory}`);
+  if (item.nextGoal) lines.push(`Next goal: ${item.nextGoal}`);
+  for (const result of item.actionResults ?? []) lines.push(`Result: ${result}`);
+  if (item.error) lines.push(`Error: ${truncateError(item.error)}`);
+  return `<step_${tag}>
+${lines.join("\n")}
+</step_${tag}>`;
+}
+function persistentLine(result) {
+  if (result.error !== void 0) return `Error: ${truncateError(result.error)}`;
+  if (result.longTermMemory !== void 0) return result.longTermMemory;
+  if (result.extractedContent !== void 0 && !result.includeExtractedContentOnlyOnce) {
+    return result.extractedContent;
+  }
+  return void 0;
+}
+var MessageManager = class {
+  systemPrompt;
+  task;
+  sensitiveData;
+  fileSystemDescribe;
+  todoContents;
+  availableFilePaths;
+  items = [];
+  readState = "";
+  compactedMemory;
+  compactionCountValue = 0;
+  lastCompactionStep = 0;
+  /**
+   * One-shot: set when a step's result asked for the screenshot to be shown
+   * next (the on-demand `screenshot` action's `metadata.includeScreenshot`,
+   * design/04b §4.3 — "the message manager attaches the *next* state
+   * screenshot even in use_vision='auto'"). Consumed by the following
+   * `buildMessages` call regardless of the caller's own `attachScreenshot`.
+   */
+  pendingScreenshotRequest = false;
+  /** The raw state text built for the most recent step (kept for history debugging). */
+  lastStateText = "";
+  constructor(options) {
+    this.systemPrompt = options.systemPrompt;
+    this.task = options.task;
+    this.sensitiveData = options.sensitiveData;
+    this.fileSystemDescribe = options.fileSystemDescribe;
+    this.todoContents = options.todoContents;
+    this.availableFilePaths = options.availableFilePaths ?? [];
+    this.items.push({ stepNumber: 0, systemMessage: "Agent initialized" });
+  }
+  get compactionCount() {
+    return this.compactionCountValue;
+  }
+  get stateMessageText() {
+    return this.lastStateText;
+  }
+  /**
+   * Fold a completed step's output + results into the running history (the RECORD
+   * half of the loop as the LLM sees it). Once-only content becomes the next
+   * prompt's one-shot <read_state>; everything else becomes a persistent line.
+   */
+  recordStep(stepNumber, output, results) {
+    const actionResults = [];
+    const readStateParts = [];
+    for (const result of results) {
+      const line = persistentLine(result);
+      if (line !== void 0) actionResults.push(line);
+      if (result.includeExtractedContentOnlyOnce && result.extractedContent !== void 0) {
+        readStateParts.push(result.extractedContent);
+      }
+      if (result.metadata?.includeScreenshot === true) this.pendingScreenshotRequest = true;
+    }
+    this.readState = truncateContent(readStateParts.join("\n\n"));
+    this.items.push({
+      stepNumber,
+      evaluationPreviousGoal: output?.evaluation_previous_goal,
+      memory: output?.memory,
+      nextGoal: output?.next_goal,
+      actionResults: actionResults.length > 0 ? actionResults : void 0
+    });
+  }
+  /** Record a synthetic system note (e.g. "Failed to complete task in max steps"). */
+  recordSystemNote(stepNumber, message) {
+    this.items.push({ stepNumber, systemMessage: message });
+  }
+  /** Full rendered history text (used for both the prompt and the compaction gate). */
+  renderHistory() {
+    const blocks = [];
+    if (this.compactedMemory) {
+      blocks.push(
+        `<compacted_memory>
+(Treat as unverified \u2014 do not report as completed unless re-verified this session.)
+${this.compactedMemory}
+</compacted_memory>`
+      );
+    }
+    for (const item of this.items) blocks.push(renderItem(item));
+    return blocks.join("\n");
+  }
+  /**
+   * Compaction (design/04b §4.2). Fires only when BOTH gates hold:
+   * `stepNumber - lastCompactionStep >= 25` AND rendered history `>= 40000` chars.
+   * Summarizes the dropped items into `compactedMemory`, keeps the first item and
+   * the last 6, and bumps the compaction count. Returns whether it fired.
+   *
+   * ponytail: deterministic join-summary rather than a summarizer LLM call — the
+   * gate + keep-window is the load-bearing behavior; upgrade path is to pass a
+   * compaction model and summarize `dropped` instead of joining their memories.
+   */
+  maybeCompact(stepNumber) {
+    if (stepNumber - this.lastCompactionStep < COMPACT_EVERY_N_STEPS) return false;
+    if (this.renderHistory().length < COMPACT_TRIGGER_CHARS) return false;
+    if (this.items.length <= KEEP_LAST_ITEMS + 1) return false;
+    const first = this.items[0];
+    const dropped = this.items.slice(1, this.items.length - KEEP_LAST_ITEMS);
+    const kept = this.items.slice(this.items.length - KEEP_LAST_ITEMS);
+    const summary = dropped.map((item) => item.memory ?? item.systemMessage ?? (item.actionResults ?? []).join("; ")).filter((text) => text.length > 0).join("\n").slice(0, SUMMARY_MAX_CHARS);
+    this.compactedMemory = [this.compactedMemory, summary].filter(Boolean).join("\n").slice(0, SUMMARY_MAX_CHARS);
+    this.items.length = 0;
+    this.items.push(first, ...kept);
+    this.compactionCountValue += 1;
+    this.lastCompactionStep = stepNumber;
+    return true;
+  }
+  /** Assemble `[system, state, ...context]` for one step. */
+  buildMessages(state, options) {
+    const stateText = this.buildStateText(state, options);
+    this.lastStateText = stateText;
+    const attachScreenshot = (options.attachScreenshot ?? false) || this.pendingScreenshotRequest;
+    this.pendingScreenshotRequest = false;
+    const systemMessage = userText(this.systemPrompt);
+    const stateMessage = this.buildStateMessage(stateText, state, attachScreenshot);
+    const contextMessages = (options.nudges ?? []).map((nudge) => userText(nudge));
+    return [systemMessage, stateMessage, ...contextMessages];
+  }
+  buildStateMessage(stateText, state, attachScreenshot) {
+    if (attachScreenshot && state.screenshot) {
+      const parts = [
+        { type: "text", text: stateText },
+        { type: "text", text: "Current screenshot:" },
+        { type: "image", data: state.screenshot, mimeType: "image/png" }
+      ];
+      return { role: "user", content: parts, timestamp: Date.now() };
+    }
+    return { role: "user", content: stateText, timestamp: Date.now() };
+  }
+  buildStateText(state, options) {
+    const sections = [];
+    sections.push(`<user_request>
+${this.task}
+</user_request>`);
+    sections.push(`<agent_history>
+${this.renderHistory()}
+</agent_history>`);
+    sections.push(this.buildAgentState(state.url));
+    sections.push(this.buildBrowserState(state));
+    if (this.readState) sections.push(`<read_state>
+${this.readState}
+</read_state>`);
+    sections.push(
+      `<step_info>
+Step ${options.stepNumber} of at most ${options.maxSteps}.
+</step_info>`
+    );
+    const text = sections.join("\n\n");
+    return this.sensitiveData ? maskOutbound(text, this.sensitiveData) : text;
+  }
+  buildAgentState(url) {
+    const parts = [];
+    if (this.fileSystemDescribe)
+      parts.push(`<file_system>
+${this.fileSystemDescribe()}
+</file_system>`);
+    if (this.todoContents) {
+      const todo = this.todoContents();
+      parts.push(
+        `<todo_contents>
+${todo || "[empty todo.md \u2014 fill it when useful]"}
+</todo_contents>`
+      );
+    }
+    if (this.sensitiveData) {
+      const block = sensitiveDataDescription(this.sensitiveData, url);
+      if (block) parts.push(`<sensitive_data>
+${block}
+</sensitive_data>`);
+    }
+    if (this.availableFilePaths.length > 0) {
+      parts.push(
+        `<available_file_paths>
+${this.availableFilePaths.join("\n")}
+Use absolute paths.
+</available_file_paths>`
+      );
+    }
+    return `<agent_state>
+${parts.join("\n")}
+</agent_state>`;
+  }
+  buildBrowserState(state) {
+    const tabs = state.tabs.map((tab) => `  [${tab.id}] ${tab.url} \u2014 ${tab.title.slice(0, 30)}`).join("\n");
+    return [
+      "<browser_state>",
+      `Current URL: ${state.url}`,
+      `Title: ${state.title}`,
+      `Open tabs:
+${tabs || "  (none)"}`,
+      "Interactive elements (only [index]ed elements are interactive):",
+      state.serializedText || "[empty page]",
+      "</browser_state>"
+    ].join("\n");
+  }
+};
+function userText(text) {
+  return { role: "user", content: text, timestamp: Date.now() };
+}
+function resultsAreDone(results) {
+  const last = results[results.length - 1];
+  return last !== void 0 && isDoneResult(last);
+}
+
+// src/agent/context-builder.ts
+var BUDGET_WARN_FRACTION = 0.75;
+var REPETITION_THRESHOLD = 5;
+var STAGNATION_THRESHOLD = 5;
+var ACTION_WINDOW = 20;
+var FINGERPRINT_WINDOW = 5;
+function perceive(driver, vision) {
+  return driver.getState({ screenshot: vision !== "off" });
+}
+function budgetNudge(stepNumber, maxSteps) {
+  if (maxSteps <= 0) return void 0;
+  if (stepNumber / maxSteps < BUDGET_WARN_FRACTION) return void 0;
+  return `Budget warning: you are on step ${stepNumber} of ${maxSteps}. Consolidate what you have found and call done soon.`;
+}
+function actionSignature(action) {
+  const [name] = Object.keys(action);
+  return `${name}|${JSON.stringify(action[name] ?? {})}`;
+}
+function pageFingerprint(state) {
+  const text = state.serializedText;
+  return `${state.url}|${text.length}|${text.slice(0, 64)}`;
+}
+var LoopDetector = class {
+  actionHashes = [];
+  fingerprints = [];
+  stagnation = 0;
+  /** Record a step's executed actions and the page state it was taken against. */
+  record(output, state) {
+    for (const action of output?.action ?? []) {
+      this.actionHashes.push(actionSignature(action));
+    }
+    while (this.actionHashes.length > ACTION_WINDOW) this.actionHashes.shift();
+    const fingerprint = pageFingerprint(state);
+    const previous = this.fingerprints[this.fingerprints.length - 1];
+    this.stagnation = previous === fingerprint ? this.stagnation + 1 : 0;
+    this.fingerprints.push(fingerprint);
+    while (this.fingerprints.length > FINGERPRINT_WINDOW) this.fingerprints.shift();
+  }
+  /** Advisory nudges to inject this step (may be empty). */
+  nudges() {
+    const out = [];
+    const repetition = this.maxRepetition();
+    if (repetition >= REPETITION_THRESHOLD) {
+      out.push(
+        `You have repeated the same action ${repetition} times. If you are not making progress, try a different approach or call done.`
+      );
+    }
+    if (this.stagnation >= STAGNATION_THRESHOLD) {
+      out.push(
+        `The page has not changed for ${this.stagnation} steps. Re-read the state and consider a different action.`
+      );
+    }
+    return out;
+  }
+  maxRepetition() {
+    const counts = /* @__PURE__ */ new Map();
+    let max = 0;
+    for (const hash of this.actionHashes) {
+      const next = (counts.get(hash) ?? 0) + 1;
+      counts.set(hash, next);
+      if (next > max) max = next;
+    }
+    return max;
+  }
+};
+
+// src/agent/event-stream.ts
+function isTerminal(event) {
+  return event.type === "done" || event.type === "error";
+}
+var AgentEventStream = class {
+  typed = /* @__PURE__ */ new Map();
+  any = /* @__PURE__ */ new Set();
+  /** Fan an event out to all listeners. */
+  emit(event) {
+    for (const cb of this.typed.get(event.type) ?? []) cb(event);
+    for (const cb of this.any) cb(event);
+  }
+  /** Subscribe to one event type. Returns an unsubscribe function. */
+  on(type, cb) {
+    let set = this.typed.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.typed.set(type, set);
+    }
+    set.add(cb);
+    return () => {
+      set?.delete(cb);
+    };
+  }
+  /** Subscribe to every event. Returns an unsubscribe function. */
+  onEvent(cb) {
+    this.any.add(cb);
+    return () => {
+      this.any.delete(cb);
+    };
+  }
+  /**
+   * An async iterable of every event, ending after the terminal (done/error).
+   * Subscribe before/while a run produces events; iterating after a run has
+   * already finished (with no further run) parks on the first `next()`.
+   */
+  events() {
+    const buffer = [];
+    let pending = null;
+    let finished = false;
+    const unsub = this.onEvent((event) => {
+      if (pending) {
+        const resolve = pending;
+        pending = null;
+        resolve({ value: event, done: false });
+      } else {
+        buffer.push(event);
+      }
+      if (isTerminal(event)) finished = true;
+    });
+    const iterator = {
+      next() {
+        const head = buffer.shift();
+        if (head !== void 0) return Promise.resolve({ value: head, done: false });
+        if (finished) {
+          unsub();
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => {
+          pending = resolve;
+        });
+      },
+      return() {
+        unsub();
+        return Promise.resolve({ value: void 0, done: true });
+      },
+      [Symbol.asyncIterator]() {
+        return this;
+      }
+    };
+    return iterator;
+  }
+};
+function toTypedAction(name, params) {
+  return { kind: name, ...params };
+}
+function summarizeActions(output) {
+  const names = (output?.action ?? []).map((entry) => Object.keys(entry)[0]).filter((name) => name !== void 0);
+  return names.length > 0 ? `Running ${names.join(", ")}.` : "";
+}
+function assembleNarration(output, results) {
+  const done2 = results.find(isDoneResult);
+  if (done2) {
+    const text = (done2.extractedContent ?? "").trim();
+    if (text) return text;
+    return done2.success ? "Task complete." : "Stopping \u2014 the task could not be completed.";
+  }
+  const parts = [];
+  const evaluation = output?.evaluation_previous_goal?.trim();
+  const nextGoal = output?.next_goal?.trim();
+  if (evaluation) parts.push(evaluation);
+  if (nextGoal) parts.push(nextGoal);
+  if (parts.length === 0) {
+    const summary = summarizeActions(output);
+    if (summary) parts.push(summary);
+  }
+  if (parts.length === 0) {
+    const errored = results.find((result) => result.error !== void 0);
+    if (errored?.error) parts.push(errored.error);
+  }
+  return parts.join(" ").trim();
+}
+
+// src/agent/executor.ts
+function snapshot(session) {
+  const focus = session.registry.focusedTargetId;
+  if (!focus) return {};
+  return { url: session.registry.getCurrentUrl(focus), focus };
+}
+async function multiAct(input) {
+  const {
+    actions,
+    registry,
+    ctx,
+    session,
+    secrets,
+    allSensitiveData,
+    signal,
+    shouldContinue,
+    emit
+  } = input;
+  const step = input.step ?? 0;
+  const results = [];
+  const limit = Math.min(actions.length, input.maxActions ?? actions.length);
+  for (let i = 0; i < limit; i++) {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    if (shouldContinue && !shouldContinue()) break;
+    const parsed = parseAction(actions[i]);
+    if (!parsed) {
+      results.push(
+        stepResult({ error: `Malformed action at position ${i} (expected a single-key object)` })
+      );
+      break;
+    }
+    if (i > 0 && parsed.name === "done") break;
+    const before = snapshot(session);
+    emit?.({
+      type: "action-started",
+      step,
+      index: i,
+      name: parsed.name,
+      action: toTypedAction(parsed.name, parsed.params),
+      params: parsed.params
+    });
+    const elementIndex = typeof parsed.params.index === "number" ? parsed.params.index : void 0;
+    if (input.demoMode && elementIndex !== void 0) {
+      await ctx.driver.highlightElement(elementIndex, { signal });
+    }
+    const result = await registry.execute(
+      parsed.name,
+      parsed.params,
+      ctx,
+      secrets,
+      allSensitiveData
+    );
+    if (input.demoMode && elementIndex !== void 0) {
+      await ctx.driver.clearHighlight({ signal });
+    }
+    results.push(result);
+    emit?.({ type: "action-finished", step, index: i, name: parsed.name, result });
+    const isLast = i === limit - 1;
+    if (isDoneResult(result) || result.error !== void 0 || isLast) break;
+    if (registry.get(parsed.name)?.terminatesSequence) break;
+    const after = snapshot(session);
+    if (after.url !== before.url || after.focus !== before.focus) break;
+  }
+  return results;
+}
+
+// src/agent/history.ts
+function stepDurationSeconds(metadata) {
+  return (metadata.stepEndTime - metadata.stepStartTime) / 1e3;
+}
+function firstError2(results) {
+  for (const result of results) {
+    if (result.error !== void 0) return result.error;
+  }
+  return void 0;
+}
+var AgentHistoryList = class _AgentHistoryList {
+  history = [];
+  usage;
+  /** Set once by the loop when it exits; drives StopReason mapping (no regex). */
+  terminationReason;
+  /** Append a step. Items are never mutated or reordered afterwards. */
+  add(item) {
+    this.history.push(item);
+  }
+  get length() {
+    return this.history.length;
+  }
+  numberOfSteps() {
+    return this.history.length;
+  }
+  lastResult() {
+    const last = this.history[this.history.length - 1];
+    if (!last) return void 0;
+    return last.result[last.result.length - 1];
+  }
+  /** The `extractedContent` of the last result of the last step. */
+  finalResult() {
+    return this.lastResult()?.extractedContent;
+  }
+  /** True once a terminal `done` result has been recorded. */
+  isDone() {
+    const last = this.lastResult();
+    return last !== void 0 && isDoneResult(last);
+  }
+  /** The agent's self-reported success — only meaningful when done, else undefined. */
+  isSuccessful() {
+    const last = this.lastResult();
+    if (!last || !isDoneResult(last)) return void 0;
+    return last.success;
+  }
+  /** One error (the first) per step; undefined where a step had none. */
+  errors() {
+    return this.history.map((step) => firstError2(step.result));
+  }
+  hasErrors() {
+    return this.errors().some((error) => error !== void 0);
+  }
+  /** Per-step page URLs. */
+  urls() {
+    return this.history.map((step) => step.state.url);
+  }
+  /** Flattened action names across all steps (one per single-key action object). */
+  actionNames() {
+    const names = [];
+    for (const step of this.history) {
+      for (const action of step.modelOutput?.action ?? []) {
+        const [name] = Object.keys(action);
+        if (name) names.push(name);
+      }
+    }
+    return names;
+  }
+  /** Sum of per-step durations (seconds). */
+  totalDurationSeconds() {
+    return this.history.reduce(
+      (sum, step) => sum + (step.metadata ? stepDurationSeconds(step.metadata) : 0),
+      0
+    );
+  }
+  /** Plain-data snapshot for persistence (design/04b §4.1 `AgentHistoryList.save_to_file`). */
+  toJSON() {
+    return { version: 1, history: this.history, terminationReason: this.terminationReason };
+  }
+  /**
+   * Rebuild a list from a plain-data snapshot. The CALLER is responsible for
+   * schema-validating untrusted input before calling this (replay.ts's
+   * `loadHistoryFromFile` is the trust boundary — this constructor trusts its
+   * argument, matching every other in-process history mutation in this class).
+   *
+   * `interactedElements` entries round-trip through JSON as `null` (undefined
+   * array elements serialize that way — `Type.Array` has no other way to carry
+   * a "no element" slot); normalize them back to `undefined` here so in-memory
+   * histories built directly (never touching JSON) and loaded ones agree.
+   */
+  static fromJSON(data) {
+    const list = new _AgentHistoryList();
+    for (const item of data.history) {
+      const interactedElements = item.state.interactedElements?.map(
+        (el) => el ?? void 0
+      );
+      list.add(
+        interactedElements ? { ...item, state: { ...item.state, interactedElements } } : item
+      );
+    }
+    list.terminationReason = data.terminationReason;
+    return list;
+  }
+};
+
+// src/observability/logger.ts
+var RANK = { debug: 10, info: 20, warn: 30, error: 40 };
+function renderValue(value) {
+  if (typeof value === "string") return value;
+  if (value === null || value === void 0) return String(value);
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+function format(level, message, fields) {
+  const keys = Object.keys(fields);
+  if (keys.length === 0) return `[${level}] ${message}`;
+  const rendered = keys.map((key) => `${key}=${renderValue(fields[key])}`).join(" ");
+  return `[${level}] ${message} ${rendered}`;
+}
+var defaultSink = (level, line) => {
+  const method = level === "debug" ? console.debug : level === "warn" ? console.warn : level === "error" ? console.error : console.info;
+  method(line);
+};
+function createLogger(options = {}) {
+  const level = options.level ?? "info";
+  const base = options.fields ?? {};
+  const sink = options.sink ?? defaultSink;
+  const min = RANK[level];
+  const write = (at, message, fields) => {
+    if (RANK[at] < min) return;
+    sink(at, format(at, message, fields ? { ...base, ...fields } : base));
+  };
+  return {
+    debug: (message, fields) => write("debug", message, fields),
+    info: (message, fields) => write("info", message, fields),
+    warn: (message, fields) => write("warn", message, fields),
+    error: (message, fields) => write("error", message, fields),
+    child: (fields) => createLogger({ level, fields: { ...base, ...fields }, sink })
+  };
+}
+var silentLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  },
+  child() {
+    return silentLogger;
+  }
+};
+
+// src/agent/captcha-watchdog.ts
+var VENDOR_PATTERNS = [
+  { vendor: "recaptcha", pattern: /\brecaptcha\b/i },
+  { vendor: "hcaptcha", pattern: /\bhcaptcha\b/i },
+  {
+    vendor: "cloudflare",
+    pattern: /checking (?:if )?(?:the )?(?:connection|site connection) is secure|cf-turnstile|cloudflare/i
+  },
+  { vendor: "perimeterx", pattern: /perimeterx|_px-captcha|press\s*(?:&|and)\s*hold/i },
+  { vendor: "datadome", pattern: /datadome/i },
+  { vendor: "akamai", pattern: /akamai bot manager|ak_bmsc/i }
+];
+var GENERIC_PATTERN = /\b(are you a (?:human|robot)|i.?m not a robot|prove you.?re (?:not a )?robot|verify you are human|verify you are a human|unusual traffic|complete the security check|access denied.{0,20}bot|suspected automated (?:traffic|access))\b/i;
+function detectCaptcha(state) {
+  const haystack = `${state.title}
+${state.serializedText}`;
+  for (const { vendor, pattern } of VENDOR_PATTERNS) {
+    const match = haystack.match(pattern);
+    if (match) return { vendor, url: state.url, title: state.title, matchedText: match[0] };
+  }
+  const generic = haystack.match(GENERIC_PATTERN);
+  if (generic) {
+    return { vendor: "generic", url: state.url, title: state.title, matchedText: generic[0] };
+  }
+  return void 0;
+}
+var CaptchaWatchdog = class {
+  last;
+  /** Check state; returns a signal only the FIRST time it's seen for this vendor+url. */
+  check(state) {
+    const signal = detectCaptcha(state);
+    if (!signal) {
+      this.last = void 0;
+      return void 0;
+    }
+    const key = `${signal.vendor}|${signal.url}`;
+    if (key === this.last) return void 0;
+    this.last = key;
+    return signal;
+  }
+};
+
+// src/agent/step-loop.ts
+import {
+  StructuredOutputError,
+  generateObject
+} from "@ap3x/ai";
+import {
+  buildInteractedElement
+} from "@ap3x/browser";
+import { Type as Type4 } from "@sinclair/typebox";
+function anySignal(...signals) {
+  const present = signals.filter((s) => s !== void 0);
+  if (present.length === 0) return void 0;
+  if (present.length === 1) return present[0];
+  return AbortSignal.any(present);
+}
+var StepLoop = class {
+  deps;
+  log;
+  loopDetector = new LoopDetector();
+  captchaWatchdog = new CaptchaWatchdog();
+  nSteps = 1;
+  consecutiveFailures = 0;
+  lastStepDurationSeconds;
+  pendingNudges = [];
+  done = false;
+  stopped = false;
+  paused = false;
+  pauseGate;
+  pauseRelease;
+  maxSteps;
+  runSignal;
+  runDeadline;
+  constructor(deps) {
+    this.deps = deps;
+    this.log = deps.logger ?? silentLogger;
+    this.maxSteps = deps.limits.maxSteps;
+  }
+  /** Fan an event out to the O2 stream (no-op when no sink is wired). */
+  emit(event) {
+    this.deps.emit?.(event);
+  }
+  // --- control surface -------------------------------------------------------
+  pause() {
+    if (this.paused) return;
+    this.paused = true;
+    this.pauseGate = new Promise((resolve) => {
+      this.pauseRelease = resolve;
+    });
+    this.emit({ type: "paused" });
+  }
+  resume() {
+    const wasPaused = this.paused;
+    this.paused = false;
+    this.pauseRelease?.();
+    this.pauseGate = void 0;
+    this.pauseRelease = void 0;
+    if (wasPaused) this.emit({ type: "resumed" });
+  }
+  stop() {
+    this.stopped = true;
+    this.resume();
+  }
+  get isDone() {
+    return this.done;
+  }
+  /** Current consecutive-failure count (observability / tests). */
+  get failures() {
+    return this.consecutiveFailures;
+  }
+  /** The 1-based number of the step about to run (observability / tests). */
+  get currentStep() {
+    return this.nSteps;
+  }
+  // --- run / step ------------------------------------------------------------
+  async run(options = {}) {
+    this.maxSteps = options.maxSteps ?? this.deps.limits.maxSteps;
+    this.runSignal = options.signal;
+    this.runDeadline = this.deps.limits.runTimeoutMs ? AbortSignal.timeout(this.deps.limits.runTimeoutMs) : void 0;
+    this.emit({
+      type: "run-started",
+      task: this.deps.task ?? "",
+      maxSteps: this.maxSteps,
+      startedAt: Date.now()
+    });
+    this.log.info("run started", { maxSteps: this.maxSteps });
+    try {
+      while (this.nSteps <= this.maxSteps) {
+        await this.waitWhilePaused();
+        if (this.stopped || this.runSignal?.aborted) {
+          this.deps.history.terminationReason = this.runSignal?.aborted ? "aborted" : "stopped";
+          break;
+        }
+        if (this.runDeadline?.aborted) {
+          this.deps.history.terminationReason = "run_timeout";
+          this.recordSyntheticFailure(
+            `Stopped: the run exceeded its ${this.deps.limits.runTimeoutMs}ms time budget.`
+          );
+          break;
+        }
+        const ceiling = this.deps.limits.maxFailures + (this.deps.limits.finalResponseAfterFailure ? 1 : 0);
+        if (this.consecutiveFailures >= ceiling) {
+          this.deps.messageManager.recordSystemNote(
+            this.nSteps,
+            `Stopped after ${this.consecutiveFailures} consecutive failures.`
+          );
+          this.deps.history.terminationReason = "max_failures";
+          break;
+        }
+        const isDone = await this.step();
+        if (isDone) {
+          this.deps.history.terminationReason = "done";
+          break;
+        }
+        if (this.stopped) {
+          this.deps.history.terminationReason = this.runSignal?.aborted ? "aborted" : "stopped";
+          break;
+        }
+      }
+      if (!this.done && this.nSteps > this.maxSteps) {
+        this.deps.history.terminationReason = "max_steps";
+        this.recordSyntheticFailure(
+          "Failed to complete the task within the maximum number of steps."
+        );
+      }
+      this.deps.history.usage = this.deps.ledger.summary();
+      await this.deps.hooks?.onDone?.(this.deps.history);
+      this.emit({
+        type: "done",
+        success: this.deps.history.isSuccessful() ?? false,
+        finalText: this.deps.history.finalResult() ?? "",
+        steps: this.deps.history.length
+      });
+      this.log.info("run finished", {
+        steps: this.deps.history.length,
+        done: this.deps.history.isDone()
+      });
+      return this.deps.history;
+    } catch (error) {
+      this.emit({ type: "error", message: errorText(error), step: this.nSteps });
+      throw error;
+    }
+  }
+  /**
+   * One perceive→decide→act→record cycle. Returns whether the task is now done.
+   * A no-op (returns false) when paused/stopped/already-done.
+   */
+  async step() {
+    if (this.paused || this.stopped || this.done) return false;
+    const stepStart = Date.now();
+    const stepSignal = anySignal(
+      this.runSignal,
+      this.runDeadline,
+      AbortSignal.timeout(this.deps.limits.stepTimeoutMs)
+    );
+    let state;
+    try {
+      state = await perceive(this.deps.driver, this.deps.vision);
+    } catch (error) {
+      this.emit({ type: "step-started", step: this.nSteps, url: "", title: "" });
+      this.log.warn("perceive failed", { step: this.nSteps, error: errorText(error) });
+      this.recordWholeStepFailure(errorText(error), placeholderState(), stepStart);
+      return false;
+    }
+    const histState = historyState(state, this.deps.sensitiveData);
+    this.emit({
+      type: "step-started",
+      step: this.nSteps,
+      url: histState.url,
+      title: histState.title
+    });
+    this.log.info("step", { step: this.nSteps, url: histState.url });
+    const captcha = this.captchaWatchdog.check(state);
+    if (captcha) {
+      this.emit({ type: "captcha-detected", step: this.nSteps, ...captcha });
+      this.log.warn("captcha detected", {
+        step: this.nSteps,
+        vendor: captcha.vendor,
+        url: state.url
+      });
+    }
+    const nudges = [...this.pendingNudges];
+    this.pendingNudges = [];
+    const budget = budgetNudge(this.nSteps, this.maxSteps);
+    if (budget) nudges.push(budget);
+    nudges.push(...this.loopDetector.nudges());
+    this.deps.messageManager.maybeCompact(this.nSteps);
+    const forced = this.nSteps >= this.maxSteps || this.deps.limits.finalResponseAfterFailure && this.consecutiveFailures >= this.deps.limits.maxFailures;
+    if (forced) {
+      nudges.push(
+        "This is your final step. Your only available tool is done \u2014 set success honestly and include everything you have found."
+      );
+    }
+    const schema = buildAgentOutputSchema(
+      forced ? this.doneOnlyUnion() : this.deps.registry.actionUnion(state.url),
+      this.deps.variant
+    );
+    const messages = this.deps.messageManager.buildMessages(state, {
+      stepNumber: this.nSteps,
+      maxSteps: this.maxSteps,
+      nudges,
+      attachScreenshot: this.deps.vision === "everyStep"
+    });
+    let output;
+    try {
+      const llmSignal = anySignal(stepSignal, AbortSignal.timeout(this.deps.limits.llmTimeoutMs));
+      const { object, usage } = await generateObject(this.deps.model, messages, schema, {
+        ...this.deps.llmStreamOptions,
+        signal: llmSignal
+      });
+      this.deps.ledger.record(this.deps.model.id, usage);
+      output = object;
+    } catch (error) {
+      return this.handleLlmError(error, histState, stepStart);
+    }
+    histState.interactedElements = output.action.map((action) => {
+      const parsed = parseAction(action);
+      const index = parsed && typeof parsed.params.index === "number" ? parsed.params.index : void 0;
+      if (index === void 0) return void 0;
+      const node = state.selectorMap.get(index);
+      return node ? buildInteractedElement(node) : void 0;
+    });
+    this.emit({
+      type: "model-thought",
+      step: this.nSteps,
+      thinking: output.thinking,
+      evaluationPreviousGoal: output.evaluation_previous_goal,
+      memory: output.memory,
+      nextGoal: output.next_goal
+    });
+    await this.deps.hooks?.onStep?.(histState, output, this.nSteps);
+    const secrets = this.deps.sensitiveData ? resolveSecretsForUrl(this.deps.sensitiveData, state.url) : {};
+    const ctx = this.buildContext(state.url, Object.keys(secrets).length > 0, stepSignal);
+    let results;
+    try {
+      results = await multiAct({
+        actions: output.action,
+        registry: this.deps.registry,
+        ctx,
+        session: this.deps.session,
+        secrets,
+        allSensitiveData: this.deps.sensitiveData,
+        signal: stepSignal,
+        shouldContinue: () => !this.stopped && !this.paused,
+        maxActions: this.deps.limits.maxActionsPerStep,
+        emit: (event) => this.emit(event),
+        step: this.nSteps,
+        demoMode: this.deps.demoMode
+      });
+    } catch (error) {
+      if (this.stopped || this.runSignal?.aborted) {
+        this.stopped = true;
+        return false;
+      }
+      results = [stepResult({ error: errorText(error) })];
+    }
+    if (this.runSignal?.aborted) {
+      this.stopped = true;
+    } else {
+      this.accountFailures(results);
+    }
+    this.loopDetector.record(output, state);
+    this.recordStep(output, results, histState, stepStart);
+    const isDone = resultsAreDone(results);
+    if (isDone) this.done = true;
+    this.nSteps += 1;
+    return isDone;
+  }
+  // --- internals -------------------------------------------------------------
+  async waitWhilePaused() {
+    while (this.paused && !this.stopped) {
+      if (!this.pauseGate) {
+        this.pauseGate = new Promise((resolve) => {
+          this.pauseRelease = resolve;
+        });
+      }
+      await this.pauseGate;
+    }
+  }
+  /** Consecutive-failure accounting (design/07 §7.2.3). */
+  accountFailures(results) {
+    const hasError = results.some((r) => r.error !== void 0);
+    if (!hasError) {
+      this.consecutiveFailures = 0;
+    } else if (results.length === 1) {
+      this.consecutiveFailures += 1;
+    }
+  }
+  handleLlmError(error, state, stepStart) {
+    if (this.stopped || this.runSignal?.aborted) {
+      this.stopped = true;
+      return false;
+    }
+    if (error instanceof StructuredOutputError && error.reason === "empty") {
+      const results = [
+        doneResult(false, { extractedContent: "No next action returned by the model." })
+      ];
+      this.recordStep(void 0, results, state, stepStart);
+      this.done = true;
+      this.nSteps += 1;
+      return true;
+    }
+    if (error instanceof StructuredOutputError && (error.reason === "invalid" || error.reason === "truncated")) {
+      this.pendingNudges.push(
+        "Your previous output did not match the required schema. Respond with a single valid object exactly matching the schema, including a non-empty action list."
+      );
+      this.recordWholeStepFailure(`Invalid model output: ${error.message}`, state, stepStart);
+      return false;
+    }
+    this.recordWholeStepFailure(errorText(error), state, stepStart);
+    return false;
+  }
+  /** A whole-step failure: increment the counter and record an error result. */
+  recordWholeStepFailure(message, state, stepStart) {
+    this.consecutiveFailures += 1;
+    const results = [stepResult({ error: message })];
+    this.recordStep(void 0, results, state, stepStart);
+    this.nSteps += 1;
+  }
+  /** Append a synthetic terminal failure entry (max steps / consecutive failures). */
+  recordSyntheticFailure(message) {
+    this.deps.messageManager.recordSystemNote(this.nSteps, message);
+    this.deps.history.add({
+      result: [doneResult(false, { extractedContent: message })],
+      state: placeholderState(),
+      metadata: this.metadata(Date.now())
+    });
+    this.done = true;
+  }
+  /** Fold a step into both the message-manager history and the AgentHistoryList. */
+  recordStep(output, results, state, stepStart) {
+    this.deps.messageManager.recordStep(this.nSteps, output, results);
+    this.deps.history.add({
+      modelOutput: output,
+      result: results,
+      state,
+      metadata: this.metadata(stepStart),
+      stateMessage: this.deps.messageManager.stateMessageText
+    });
+    const end = Date.now();
+    this.lastStepDurationSeconds = (end - stepStart) / 1e3;
+    this.emit({
+      type: "step-finished",
+      step: this.nSteps,
+      narration: assembleNarration(output, results),
+      output,
+      results
+    });
+  }
+  metadata(stepStart) {
+    return {
+      stepStartTime: stepStart,
+      stepEndTime: Date.now(),
+      stepNumber: this.nSteps,
+      stepInterval: this.lastStepDurationSeconds
+    };
+  }
+  buildContext(pageUrl, hasSensitiveData, signal) {
+    return {
+      session: this.deps.session,
+      driver: this.deps.driver,
+      pageUrl,
+      fileSystem: this.deps.fileSystem,
+      extractionLlm: this.deps.extractionLlm,
+      availableFilePaths: this.deps.availableFilePaths ?? [],
+      hasSensitiveData,
+      signal
+    };
+  }
+  /** A single-key union carrying only `done` (forced-termination schema). */
+  doneOnlyUnion() {
+    const done2 = this.deps.registry.get("done");
+    const schema = done2?.schema ?? Type4.Object({ text: Type4.String(), success: Type4.Boolean() });
+    return Type4.Object({ done: schema }, { additionalProperties: false, title: "done" });
+  }
+};
+function historyState(state, sensitiveData) {
+  const mask = (text) => sensitiveData ? maskOutbound(text, sensitiveData) : text;
+  return {
+    url: mask(state.url),
+    title: mask(state.title),
+    tabs: state.tabs.map((tab) => ({ ...tab, url: mask(tab.url), title: mask(tab.title) })),
+    screenshot: state.screenshot
+  };
+}
+function placeholderState() {
+  return { url: "", title: "", tabs: [] };
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/usage/ledger.ts
+var UsageLedger = class {
+  byModel = /* @__PURE__ */ new Map();
+  /** Fold one LLM call's usage into the running totals for `model`. */
+  record(model, usage) {
+    let stats = this.byModel.get(model);
+    if (!stats) {
+      stats = {
+        model,
+        invocations: 0,
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: 0
+      };
+      this.byModel.set(model, stats);
+    }
+    stats.invocations += 1;
+    stats.input += usage.input;
+    stats.output += usage.output;
+    stats.cacheRead += usage.cacheRead;
+    stats.cacheWrite += usage.cacheWrite;
+    stats.totalTokens += usage.totalTokens;
+    stats.cost += usage.cost.total;
+  }
+  /** The end-of-run summary (per-model + grand totals). */
+  summary() {
+    const perModel = [...this.byModel.values()];
+    return {
+      perModel,
+      totalTokens: perModel.reduce((sum, m) => sum + m.totalTokens, 0),
+      totalCost: perModel.reduce((sum, m) => sum + m.cost, 0),
+      totalInvocations: perModel.reduce((sum, m) => sum + m.invocations, 0)
+    };
+  }
+};
+
+// src/agent/gif.ts
+import { createRequire } from "module";
+import { PLACEHOLDER_SCREENSHOT } from "@ap3x/browser";
+
+// src/agent/png-decode.ts
+import { inflateSync } from "zlib";
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+function decodePngBase64(base64) {
+  try {
+    return decodePng(Buffer.from(base64, "base64"));
+  } catch {
+    return void 0;
+  }
+}
+function decodePng(buf) {
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) return void 0;
+  let width;
+  let height;
+  let bitDepth;
+  let colorType;
+  let interlace;
+  const idat = [];
+  let offset = 8;
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString("ascii", offset + 4, offset + 8);
+    const dataStart = offset + 8;
+    const data = buf.subarray(dataStart, dataStart + length);
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data.readUInt8(8);
+      colorType = data.readUInt8(9);
+      interlace = data.readUInt8(12);
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+    offset = dataStart + length + 4;
+  }
+  if (width === void 0 || height === void 0 || bitDepth !== 8 || interlace !== 0 || colorType !== 2 && colorType !== 6 || idat.length === 0) {
+    return void 0;
+  }
+  const channels = colorType === 6 ? 4 : 3;
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const rgba = new Uint8Array(width * height * 4);
+  let prevLine = new Uint8Array(stride);
+  let pos = 0;
+  for (let y = 0; y < height; y++) {
+    if (pos >= raw.length) return void 0;
+    const filterType = raw[pos];
+    pos += 1;
+    if (pos + stride > raw.length) return void 0;
+    const line = raw.subarray(pos, pos + stride);
+    pos += stride;
+    const out = new Uint8Array(stride);
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? out[x - channels] : 0;
+      const b = prevLine[x];
+      const c = x >= channels ? prevLine[x - channels] : 0;
+      const raw8 = line[x];
+      let value;
+      switch (filterType) {
+        case 0:
+          value = raw8;
+          break;
+        case 1:
+          value = raw8 + a;
+          break;
+        case 2:
+          value = raw8 + b;
+          break;
+        case 3:
+          value = raw8 + Math.floor((a + b) / 2);
+          break;
+        case 4:
+          value = raw8 + paeth(a, b, c);
+          break;
+        default:
+          return void 0;
+      }
+      out[x] = value & 255;
+    }
+    for (let x = 0; x < width; x++) {
+      const si = x * channels;
+      const di = (y * width + x) * 4;
+      rgba[di] = out[si];
+      rgba[di + 1] = out[si + 1];
+      rgba[di + 2] = out[si + 2];
+      rgba[di + 3] = channels === 4 ? out[si + 3] : 255;
+    }
+    prevLine = out;
+  }
+  return { width, height, rgba };
+}
+
+// src/agent/gif.ts
+var { GIFEncoder, applyPalette, quantize } = createRequire(import.meta.url)(
+  "gifenc"
+);
+var DEFAULT_FRAME_DURATION_MS = 3e3;
+var DEFAULT_MAX_COLORS = 256;
+function collectFrames(history) {
+  const frames = [];
+  for (const step of history.history) {
+    const shot = step.state.screenshot;
+    if (!shot || shot === PLACEHOLDER_SCREENSHOT) continue;
+    const decoded = decodePngBase64(shot);
+    if (decoded && (frames.length === 0 || sameSize(decoded, frames[0]))) {
+      frames.push(decoded);
+    }
+  }
+  return frames;
+}
+function sameSize(a, b) {
+  return a.width === b.width && a.height === b.height;
+}
+function encodeFramesToGif(frames, options = {}) {
+  if (frames.length === 0) return void 0;
+  const delay = options.frameDurationMs ?? DEFAULT_FRAME_DURATION_MS;
+  const maxColors = options.maxColors ?? DEFAULT_MAX_COLORS;
+  const repeat = options.repeat ?? 0;
+  const { width, height } = frames[0];
+  const gif = GIFEncoder();
+  for (const frame of frames) {
+    const palette = quantize(frame.rgba, maxColors);
+    const indexed = applyPalette(frame.rgba, palette);
+    gif.writeFrame(indexed, width, height, { palette, delay, repeat });
+  }
+  gif.finish();
+  return gif.bytes();
+}
+function generateRunGif(history, options = {}) {
+  return encodeFramesToGif(collectFrames(history), options);
+}
+
+// src/agent/judge.ts
+import {
+  generateObject as generateObject2
+} from "@ap3x/ai";
+import { PLACEHOLDER_SCREENSHOT as PLACEHOLDER_SCREENSHOT2 } from "@ap3x/browser";
+import { Type as Type5 } from "@sinclair/typebox";
+var JudgementResultSchema = Type5.Object({
+  reasoning: Type5.String(),
+  verdict: Type5.Boolean(),
+  failureReason: Type5.String(),
+  impossibleTask: Type5.Boolean(),
+  reachedCaptcha: Type5.Boolean()
+});
+var MAX_TEXT_CHARS = 4e4;
+var DEFAULT_MAX_IMAGES = 10;
+function truncate2(text) {
+  return text.length <= MAX_TEXT_CHARS ? text : `${text.slice(0, MAX_TEXT_CHARS)}...[truncated]`;
+}
+function formatSteps(history) {
+  return history.history.map((step, i) => {
+    const lines = [`Step ${i + 1}:`];
+    const actions = step.modelOutput?.action ?? [];
+    if (actions.length > 0) lines.push(`Actions: ${JSON.stringify(actions)}`);
+    step.result.forEach((result, j) => {
+      if (result.extractedContent) lines.push(`Result ${j + 1}: ${result.extractedContent}`);
+      if (result.error) lines.push(`Error ${j + 1}: ${result.error}`);
+    });
+    return lines.join("\n");
+  }).join("\n\n");
+}
+function selectScreenshots(history, maxImages) {
+  const shots = history.history.map((step) => step.state.screenshot).filter((shot) => !!shot && shot !== PLACEHOLDER_SCREENSHOT2);
+  return maxImages > 0 ? shots.slice(-maxImages) : [];
+}
+function buildSystemPrompt(hasGroundTruth) {
+  return [
+    "You are an expert judge evaluating a browser-automation agent's completed run.",
+    hasGroundTruth ? "A <ground_truth> block is provided below and takes ABSOLUTE precedence: if the run does not satisfy it, verdict MUST be false." : void 0,
+    "Judge, in order of importance: (1) whether the task was actually accomplished, matching the user's exact request \u2014 not a partial or approximate match; (2) whether the final output is complete and in the right format; (3) whether the browser interactions actually succeeded (don't just trust the agent's self-report \u2014 cross-check it against the trajectory and screenshots); (4) the quality of the agent's reasoning and recovery from errors.",
+    "Automatically fail the run if: it was blocked by a captcha or login wall, the output format is wrong or missing, the agent looped or crashed, a required step was skipped, the agent fabricated content not present in the page/screenshots, or `done` was called before the task was actually complete.",
+    "Set impossibleTask=true only when the task itself could not have been completed by any agent (a genuinely broken/inaccessible site, missing required credentials, a nonsensical request) \u2014 not merely because this agent performed poorly.",
+    "Set reachedCaptcha=true if any screenshot or error indicates a captcha/bot-detection challenge was encountered.",
+    "Be skeptical of the agent's own success claim; verify it against the trajectory. Respond with the exact JSON shape requested by the schema."
+  ].filter((line) => !!line).join("\n");
+}
+function buildUserPrompt(task, finalResult, stepsText, groundTruth, imageCount) {
+  const sections = [
+    `<task>
+${truncate2(task) || "No task provided"}
+</task>`,
+    groundTruth ? `<ground_truth>
+${truncate2(groundTruth)}
+</ground_truth>` : void 0,
+    `<agent_trajectory>
+${truncate2(stepsText) || "No agent trajectory provided"}
+</agent_trajectory>`,
+    `<final_result>
+${truncate2(finalResult) || "No final result provided"}
+</final_result>`,
+    `${imageCount} screenshot(s) from execution are attached.`,
+    "Evaluate this run against the criteria above and respond with the required JSON structure."
+  ];
+  return sections.filter((line) => !!line).join("\n\n");
+}
+async function judgeRun(model, task, history, options = {}) {
+  const useVision = options.vision ?? true;
+  const maxImages = options.maxImages ?? DEFAULT_MAX_IMAGES;
+  const screenshots = useVision ? selectScreenshots(history, maxImages) : [];
+  const system = buildSystemPrompt(!!options.groundTruth);
+  const user = buildUserPrompt(
+    task,
+    history.finalResult() ?? "",
+    formatSteps(history),
+    options.groundTruth,
+    screenshots.length
+  );
+  const userParts = [{ type: "text", text: user }];
+  for (const shot of screenshots)
+    userParts.push({ type: "image", data: shot, mimeType: "image/png" });
+  const messages = [
+    { role: "user", content: system, timestamp: Date.now() },
+    { role: "user", content: userParts, timestamp: Date.now() }
+  ];
+  const { object, usage } = await generateObject2(model, messages, JudgementResultSchema, {
+    ...options.streamOptions,
+    signal: options.signal
+  });
+  return { judgement: object, usage };
+}
+
+// src/agent/video.ts
+function sameSize2(a, b) {
+  return a.width === b.width && a.height === b.height;
+}
+function decodeFrames(frames) {
+  const decoded = [];
+  for (const frame of frames) {
+    const image = decodePngBase64(frame.data);
+    if (image && (decoded.length === 0 || sameSize2(image, decoded[0]))) {
+      decoded.push(image);
+    }
+  }
+  return decoded;
+}
+function generateRunVideoGif(frames, options = {}) {
+  const DEFAULT_VIDEO_FRAME_MS = 200;
+  return encodeFramesToGif(decodeFrames(frames), {
+    frameDurationMs: DEFAULT_VIDEO_FRAME_MS,
+    ...options
+  });
+}
+
+// src/agent/agent.ts
+import { randomUUID } from "crypto";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+import { BrowserDriver } from "@ap3x/browser";
+import { Type as Type6 } from "@sinclair/typebox";
+var screenshotAction = defineAction({
+  name: "screenshot",
+  description: "Capture a screenshot of the current page for visual inspection.",
+  schema: Type6.Object({}),
+  async execute(_params, ctx) {
+    const data = await ctx.driver.screenshot({ signal: ctx.signal });
+    return stepResult({
+      images: [{ name: "screenshot", data }],
+      metadata: { includeScreenshot: true }
+    });
+  }
+});
+var DEFAULT_LIMITS = {
+  maxSteps: 100,
+  maxFailures: 5,
+  maxActionsPerStep: 5,
+  finalResponseAfterFailure: true,
+  stepTimeoutMs: 18e4,
+  llmTimeoutMs: 9e4
+};
+var DEFAULT_SYSTEM_PROMPT = [
+  "You are an autonomous browser agent. You run in a loop: read the page state, decide the next action(s), execute them, then observe the result.",
+  "",
+  "Each turn you receive a state message with these sections:",
+  "- <user_request>: the task. Follow specific instructions literally; plan open-ended tasks yourself.",
+  "- <agent_history>: your previous steps as <step_N> blocks (evaluation, memory, next goal, results).",
+  "- <agent_state>: your file system, todo list, and any sensitive-data placeholders.",
+  "- <browser_state>: the current URL, tabs, and the numbered interactive elements. ONLY elements shown with an [index] are interactive.",
+  "- <read_state>: one-shot content from the previous step (shown once).",
+  "",
+  "Rules:",
+  "- Act only on element indexes present in <browser_state>. A stale index means the page changed \u2014 re-read it.",
+  "- Put page-changing actions (navigate, go_back, switch/open tab) last: anything queued after them is skipped and must be retried next step.",
+  "- When sensitive data applies, write <secret>key</secret> where the value should go; never write the raw value.",
+  "- Call done when the task is complete, impossible, or on the final step. Set success=true ONLY when fully complete, and report only facts you observed this session.",
+  "",
+  "Respond with a single object matching the required schema, including a non-empty action list."
+].join("\n");
+var Agent = class {
+  task;
+  options;
+  model;
+  session;
+  driver;
+  registry;
+  vision;
+  variant;
+  limits;
+  ledger = new UsageLedger();
+  historyList = new AgentHistoryList();
+  messageManager;
+  fileSystemDir;
+  stream = new AgentEventStream();
+  logger;
+  taskId = randomUUID();
+  fileSystem;
+  stepLoop;
+  pendingPaused = false;
+  pendingStopped = false;
+  /** Set once, after `run()` completes, when `output.generateGif` is on. */
+  lastGif;
+  /** Set once, after `run()` completes, when `output.recordHar` is on. */
+  lastHar;
+  /** Set once, after `run()` completes, when `output.recordVideo` is on. */
+  lastVideo;
+  /** Set once, after `run()` completes, when `judge` is on and the judge succeeded. */
+  lastJudgement;
+  constructor(task, options) {
+    this.task = task;
+    this.options = options;
+    this.model = options.llm.model;
+    this.logger = (options.logger ?? silentLogger).child({ taskId: this.taskId });
+    this.session = options.browser.session;
+    this.driver = options.browser.driver ?? new BrowserDriver(this.session);
+    this.vision = options.vision ?? "everyStep";
+    this.variant = options.output?.flash ? "flash" : options.output?.thinking === false ? "noThinking" : "thinking";
+    this.limits = { ...DEFAULT_LIMITS, ...options.limits };
+    this.fileSystemDir = options.fileSystemDir ?? join3(tmpdir(), `ap3x_agent_${randomUUID()}`);
+    this.registry = this.buildRegistry();
+    this.messageManager = new MessageManager({
+      systemPrompt: options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+      task,
+      sensitiveData: options.security?.sensitiveData,
+      fileSystemDescribe: () => this.fileSystem?.describe() ?? "",
+      todoContents: () => this.fileSystem?.getTodoContents() ?? "",
+      availableFilePaths: options.security?.availableFilePaths ?? []
+    });
+  }
+  /** The run history (populated as the loop runs). */
+  get history() {
+    return this.historyList;
+  }
+  /** The effective (cloned, vision-filtered) registry the agent drives. */
+  get effectiveRegistry() {
+    return this.registry;
+  }
+  /** The model this agent reasons with. */
+  get currentModel() {
+    return this.model;
+  }
+  /** The GIF run-summary built after `run()`, when `output.generateGif` is on. */
+  get gif() {
+    return this.lastGif;
+  }
+  /** The HAR 1.2 network-traffic artifact built after `run()`, when `output.recordHar` is on. */
+  get har() {
+    return this.lastHar;
+  }
+  /** The video-as-GIF artifact built after `run()`, when `output.recordVideo` is on. */
+  get video() {
+    return this.lastVideo;
+  }
+  /**
+   * The post-run judge's verdict, when `judge` is on. Informational — it never
+   * overrides the agent's own reported success. `undefined` if the judge was off
+   * or the evaluation failed.
+   */
+  get judgement() {
+    return this.lastJudgement;
+  }
+  /** The curated O2 event stream as an async iterable (`for await`). */
+  events() {
+    return this.stream.events();
+  }
+  /** Subscribe to one event type (callback sugar over {@link events}). */
+  on(type, cb) {
+    return this.stream.on(type, cb);
+  }
+  /** Subscribe to every event. Returns an unsubscribe function. */
+  onEvent(cb) {
+    return this.stream.onEvent(cb);
+  }
+  async run(options = {}) {
+    const loop = await this.ensureReady();
+    if (this.options.output?.recordHar && !this.session.har.isRecording) this.session.har.start();
+    if (this.options.output?.recordVideo && !this.session.screencast.isRecording) {
+      this.session.screencast.start();
+    }
+    return loop.run(options);
+  }
+  /** Drive one step (respects pause/stop). Returns whether the task is now done. */
+  async step() {
+    const loop = await this.ensureReady();
+    return loop.step();
+  }
+  pause() {
+    if (this.stepLoop) this.stepLoop.pause();
+    else this.pendingPaused = true;
+  }
+  resume() {
+    if (this.stepLoop) this.stepLoop.resume();
+    else this.pendingPaused = false;
+  }
+  stop() {
+    if (this.stepLoop) this.stepLoop.stop();
+    else this.pendingStopped = true;
+  }
+  // --- internals -------------------------------------------------------------
+  /** Clone the caller's (or default) registry and apply the vision filter (E7). */
+  buildRegistry() {
+    const base = this.options.tools ?? createDefaultRegistry();
+    const registry = base.clone();
+    if ((this.options.vision ?? "everyStep") === "off") {
+      registry.exclude("screenshot");
+    } else if (!registry.get("screenshot")) {
+      registry.register(screenshotAction);
+    }
+    return registry;
+  }
+  /**
+   * Compose the caller's `onDone` (if any) with the post-run artifact steps:
+   * the caller's hook always runs first, then — for whichever of GIF/HAR/video
+   * is gated on — the run's screenshots/network trace/screencast are turned
+   * into {@link Agent.gif} / {@link Agent.har} / {@link Agent.video}. Each
+   * artifact step is independently logged-and-swallowed on failure — a pure
+   * output artifact must never fail the run.
+   */
+  buildHooks() {
+    const userHooks = this.options.hooks;
+    const output = this.options.output ?? {};
+    if (!output.generateGif && !output.recordHar && !output.recordVideo && !this.options.judge) {
+      return userHooks ?? {};
+    }
+    const gifOptions = typeof output.generateGif === "object" ? output.generateGif : {};
+    const videoOptions = typeof output.recordVideo === "object" ? output.recordVideo : {};
+    return {
+      ...userHooks,
+      onDone: async (history) => {
+        await userHooks?.onDone?.(history);
+        if (output.generateGif) {
+          try {
+            this.lastGif = generateRunGif(history, gifOptions);
+          } catch (error) {
+            this.logger.warn("gif generation failed", {
+              error: error instanceof Error ? error.message : String(error)
+            });
+          }
+        }
+        if (output.recordHar && this.session.har.isRecording) {
+          try {
+            this.lastHar = this.session.har.stop();
+          } catch (error) {
+            this.logger.warn("har recording failed", {
+              error: error instanceof Error ? error.message : String(error)
+            });
+          }
+        }
+        if (output.recordVideo && this.session.screencast.isRecording) {
+          try {
+            const frames = this.session.screencast.stop();
+            this.lastVideo = generateRunVideoGif(frames, videoOptions);
+          } catch (error) {
+            this.logger.warn("video generation failed", {
+              error: error instanceof Error ? error.message : String(error)
+            });
+          }
+        }
+        if (this.options.judge) {
+          try {
+            const cfg = typeof this.options.judge === "object" ? this.options.judge : {};
+            const judgeModel = cfg.model ?? this.model;
+            const { judgement, usage } = await judgeRun(judgeModel, this.task, history, {
+              groundTruth: cfg.groundTruth,
+              maxImages: cfg.maxImages,
+              vision: cfg.vision,
+              // ponytail: reuse the agent's per-call LLM overrides (auth) — correct
+              // for the default same-model judge; add a judge-specific override
+              // only if a split-provider judge ever needs different credentials.
+              streamOptions: this.options.llm.streamOptions
+            });
+            this.lastJudgement = judgement;
+            this.ledger.record(judgeModel.id, usage);
+            history.usage = this.ledger.summary();
+          } catch (error) {
+            this.logger.warn("judge evaluation failed", {
+              error: error instanceof Error ? error.message : String(error)
+            });
+          }
+        }
+      }
+    };
+  }
+  /** Create the FileSystem + StepLoop once; apply any buffered pause/stop. */
+  async ensureReady() {
+    if (this.stepLoop) return this.stepLoop;
+    this.fileSystem = await FileSystem.create(this.fileSystemDir);
+    this.stepLoop = new StepLoop({
+      model: this.model,
+      driver: this.driver,
+      session: this.session,
+      registry: this.registry,
+      fileSystem: this.fileSystem,
+      messageManager: this.messageManager,
+      history: this.historyList,
+      ledger: this.ledger,
+      vision: this.vision,
+      variant: this.variant,
+      limits: this.limits,
+      sensitiveData: this.options.security?.sensitiveData,
+      availableFilePaths: this.options.security?.availableFilePaths ?? [],
+      extractionLlm: this.options.llm.extraction,
+      llmStreamOptions: this.options.llm.streamOptions,
+      demoMode: this.options.demoMode,
+      hooks: this.buildHooks(),
+      task: this.task,
+      emit: (event) => this.stream.emit(event),
+      logger: this.logger
+    });
+    if (this.pendingStopped) this.stepLoop.stop();
+    else if (this.pendingPaused) this.stepLoop.pause();
+    return this.stepLoop;
+  }
+};
+
+// src/mcp/log.ts
+var mcpLogger = createLogger({
+  level: "info",
+  fields: { component: "mcp" },
+  sink: (_level, line) => process.stderr.write(`${line}
+`)
+});
+function logStderr(message) {
+  mcpLogger.info(message);
+}
+
+// src/mcp/server.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join4 } from "path";
+import { BrowserDriver as BrowserDriver2 } from "@ap3x/browser";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { Type as Type7 } from "@sinclair/typebox";
+var ACT_TOOLS = [
+  { tool: "browser_navigate", action: "navigate" },
+  { tool: "browser_click", action: "click" },
+  { tool: "browser_type", action: "input_text" },
+  { tool: "browser_scroll", action: "scroll" },
+  { tool: "browser_extract", action: "extract_content" },
+  { tool: "browser_go_back", action: "go_back" },
+  { tool: "browser_switch_tab", action: "switch_tab" },
+  { tool: "browser_close_tab", action: "close_tab" }
+];
+var GET_STATE_SCHEMA = Type7.Object({ include_screenshot: Type7.Optional(Type7.Boolean()) });
+var SCREENSHOT_SCHEMA = Type7.Object({ full_page: Type7.Optional(Type7.Boolean()) });
+var LIST_TABS_SCHEMA = Type7.Object({});
+var RUN_AGENT_SCHEMA = Type7.Object({
+  task: Type7.String(),
+  max_steps: Type7.Optional(Type7.Integer({ minimum: 1 }))
+});
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function actionResultToContent(result) {
+  if (result.error !== void 0) return errorResult(result.error);
+  const text = result.longTermMemory ?? result.extractedContent ?? "OK";
+  const content = [{ type: "text", text }];
+  for (const image of result.images ?? []) {
+    content.push({ type: "image", data: image.data, mimeType: "image/png" });
+  }
+  return { content };
+}
+async function getStateResult(driver, includeScreenshot) {
+  const state = await driver.getState({ screenshot: includeScreenshot });
+  const content = [
+    {
+      type: "text",
+      text: JSON.stringify({
+        url: state.url,
+        title: state.title,
+        tabs: state.tabs,
+        elements: state.serializedText
+      })
+    }
+  ];
+  if (state.screenshot)
+    content.push({ type: "image", data: state.screenshot, mimeType: "image/png" });
+  return { content };
+}
+async function screenshotResult(driver, fullPage, signal) {
+  const data = await driver.screenshot({ fullPage, signal });
+  return { content: [{ type: "image", data, mimeType: "image/png" }] };
+}
+function createBrowserMcpServer(options) {
+  const { session } = options;
+  const driver = options.driver ?? new BrowserDriver2(session);
+  const registry = options.registry ?? createDefaultRegistry();
+  function catalog() {
+    const tools = [];
+    for (const { tool, action } of ACT_TOOLS) {
+      const registered = registry.get(action);
+      if (!registered) continue;
+      tools.push({
+        name: tool,
+        description: registered.description,
+        inputSchema: registered.schema
+      });
+    }
+    tools.push({
+      name: "browser_get_state",
+      description: "Read the current page: url, title, tabs, and the numbered interactive elements the agent sees.",
+      inputSchema: GET_STATE_SCHEMA
+    });
+    tools.push({
+      name: "browser_screenshot",
+      description: "Capture a screenshot of the current page.",
+      inputSchema: SCREENSHOT_SCHEMA
+    });
+    tools.push({
+      name: "browser_list_tabs",
+      description: "List the open tabs with their 4-char ids.",
+      inputSchema: LIST_TABS_SCHEMA
+    });
+    if (options.llm) {
+      tools.push({
+        name: "browser_run_agent",
+        description: "Run an autonomous browser agent to complete a task end-to-end.",
+        inputSchema: RUN_AGENT_SCHEMA
+      });
+    }
+    return tools;
+  }
+  let fsPromise;
+  const fileSystem = () => {
+    if (!fsPromise) {
+      fsPromise = FileSystem.create(
+        options.fileSystemDir ?? join4(tmpdir2(), `ap3x_mcp_${randomUUID2()}`)
+      );
+    }
+    return fsPromise;
+  };
+  async function buildCtx(signal) {
+    const focus = session.registry.focusedTargetId;
+    return {
+      session,
+      driver,
+      pageUrl: focus ? session.registry.getCurrentUrl(focus) ?? "" : "",
+      fileSystem: await fileSystem(),
+      extractionLlm: options.llm?.extraction,
+      availableFilePaths: options.availableFilePaths ?? [],
+      hasSensitiveData: false,
+      signal
+    };
+  }
+  async function runAgent(args, signal) {
+    if (!options.llm) return errorResult("browser_run_agent is not available: no LLM configured.");
+    const task = typeof args.task === "string" ? args.task : "";
+    if (!task) return errorResult("browser_run_agent requires a 'task' string.");
+    const agent = new Agent(task, {
+      llm: options.llm,
+      browser: { session, driver },
+      limits: typeof args.max_steps === "number" ? { maxSteps: args.max_steps } : void 0
+    });
+    const history = await agent.run({ signal });
+    return textResult(
+      JSON.stringify({
+        done: history.isDone(),
+        success: history.isSuccessful(),
+        steps: history.length,
+        finalResult: history.finalResult(),
+        urls: history.urls(),
+        errors: history.errors().filter((error) => error !== void 0)
+      })
+    );
+  }
+  async function dispatch(name, args, signal) {
+    const act = ACT_TOOLS.find((mapping) => mapping.tool === name);
+    if (act) {
+      const ctx = await buildCtx(signal);
+      return actionResultToContent(await registry.execute(act.action, args, ctx));
+    }
+    switch (name) {
+      case "browser_get_state":
+        return getStateResult(driver, args.include_screenshot === true);
+      case "browser_screenshot":
+        return screenshotResult(driver, args.full_page === true, signal);
+      case "browser_list_tabs":
+        return textResult(JSON.stringify(driver.tabs()));
+      case "browser_run_agent":
+        return runAgent(args, signal);
+      default:
+        return errorResult(`Unknown tool "${name}"`);
+    }
+  }
+  const server = new Server(
+    {
+      name: options.serverInfo?.name ?? "ap3x-browser",
+      version: options.serverInfo?.version ?? "0.1.0"
+    },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: catalog() }));
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const name = request.params.name;
+    const args = request.params.arguments ?? {};
+    try {
+      return await dispatch(name, args, extra.signal);
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  });
+  return server;
+}
+async function runBrowserMcpServer(options) {
+  const server = createBrowserMcpServer(options);
+  await server.connect(new StdioServerTransport());
+  logStderr("browser MCP server ready on stdio");
+  return server;
+}
+
+export {
+  stepResult,
+  doneResult,
+  isDoneResult,
+  resolveSecretsForUrl,
+  applicablePlaceholders,
+  sensitiveDataDescription,
+  maskOutbound,
+  maskSecretMap,
+  substituteSecrets,
+  totp,
+  defineAction,
+  Registry,
+  FileParseError,
+  readExternalFile,
+  BUILTIN_ACTIONS,
+  registerBuiltins,
+  createDefaultRegistry,
+  sanitizeFilename,
+  FileSystem,
+  buildAgentOutputSchema,
+  parseAction,
+  COMPACT_EVERY_N_STEPS,
+  COMPACT_TRIGGER_CHARS,
+  MessageManager,
+  resultsAreDone,
+  perceive,
+  budgetNudge,
+  LoopDetector,
+  AgentEventStream,
+  toTypedAction,
+  assembleNarration,
+  multiAct,
+  stepDurationSeconds,
+  AgentHistoryList,
+  createLogger,
+  silentLogger,
+  detectCaptcha,
+  CaptchaWatchdog,
+  anySignal,
+  StepLoop,
+  UsageLedger,
+  encodeFramesToGif,
+  generateRunGif,
+  JudgementResultSchema,
+  judgeRun,
+  generateRunVideoGif,
+  Agent,
+  logStderr,
+  createBrowserMcpServer,
+  runBrowserMcpServer
+};