agentlinkops 0.5.0 → 0.5.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Connect an agent to AgentLinkOps and run backlink work with it: the connect skill (views, the three discovery verbs, evidence rules), local ledger and campaign skills, a portable CRM, the source-cited content pipeline, user-managed disavow lists, HTML reports and monitoring-event sync.",
   "author": {
     "name": "AgentLinkOps"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Connect an agent to AgentLinkOps and run backlink work with it: the connect skill (views, the three discovery verbs, evidence rules), local ledger and campaign skills, a portable CRM, the source-cited content pipeline, user-managed disavow lists, HTML reports and monitoring-event sync.",
   "author": {
     "name": "AgentLinkOps"

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agentlinkops": {
+      "type": "http",
+      "url": "https://app.agentlinkops.com/mcp"
+    }
+  }
+}

package/CHANGELOG.md

@@ -3,7 +3,21 @@
 All notable changes to the `agentlinkops` package are recorded here. The version follows the
 plugin manifests in `.claude-plugin/` and `.codex-plugin/`.
 
-## 0.5.0 (unreleased; DP-0036 agent surface)
+## 0.5.1 (2026-09-17)
+
+- The plugin's `.mcp.json` ships in the tarball. 0.5.0 left it out, so a marketplace install
+  got the skills but no MCP server entry; the package build now carries and requires it.
+- Package identity: `author` is AgentLinkOps (https://agentlinkops.com); `repository` and
+  `bugs` point at `sunlover7/agentlinkops-cli`. No personal identity in the registry metadata.
+- `agentlinkops citation run PANEL.json --engine chatgpt:web-own-browser`: measures the
+  consumer UI through the customer's own Camoufox browser instead of an API, with a screenshot
+  of every answer in the evidence. `--engine NAME[:PROVIDER]` overrides the panel's engine list.
+  `playwright-core` is an optional dependency; `doctor` reports the browser stack as a skip,
+  never a failure, when it is absent (API and mock engines need none of it).
+- Repository: CI on every push and a tag-driven release workflow that publishes through npm
+  trusted publishing with provenance.
+
+## 0.5.0 (2026-09-16; DP-0036 agent surface)
 
 - `agentlinkops tools [TOOLSET]`, `agentlinkops describe NAME` and `agentlinkops call NAME`:
   the three discovery verbs, answered offline from the bundled catalog snapshot (`--refresh`

package/README.md

@@ -37,7 +37,8 @@ Four steps, the same ones the docs and the landing page show. Node.js 22.13 or l
 The skill is a short door: the first time your agent uses AgentLinkOps in a session it reads
 the full agent reference, which `agentlinkops skill` prints and
 https://agentlinkops.com/SKILL.md serves. Hosted monitoring is an invitation-only pilot; the
-local commands below need no account.
+local commands below need no account. The package is `agentlinkops` on npm, published by the
+`agentlinkops` account; the source is https://github.com/sunlover7/agentlinkops-cli.
 
 ## Install the CLI on its own
 

package/cli/citation.js

@@ -21,6 +21,10 @@ const USAGE = `agentlinkops citation — AI citation watches in this repository
   agentlinkops citation run PANEL.json [--dir DIR] [--samples N] [--max-usd USD] [--json]
                                             run one fixed-n epoch over a panel; evidence and
                                             tallies land under .agentlinkops/citations/
+  agentlinkops citation run PANEL.json --engine chatgpt:web-own-browser
+                                            measure the consumer UI through Camoufox
+                                            (dedicated account, personal cadence; evidence
+                                            includes a screenshot of every answer)
   agentlinkops citation help                 this help
 
 Panel (JSON): targets (domain or url, brand, aliases), prompts, engines
@@ -53,6 +57,15 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   const dir = resolve(cwd, args.dir ?? '.agentlinkops');
   if (args.samples) panel.samples = Number(args.samples);
   if (args['max-usd']) panel.maxUsd = Number(args['max-usd']);
+  // --engine NAME[:PROVIDER] overrides the panel's engine list. The provider
+  // suffix picks the surface: chatgpt:web-own-browser measures the consumer
+  // UI through Camoufox; chatgpt:api would measure the API. Never averaged.
+  if (args.engine) {
+    const [engineName, providerTag] = String(args.engine).split(':');
+    const via = providerTag === 'web-own-browser' ? 'browser' : 'api';
+    panel.engines = [{ engine: engineName, via }];
+    err(`engine override: ${engineIdentity(panel.engines[0])}`);
+  }
   // Overrides are stated, never silent: a number the panel did not ask for is a
   // configuration decision the operator should see in the receipt.
   if (args.samples || args['max-usd']) {
@@ -63,6 +76,11 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   for (const spec of panel.engines) {
     const identity = engineIdentity(spec);
     if (engines.has(identity)) continue;
+    if (spec.via === 'browser') {
+      const { createBrowserEngine } = await import('../src/citations/browser/engine.js');
+      engines.set(identity, createBrowserEngine({ engineName: spec.engine, env }));
+      continue;
+    }
     if (spec.engine === 'mock') {
       engines.set(identity, createMockEngine({ fixtures: panel.mockFixtures ?? {} }));
     } else if (spec.engine === 'perplexity') {
@@ -79,7 +97,7 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   }
 
   try {
-    const result = await runEpoch(panel, { dir, engines, delayMs: 250 });
+    const result = await runEpoch(panel, { dir, engines, delayMs: 250, err });
     if (args.json) {
       out(JSON.stringify(result, null, 2));
     } else {

package/cli/client.js

@@ -2,7 +2,7 @@ import {restResponseContract} from '../shared/response-contract.js';
 // A small HTTP client for the cloud. Scoped keys only; no human session ever reaches here.
 // DP-0036-T13: the CLI names itself so the usage counters can tell it from other REST callers.
 // The version follows the plugin manifests; bump it with them.
-export const CLI_VERSION = '0.5.0';
+export const CLI_VERSION = '0.5.1';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 export class CloudError extends Error {
   constructor(code, status, details = null) {

package/cli/doctor.js

@@ -261,6 +261,25 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
     checks.push({ status: 'skip', name: 'citations', detail: 'no engine credential set; mock citation runs work, live runs need PERPLEXITY_API_KEY' });
   }
 
+  // Browser engines: the Camoufox stack. Each missing piece names its fix; none
+  // of it fails doctor, because API and mock engines do not need it.
+  try {
+    await import('playwright-core');
+    const { execFile } = await import('node:child_process');
+    const camoufoxOk = await new Promise((resolve) => {
+      // `camoufox path` resolves the fetched browser and exits 0; the launcher
+      // has no --version flag and exits nonzero on it.
+      execFile('camoufox', ['path'], { timeout: 8000 }, (error) => resolve(!error));
+    });
+    if (camoufoxOk) {
+      checks.push({ status: 'ok', name: 'browser', detail: 'playwright-core + camoufox present; browser engines available' });
+    } else {
+      checks.push({ status: 'skip', name: 'browser', detail: 'playwright-core ok but camoufox missing', fix: 'python3 -m pip install cloverlabs-camoufox[geoip] && python3 -m camoufox fetch' });
+    }
+  } catch {
+    checks.push({ status: 'skip', name: 'browser', detail: 'browser engines unavailable: playwright-core not installed', fix: 'npm install playwright-core (API and mock engines are unaffected)' });
+  }
+
   out(`agentlinkops doctor — ${config.dir}`);
 
   // Record the probe outcomes beside the cursors they protect — BEFORE rendering, so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A backlink ledger that lives in your repository: local link checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",
@@ -21,6 +21,7 @@
     "templates",
     "references",
     "scripts",
+    ".mcp.json",
     ".claude-plugin",
     ".codex-plugin",
     "README.md",
@@ -54,6 +55,13 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "parse5": "8.0.1",
+    "turndown": "^7.2.4",
     "zod": "4.6.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "optionalDependencies": {
+    "playwright-core": "^1.63.0"
   }
 }

package/src/citations/browser/engine.js

@@ -0,0 +1,196 @@
+// The browser engine provider: one AI surface, measured through a real
+// Camoufox-driven Firefox at consumer URLs, as our citation adapter contract.
+//
+// Everything here follows the DP-0031 contract's posture rules: a fresh
+// browser context per sample (session history can never contaminate the
+// panel), the vendored oneglanse per-engine configs for wait/extract/citations
+// (MIT, attributed), our proxy from AGENTLINKOPS_PROXY_URL, and a screenshot
+// captured into evidence on every run so an observation is never just a claim.
+//
+// This module imports playwright-core lazily: a CLI install without the
+// browser tooling still runs every non-browser engine, and `citation doctor`
+// reports the gap instead of the whole CLI failing to load.
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { EngineError } from '../adapter.js';
+
+const lazy = async (path) => import(path);
+
+let playwrightFirefox = null;
+async function firefox() {
+  if (!playwrightFirefox) {
+    try {
+      playwrightFirefox = (await lazy('playwright-core')).firefox;
+    } catch (cause) {
+      throw new EngineError('playwright-core is not installed; browser engines need it (npm install playwright-core)', { cause });
+    }
+  }
+  return playwrightFirefox;
+}
+
+export const BROWSER_PROVIDERS = Object.freeze(['chatgpt', 'perplexity', 'gemini', 'claude', 'ai-overview']);
+
+// Nominal per-answer estimate: ~0.3 MB through a residential proxy at ~$7/GB,
+// plus slack for the page itself. Checked BEFORE the run by the budget cap.
+const NOMINAL_COST_USD = 0.004;
+
+function parseProxyUrl(raw) {
+  if (!raw) return null;
+  try {
+    const url = new URL(raw);
+    return {
+      server: `${url.protocol}//${url.hostname}:${url.port}`,
+      username: decodeURIComponent(url.username),
+      password: decodeURIComponent(url.password),
+    };
+  } catch {
+    throw new EngineError(`AGENTLINKOPS_PROXY_URL is not a valid proxy URL (length ${raw.length}, value never printed)`);
+  }
+}
+
+export function createBrowserEngine({ engineName, env = process.env, onEvent = () => {} } = {}) {
+  if (!BROWSER_PROVIDERS.includes(engineName)) {
+    throw new EngineError(`unknown browser engine: ${engineName} (known: ${BROWSER_PROVIDERS.join(', ')})`);
+  }
+  const identity = { engine: engineName, provider: 'web-own-browser', model: engineName };
+  const sessionDir = join(homedir(), '.agentlinkops', 'citations', 'sessions');
+
+  let browserHandle = null;   // { browser, cleanup } for the whole epoch
+  let displayHandle = null;
+  let providerConfig = null;
+
+  async function ensureProviderConfig() {
+    if (providerConfig) return providerConfig;
+    const { PROVIDER_CONFIGS } = await lazy('./gen/core/providers/index.js');
+    providerConfig = PROVIDER_CONFIGS[engineName];
+    if (!providerConfig) throw new EngineError(`no provider config for ${engineName}`);
+    return providerConfig;
+  }
+
+  async function ensureBrowser() {
+    if (browserHandle) return browserHandle;
+    const [{ resolveCamoufoxLaunchOptions }, display, { firefox: launchFirefox }] = [
+      await lazy('./gen/lib/browser/camoufox.js'),
+      await lazy('./gen/lib/browser/display.js'),
+      { firefox: await firefox() },
+    ];
+
+    // Linux without a display gets the vendored self-bootstrapped Xvfb — the
+    // engines that block headless render headfully inside a virtual display.
+    if (process.platform === 'linux' && !display.detectDisplay()) {
+      displayHandle = await display.ensureDisplay({ allowExistingDisplay: false });
+      onEvent(`display: ${displayHandle.display}`);
+    }
+
+    const proxy = parseProxyUrl(env.AGENTLINKOPS_PROXY_URL);
+    if (proxy) onEvent(`proxy: ${proxy.server}`);
+
+    const options = await resolveCamoufoxLaunchOptions({
+      provider: engineName,
+      proxy: proxy ?? undefined,
+      // "virtual" on Linux = headful Firefox inside Xvfb; true headless is the
+      // detection magnet the research warned about.
+      headlessMode: process.platform === 'linux' ? 'virtual' : 'headful',
+    });
+    const browser = await launchFirefox({ ...options, executablePath: options.executablePath, proxy });
+
+    browserHandle = {
+      browser,
+      cleanup: async () => {
+        await browser.close().catch(() => null);
+        await displayHandle?.cleanup?.().catch(() => null);
+        displayHandle = null;
+      },
+    };
+    return browserHandle;
+  }
+
+  async function loadStorageState() {
+    try {
+      const { readFile } = await lazy('node:fs/promises');
+      return JSON.parse(await readFile(join(sessionDir, `${engineName}.json`), 'utf8'));
+    } catch {
+      return undefined; // anonymous session: several surfaces work logged-out
+    }
+  }
+
+  return {
+    identity,
+    estimateCostUsd: () => NOMINAL_COST_USD,
+
+    async run({ prompt }) {
+      const config = await ensureProviderConfig();
+      const { browser, cleanup } = await ensureBrowser();
+      const context = await browser.newContext({
+        storageState: await loadStorageState(),
+        locale: 'en-US',
+        timezoneId: 'America/New_York',
+      });
+      try {
+        const page = await context.newPage();
+        page.setDefaultTimeout(45_000);
+
+        if (config.navigateToPrompt) {
+          await config.navigateToPrompt(page, prompt);
+        } else {
+          await page.goto(config.url, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+          await config.postNavigationHook?.(page);
+          await config.beforePromptHook?.(page);
+
+          const { findActiveEditorCandidate } = await lazy('./gen/lib/input/editor/findEditor.js');
+          const { PROVIDER_EDITOR_SELECTORS } = await lazy('./shims/utils.js');
+          const editor = await findActiveEditorCandidate(page, PROVIDER_EDITOR_SELECTORS[engineName]);
+          if (!editor) throw new EngineError(`${engineName}: no prompt editor found (surface may be gated or changed)`);
+
+          const { insertPromptIntoEditor } = await lazy('./gen/lib/input/editor/promptInput.js');
+          await insertPromptIntoEditor(page, editor.locator, prompt, engineName);
+          await config.afterTypingHook?.(page);
+          await config.beforeSubmitHook?.(page);
+
+          const { findEnabledSendButton } = await lazy('./gen/lib/input/editor/findSendButton.js');
+          const { PROVIDER_SUBMIT_BTN_SELECTORS } = await lazy('./shims/utils.js');
+          const send = await findEnabledSendButton(page, PROVIDER_SUBMIT_BTN_SELECTORS[engineName]);
+          if (send) { await send.click(); }
+          else { await editor.locator.press('Enter'); }
+        }
+        await config.afterSubmitHook?.(page);
+
+        await config.waitForResponse(page);
+        const answer = await config.extractResponse(page);
+        if (!answer || answer.trim().length === 0) {
+          throw new EngineError(`${engineName}: answer extracted empty`, { retriable: true });
+        }
+        const sources = await config.extractSources(page);
+        const screenshotPng = await page.screenshot({ fullPage: false }).catch(() => null);
+
+        return {
+          engine: engineName,
+          provider: 'web-own-browser',
+          model: engineName,
+          providerModelVersion: `${engineName}-web`,
+          answer,
+          citations: (sources ?? []).map((s) => ({ url: s.url, title: s.title ?? s.cited_text ?? null })).filter((c) => typeof c.url === 'string' && c.url.length > 0),
+          fanOut: [],
+          usage: { input_tokens: 0, output_tokens: 0 },
+          costEstimateUsd: NOMINAL_COST_USD,
+          screenshotPng,
+        };
+      } catch (cause) {
+        if (cause instanceof EngineError) throw cause;
+        const msg = String(cause?.message ?? cause);
+        const retriable = /timeout|timed out|ERR_|net::|closed|Target closed/i.test(msg);
+        throw new EngineError(`${engineName}: browser run failed: ${msg}`, { retriable, cause });
+      } finally {
+        await context.close().catch(() => null);
+      }
+    },
+
+    // Called by the runner at epoch end.
+    async close() {
+      await browserHandle?.cleanup?.();
+      browserHandle = null;
+    },
+  };
+}

package/src/citations/browser/gen/core/providers/_shared/google.js

@@ -0,0 +1,4 @@
+const GOOGLE_CONSENT_SELECTOR = "button#L2AGLb, button#W0wltc, form[action*='consent.google.com'] button";
+export {
+  GOOGLE_CONSENT_SELECTOR
+};

package/src/citations/browser/gen/core/providers/_shared/rawSourcesDom.js

@@ -0,0 +1,15 @@
+import { AI_OVERVIEW_RAW_SOURCES_DOM_EXTRACTOR } from "../ai-overview/lib/extractSources.js";
+import { CHATGPT_RAW_SOURCES_DOM_EXTRACTOR } from "../chatgpt/lib/extractSources.js";
+import { CLAUDE_RAW_SOURCES_DOM_EXTRACTOR } from "../claude/lib/extractSources.js";
+import { GEMINI_RAW_SOURCES_DOM_EXTRACTOR } from "../gemini/lib/extractSources.js";
+import { PERPLEXITY_RAW_SOURCES_DOM_EXTRACTOR } from "../perplexity/lib/extractSources.js";
+const PROVIDER_RAW_SOURCES_DOM_EXTRACTORS = {
+  chatgpt: CHATGPT_RAW_SOURCES_DOM_EXTRACTOR,
+  perplexity: PERPLEXITY_RAW_SOURCES_DOM_EXTRACTOR,
+  gemini: GEMINI_RAW_SOURCES_DOM_EXTRACTOR,
+  claude: CLAUDE_RAW_SOURCES_DOM_EXTRACTOR,
+  "ai-overview": AI_OVERVIEW_RAW_SOURCES_DOM_EXTRACTOR
+};
+export {
+  PROVIDER_RAW_SOURCES_DOM_EXTRACTORS
+};

package/src/citations/browser/gen/core/providers/_shared/resetProviderPage.js

@@ -0,0 +1,22 @@
+import { logger } from "../../../../shims/utils.js";
+import { preInteractionIdle, randomBetween } from "../../../lib/browser/humanBehavior.js";
+import { navigateWithRetry } from "../../../lib/browser/navigate.js";
+import { detectBotPage } from "../../../lib/input/response/detectBotPage.js";
+async function resetProviderPage(page, provider, url, options = {}) {
+  logger.log(`[${provider}] resetting page for next prompt`);
+  await preInteractionIdle(page).catch(() => {
+  });
+  await page.waitForTimeout(randomBetween(600, 1400));
+  await navigateWithRetry(page, url, {
+    waitUntil: "domcontentloaded",
+    timeout: 3e4
+  });
+  logger.log(`[${provider}] redirected back to provider page: ${page.url()}`);
+  await detectBotPage(page, provider);
+  await options.postNavigationHook?.(page);
+  await page.waitForTimeout(randomBetween(1200, 2600));
+  logger.log(`[${provider}] page reset ready: ${page.url()}`);
+}
+export {
+  resetProviderPage
+};

package/src/citations/browser/gen/core/providers/_shared/sourceUtils.js

@@ -0,0 +1,8 @@
+import {
+  buildSources,
+  clickButtonViaDispatch
+} from "../../../lib/extraction/sourceUtils.js";
+export {
+  buildSources,
+  clickButtonViaDispatch
+};

package/src/citations/browser/gen/core/providers/ai-overview/index.js

@@ -0,0 +1,70 @@
+import { PROVIDER_EDITOR_SELECTORS } from "../../../../shims/utils.js";
+import { logger } from "../../../../shims/utils.js";
+import { navigateWithRetry } from "../../../lib/browser/navigate.js";
+import {
+  findActiveEditorCandidateFromSelectors
+} from "../../../lib/input/editor/findEditor.js";
+import { extractAssistantMarkdown } from "../../../lib/input/markdown/toMarkdown.js";
+import { insertPromptIntoEditor } from "../../../lib/input/editor/promptInput.js";
+import { waitForAssistantToFinish } from "../../../lib/input/response/waitForFinish.js";
+import { extractAIOverviewSources } from "./lib/extractSources.js";
+import { expandAIOverviewSources } from "./lib/expand.js";
+import {
+  AI_OVERVIEW_URL,
+  resetAIOverviewPage
+} from "./lib/pageLifecycle.js";
+import {
+  assertAIOverviewPageNotBlocked,
+  dismissGoogleConsentDialog,
+  ensureAIOverviewGoogleSession,
+  waitForAIOverviewSearchResults
+} from "./lib/session.js";
+const aiOverviewConfig = {
+  url: AI_OVERVIEW_URL,
+  label: "AI Overview",
+  displayName: "AI Overview",
+  skipInitialNavigation: true,
+  navigateToPrompt: async (page, prompt) => {
+    await ensureAIOverviewGoogleSession(page);
+    await navigateWithRetry(page, AI_OVERVIEW_URL, {
+      waitUntil: "domcontentloaded",
+      timeout: 3e4
+    });
+    assertAIOverviewPageNotBlocked(page);
+    await dismissGoogleConsentDialog(page);
+    const searchInput = await findActiveEditorCandidateFromSelectors(page, [
+      ...PROVIDER_EDITOR_SELECTORS["ai-overview"]
+    ]);
+    logger.debug(`[ai-overview] using search selector: ${searchInput.selector}`);
+    logger.debug(`[ai-overview] pasting ${prompt.length} chars\u2026`);
+    await insertPromptIntoEditor(
+      page,
+      searchInput.locator,
+      prompt,
+      "ai-overview"
+    );
+    logger.debug(`[ai-overview] pasting ${prompt.length} chars complete`);
+    await page.waitForTimeout(400);
+    logger.debug("[ai-overview] attempting submission\u2026");
+    await page.keyboard.press("Enter");
+    await page.waitForLoadState("domcontentloaded", { timeout: 5e3 }).catch(
+      () => {
+      }
+    );
+    await waitForAIOverviewSearchResults(page);
+    await dismissGoogleConsentDialog(page);
+    assertAIOverviewPageNotBlocked(page);
+    logger.log(`[ai-overview] search ready: ${page.url()}`);
+  },
+  waitForResponse: (page) => waitForAssistantToFinish(page, "ai-overview"),
+  extractResponse: (page) => extractAssistantMarkdown(page, "ai-overview"),
+  beforeRetryHook: resetAIOverviewPage,
+  betweenPromptsHook: resetAIOverviewPage,
+  extractSources: async (page) => {
+    await expandAIOverviewSources(page);
+    return extractAIOverviewSources(page);
+  }
+};
+export {
+  aiOverviewConfig
+};

package/src/citations/browser/gen/core/providers/ai-overview/lib/expand.js

@@ -0,0 +1,59 @@
+import { logger } from "../../../../../shims/utils.js";
+const AI_OVERVIEW_SOURCE_ROOT_SELECTOR = '[data-container-id="rhs-col"]';
+const AI_OVERVIEW_BUTTON_SELECTOR = '[role="button"], button';
+function shouldClickSourceExpansionButton(text, aria) {
+  const t = `${text} ${aria}`.toLowerCase();
+  if (t.includes("videos")) return false;
+  if (t.includes("more")) return true;
+  if (t.includes("all")) return true;
+  if (t.includes("expand")) return true;
+  return false;
+}
+async function expandAIOverviewSources(page) {
+  const matches = await page.evaluate(
+    ({
+      rootSelector,
+      buttonSelector
+    }) => {
+      const root = document.querySelector(rootSelector);
+      if (!(root instanceof HTMLElement)) return [];
+      return Array.from(root.querySelectorAll(buttonSelector)).map((button, index) => {
+        if (!(button instanceof HTMLElement)) {
+          return null;
+        }
+        const style = window.getComputedStyle(button);
+        const rect = button.getBoundingClientRect();
+        const visible = button.isConnected && style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0" && rect.width > 0 && rect.height > 0;
+        if (!visible) return null;
+        return {
+          index,
+          text: (button.textContent || "").trim(),
+          aria: button.getAttribute("aria-label")?.trim() || ""
+        };
+      }).filter(
+        (match) => match !== null
+      );
+    },
+    {
+      rootSelector: AI_OVERVIEW_SOURCE_ROOT_SELECTOR,
+      buttonSelector: AI_OVERVIEW_BUTTON_SELECTOR
+    }
+  );
+  for (const match of matches) {
+    if (!shouldClickSourceExpansionButton(match.text, match.aria)) {
+      continue;
+    }
+    const button = page.locator(`${AI_OVERVIEW_SOURCE_ROOT_SELECTOR} ${AI_OVERVIEW_BUTTON_SELECTOR}`).nth(match.index);
+    const visible = await button.isVisible().catch(() => false);
+    if (!visible) continue;
+    logger.debug(
+      `[ai-overview] expanding sources text="${match.text}" aria="${match.aria}"`
+    );
+    await button.click({ timeout: 5e3 }).catch(() => {
+    });
+    await page.waitForTimeout(700);
+  }
+}
+export {
+  expandAIOverviewSources
+};

package/src/citations/browser/gen/core/providers/ai-overview/lib/extractSources.js

@@ -0,0 +1,60 @@
+import { toErrorMessage } from "../../../../../shims/errors.js";
+import { logger } from "../../../../../shims/utils.js";
+import { buildSources } from "../../_shared/sourceUtils.js";
+const AI_OVERVIEW_RAW_SOURCES_DOM_EXTRACTOR = String.raw`(_helpers) => {
+	const results = [];
+	const rhsCol = document.querySelector('[data-container-id="rhs-col"]');
+	if (!rhsCol) {
+		return { rawSources: results, containerFound: false };
+	}
+
+	for (const card of Array.from(rhsCol.querySelectorAll("div[data-src-id]"))) {
+		if (!(card instanceof HTMLElement)) continue;
+
+		const link = card.querySelector('a[href^="http"]');
+		if (!(link instanceof HTMLAnchorElement)) continue;
+
+		const title =
+			link
+				.getAttribute("aria-label")
+				?.replace(/\.\s*Opens in new tab\.?$/i, "")
+				.trim() || link.href;
+		const citedText =
+			card.querySelector("[data-crb-snippet-text]")?.textContent?.trim() || "";
+
+		results.push({
+			rawHref: link.href,
+			title,
+			citedText,
+		});
+	}
+
+	return { rawSources: results, containerFound: true };
+}`;
+function normalizeAIOverviewTitle(title) {
+  return title.replace(/\s*\.?\s*opens in new tab\.?\s*$/i, "").trim();
+}
+async function extractAIOverviewSources(page) {
+  try {
+    const { rawSources, containerFound } = await page.runDomOp("raw-sources", {
+      provider: "ai-overview"
+    });
+    if (!containerFound) {
+      logger.warn("AI Overview container not found \u2014 no sources extracted");
+    }
+    const normalizedSources = rawSources.map((source) => ({
+      ...source,
+      title: normalizeAIOverviewTitle(source.title ?? "") || source.rawHref
+    }));
+    return buildSources(normalizedSources, { provider: "ai-overview" });
+  } catch (err) {
+    logger.error(
+      `Failed to extract AI Overview sources: ${toErrorMessage(err)}`
+    );
+    return [];
+  }
+}
+export {
+  AI_OVERVIEW_RAW_SOURCES_DOM_EXTRACTOR,
+  extractAIOverviewSources
+};

package/src/citations/browser/gen/core/providers/ai-overview/lib/pageLifecycle.js

@@ -0,0 +1,18 @@
+import { resetProviderPage } from "../../_shared/resetProviderPage.js";
+import {
+  assertAIOverviewPageNotBlocked,
+  dismissGoogleConsentDialog
+} from "./session.js";
+const AI_OVERVIEW_URL = "https://www.google.com/";
+async function resetAIOverviewPage(page) {
+  await resetProviderPage(page, "ai-overview", AI_OVERVIEW_URL, {
+    postNavigationHook: async (currentPage) => {
+      assertAIOverviewPageNotBlocked(currentPage);
+      await dismissGoogleConsentDialog(currentPage);
+    }
+  });
+}
+export {
+  AI_OVERVIEW_URL,
+  resetAIOverviewPage
+};