agentlinkops 0.5.0 → 0.6.0

package/src/citations/adapter.js

@@ -139,3 +139,176 @@ export function createEngine(spec, options = {}) {
   if (spec.engine === 'perplexity') return createPerplexityEngine({ model: spec.model ?? 'sonar', ...(options.perplexity ?? {}) });
   throw new EngineError(`unknown engine: ${spec.engine}`);
 }
+
+// duck.ai anonymous engine: DuckDuckGo's AI chat serves Claude Haiku 4.5
+// without an account. The VQD handshake follows Duck2api (MIT): the status
+// call returns a token; when it returns a JS hash challenge instead, the
+// documented fallback payload is accepted. Pure HTTP through the proxy —
+// cheaper than a browser, and the surface has no bot wall at personal cadence.
+const DUCK_BASE = 'https://duck.ai';
+const DUCK_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36';
+const DUCK_ORIGIN = 'https://duck.ai';
+const DUCK_STACK = 'Error\n    at l (https://duck.ai/dist/duckai-dist/entry.duckai.c0a8c794abcbc8ee2d3c.js:2:1446307)\n    at async https://duck.ai/dist/duckai-dist/entry.duckai.c0a8c794abcbc8ee2d3c.js:2:1294181';
+
+async function duckDispatcher(proxyUrl) {
+  if (!proxyUrl) return undefined;
+  const { ProxyAgent } = await import('undici');
+  return new ProxyAgent(proxyUrl);
+}
+
+export function createDuckAiEngine({ model = 'claude-haiku-4-5', proxyUrl } = {}) {
+  let dispatcher = null;
+  const getDispatcher = async () => dispatcher ?? (dispatcher = await duckDispatcher(proxyUrl));
+
+  const duckFetch = async (path, init = {}) => {
+    const d = await getDispatcher();
+    return fetch(`${DUCK_BASE}${path}`, {
+      ...init,
+      headers: { 'user-agent': DUCK_UA, origin: DUCK_ORIGIN, referer: `${DUCK_BASE}/`, ...init.headers },
+      ...(d ? { dispatcher: d } : {}),
+    });
+  };
+
+  const vqdFallback = (challengeB64) => {
+    const decoded = Buffer.from(challengeB64, 'base64').toString('utf8');
+    const payload = `${decoded}::no-exec::${DUCK_STACK}::${DUCK_ORIGIN}`;
+    return Buffer.from(payload).toString('base64');
+  };
+
+  return {
+    identity: { engine: 'duckai', provider: 'anon-api', model },
+    estimateCostUsd: () => 0.0002,
+    async run({ prompt }) {
+      const status = await duckFetch('/duckchat/v1/status', { headers: { accept: '*/*' } });
+      if (!status.ok) throw new EngineError(`duckai status HTTP ${status.status}`, { retriable: true });
+      let vqd = status.headers.get('x-vqd-4') ?? status.headers.get('x-vqd');
+      const hashChallenge = status.headers.get('x-vqd-hash-1');
+      const headers = { accept: 'text/event-stream', 'content-type': 'application/json' };
+      if (!vqd && hashChallenge) {
+        vqd = vqdFallback(hashChallenge);
+        headers['x-vqd-hash-1'] = vqd;
+      }
+      if (!vqd) throw new EngineError('duckai: no vqd token or challenge in status response', { retriable: true });
+      headers['x-vqd-4'] = vqd;
+      if (vqd !== headers['x-vqd-hash-1']) headers['x-vqd'] = vqd;
+
+      const chat = await duckFetch('/duckchat/v1/chat', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }], stream: true }),
+      });
+      if (!chat.ok) throw new EngineError(`duckai chat HTTP ${chat.status}`, { retriable: true });
+      const body = await chat.text();
+      let message = '';
+      for (const line of body.split('\n')) {
+        const t = line.trim();
+        if (!t.startsWith('data:') || t.includes('[DONE]')) continue;
+        try { message += (JSON.parse(t.slice(5).trim()).message ?? ''); } catch { /* chunk */ }
+      }
+      if (message.trim().length < 20) throw new EngineError('duckai: empty chat message', { retriable: true });
+      return {
+        engine: 'duckai', provider: 'anon-api', model,
+        providerModelVersion: `duck:${model}`,
+        answer: message, citations: [], fanOut: [],
+        usage: { input_tokens: 0, output_tokens: 0 },
+        costEstimateUsd: 0.0002,
+      };
+    },
+  };
+}
+
+// OpenAI-compatible engine: any endpoint speaking /v1/chat/completions —
+// including self-hosted Duck2api on the VPS, which serves the whole Claude
+// family (haiku/sonnet/opus) plus GPT-5.6 anonymously through duck.ai.
+// The engine identity names the model explicitly; never averaged with others.
+export function createOpenAiCompatibleEngine({ baseUrl, model, apiKey, fetchImpl, costEstimateUsd = 0.0002, providerLabel = 'openai-compatible' } = {}) {
+  if (!baseUrl || !model) throw new EngineError('openai-compatible engine needs baseUrl and model');
+  const doFetch = fetchImpl ?? globalThis.fetch?.bind(globalThis);
+  return {
+    identity: { engine: model.split(':')[0] ?? model, provider: providerLabel, model },
+    estimateCostUsd: () => costEstimateUsd,
+    async run({ prompt }) {
+      const headers = { 'content-type': 'application/json' };
+      if (apiKey) headers.authorization = `Bearer ${apiKey}`;
+      const response = await doFetch(`${baseUrl}/chat/completions`, {
+        method: 'POST', headers,
+        body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+        signal: AbortSignal.timeout(CITATION_LIMITS.timeoutMs * 2),
+      }).catch((cause) => { throw new EngineError(`openai-compatible request failed: ${cause.message}`, { retriable: true, cause }); });
+      if (!response.ok) throw new EngineError(`openai-compatible responded ${response.status}`, { retriable: response.status >= 500 || [429, 418, 408, 425].includes(response.status) });
+      const body = await response.json().catch(() => { throw new EngineError('openai-compatible response was not JSON'); });
+      const answer = body?.choices?.[0]?.message?.content ?? '';
+      if (answer.trim().length < 20) throw new EngineError('openai-compatible returned an empty answer', { retriable: true });
+      return {
+        engine: model.split(':')[0] ?? model, provider: providerLabel, model,
+        providerModelVersion: `${providerLabel}:${model}`,
+        answer, citations: [], fanOut: [],
+        usage: { input_tokens: body?.usage?.prompt_tokens ?? 0, output_tokens: body?.usage?.completion_tokens ?? 0 },
+        costEstimateUsd,
+      };
+    },
+  };
+}
+
+// Google AI Overview engine via DataForSEO SERP API (fixture-first, DP-0044).
+// AIO is a SERP feature, not a chat: the engine sends a search query and reads
+// the ai_overview block from the returned items. Cited sources are domains the
+// overview linked to — the citation equivalent of a chat engine's source list.
+// The fixture below proves the parser against the documented response shape;
+// the live adapter activates with credentials in fleet, never before.
+export function createGoogleAioEngine({ fetchImpl, credentials, costEstimateUsd = 0.0012 } = {}) {
+  const doFetch = fetchImpl ?? globalThis.fetch?.bind(globalThis);
+  const hasCredentials = Boolean(credentials?.login && credentials?.password);
+
+  return {
+    identity: { engine: 'google-aio', provider: hasCredentials ? 'dataforseo-serp' : 'fixture', model: 'ai-overview' },
+    estimateCostUsd: () => costEstimateUsd,
+
+    async run({ prompt }) {
+      if (!hasCredentials) {
+        // Fixture mode: prove the parser against the recorded response.
+        const fixture = await import('./fixtures/dataforseo-aio.json', { with: { type: 'json' } });
+        return parseAioResponse(fixture.default, prompt);
+      }
+      // Live mode: DataForSEO live/advanced POST.
+      const auth = Buffer.from(`${credentials.login}:${credentials.password}`).toString('base64');
+      const response = await doFetch('https://api.dataforseo.com/v3/serp/google/organic/live/advanced', {
+        method: 'POST',
+        headers: { 'authorization': `Basic ${auth}`, 'content-type': 'application/json' },
+        body: JSON.stringify([{ keyword: prompt, location_code: 2840, language_code: 'en' }]),
+        signal: AbortSignal.timeout(120_000),
+      }).catch((cause) => { throw new EngineError(`dataforseo request failed: ${cause.message}`, { retriable: true, cause }); });
+      if (!response.ok) throw new EngineError(`dataforseo responded ${response.status}`, { retriable: response.status >= 500 });
+      const body = await response.json().catch(() => { throw new EngineError('dataforseo response was not JSON'); });
+      return parseAioResponse(body, prompt);
+    },
+  };
+}
+
+function parseAioResponse(body, prompt) {
+  const result = body?.tasks?.[0]?.result?.[0];
+  if (!result) throw new EngineError('google-aio: no result in response', { retriable: true });
+  const aioBlock = (result.items ?? []).find((item) => item.type === 'ai_overview');
+  if (!aioBlock) {
+    // An honest absence: the SERP rendered without an AI Overview block.
+    throw new EngineError('google-aio: no AI Overview block rendered for this query', { retriable: true });
+  }
+  const answer = aioBlock.text ?? '';
+  if (answer.trim().length < 40) {
+    throw new EngineError('google-aio: AI Overview text too short to interpret', { retriable: true });
+  }
+  const citations = (aioBlock.items ?? [])
+    .filter((src) => typeof src.url === 'string' && src.url.length > 0)
+    .map((src) => ({ url: src.url, title: src.title ?? null }));
+  return {
+    engine: 'google-aio',
+    provider: 'dataforseo-serp',
+    model: 'ai-overview',
+    providerModelVersion: 'google-aio-serp-v1',
+    answer,
+    citations,
+    fanOut: [],
+    usage: { input_tokens: 0, output_tokens: 0 },
+    costEstimateUsd: body?.cost ?? 0.0012,
+  };
+}

package/src/citations/alert.js

@@ -0,0 +1,53 @@
+// Citation alert: deliver the report when a cell classifies as declined.
+// Uses the same SMTP pattern as the send-email skill (zero-dependency Python
+// script). The alert only fires on complete evidence — insufficient_data
+// and first_epoch never trigger, exactly as the contract requires.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+
+export function shouldAlert(cells) {
+  return cells.some((c) => c.classification === 'declined');
+}
+
+export async function sendAlertEmail({ to, subject, htmlPath, smtp = {} }) {
+  if (!to || !htmlPath) throw new Error('sendAlertEmail needs to and htmlPath');
+  const { host, port, user, pass, from } = smtp;
+  if (!host || !user || !pass) {
+    // No SMTP configured — log the alert locally; the report file IS the alert.
+    return { delivered: false, reason: 'no smtp configured', htmlPath };
+  }
+  const html = await readFile(htmlPath, 'utf8');
+  // Strip the outer HTML tags for the plain-text body (the HTML stays as an
+  // attachment in a real deployment; for v1 the file path is the artifact).
+  const textBody = html
+    .replace(/<style[^>]*>.*?<\/style>/gs, '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 2000);
+
+  const python = `
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+msg = MIMEMultipart('alternative')
+msg['Subject'] = ${JSON.stringify(subject)}
+msg['From'] = ${JSON.stringify(from ?? user)}
+msg['To'] = ${JSON.stringify(to)}
+msg.attach(MIMEText(${JSON.stringify(textBody)}, 'plain'))
+with open(${JSON.stringify(htmlPath)}, 'r') as f:
+    msg.attach(MIMEText(f.read(), 'html'))
+with smtplib.SMTP(${JSON.stringify(host)}, ${parseInt(port ?? 587, 10)}) as s:
+    s.starttls()
+    s.login(${JSON.stringify(user)}, ${JSON.stringify(pass)})
+    s.send_message(msg)
+print('sent')
+`;
+  return new Promise((resolve, reject) => {
+    execFile('python3', ['-c', python], (err, stdout) => {
+      if (err) reject(new Error(`smtp send failed: ${err.message}`));
+      else resolve({ delivered: true, htmlPath });
+    });
+  });
+}

package/src/citations/browser/engine.js

@@ -0,0 +1,267 @@
+// 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', 'grok', 'copilot', 'bing', 'duckai']);
+
+// 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.03;
+
+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');
+    const { OWN_PROVIDER_CONFIGS } = await lazy('./providers.js');
+    providerConfig = OWN_PROVIDER_CONFIGS[engineName] ?? 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, fw] = [
+      await lazy('./gen/lib/browser/camoufox.js'),
+      await lazy('./gen/lib/browser/display.js'),
+      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,
+      // The virtual display handle must travel into the launch payload: the
+      // resolver exports DISPLAY for the browser process it configures.
+      display: displayHandle?.display,
+      // "virtual" on Linux = headful Firefox inside Xvfb; true headless is the
+      // detection magnet the research warned about.
+      headlessMode: process.platform === 'linux' ? 'virtual' : 'headful',
+    });
+    const launchOpts = { ...options, executablePath: options.executablePath };
+    if (proxy) launchOpts.proxy = proxy;
+    const browser = await fw.launch(launchOpts);
+
+    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',
+      });
+      // Route-level asset stripping (opt out with AGENTLINKOPS_BROWSER_KEEP_ASSETS=1):
+      // images and media are the bulk of the 3-8 MB measured per observation.
+      // Fonts stay — font metrics are part of the fingerprint surface.
+      if (env.AGENTLINKOPS_BROWSER_KEEP_ASSETS !== '1') {
+        await context.route('**/*', (route) => {
+          const type = route.request().resourceType();
+          if (type === 'image' || type === 'media') return route.abort();
+          return route.continue();
+        });
+      }
+      try {
+        const page = await context.newPage();
+        page.setDefaultTimeout(45_000);
+
+        if (config.navigateToPrompt) {
+          await config.navigateToPrompt(page, prompt);
+        } else if (engineName === 'grok') {
+          // Probe-proven grok flow: the composer's position moves with each
+          // randomized fingerprint, so its live rect is located in-page and
+          // clicked at the computed center — never a fixed coordinate.
+          await page.goto('https://grok.com/', { waitUntil: 'domcontentloaded', timeout: 60_000 });
+          await page.waitForTimeout(12_000);
+          let spot = null;
+          for (let attempt = 0; attempt < 3 && !spot; attempt += 1) {
+            spot = await page.evaluate(() => {
+              const els = [...document.querySelectorAll('textarea, [contenteditable="true"], [role="textbox"]')];
+              for (const el of els) {
+                const r = el.getBoundingClientRect();
+                if (r.width > 60 && r.height > 10) return { x: Math.round(r.x + r.width / 2), y: Math.round(r.y + Math.min(Math.max(r.height / 2, 12), 40)) };
+              }
+              return null;
+            });
+            if (!spot) await page.waitForTimeout(7000);
+          }
+          if (!spot) throw new EngineError('grok: no composer found after settle retries (surface may be gated or changed)', { retriable: true });
+          await page.mouse.click(spot.x, spot.y);
+          await page.waitForTimeout(1000);
+          await page.keyboard.type(prompt, { delay: 90 });
+          await page.waitForTimeout(1200);
+          await page.keyboard.press('Enter');
+        } else if (engineName === 'duckai') {
+          // The page's own JS solves the VQD challenge; the chat call runs
+          // in-page with native cookies and headers. Claude Haiku, anonymous.
+          await page.waitForTimeout(6000);
+          const { duckChat } = await lazy('./providers.js');
+          const chat = await duckChat(page, prompt);
+          if (!chat.message || chat.message.trim().length < 40) {
+            throw new EngineError(`duckai: empty chat response (models seen: ${(chat.models ?? []).slice(0, 5).join(',')})`, { retriable: true });
+          }
+          answer = chat.message;
+        } else if (engineName === 'bing') {
+          // Pure navigation: the prompt IS the URL. No editor, no typing, no
+          // modal — the generative answer block renders with its citations.
+          await page.goto(`https://www.bing.com/search?q=${encodeURIComponent(prompt)}`, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+          await config.waitForResponse(page);
+        } 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);
+        let answer = '';
+        if (!answer) answer = await config.extractResponse(page);
+        // Anonymous/mobile layouts render the conversation without the
+        // logged-in app's message attributes. The honest fallback is the
+        // page's own text: it is the answer surface the user saw, and the
+        // screenshot beside it shows exactly what was read.
+        if ((!answer || answer.trim().length === 0) && engineName !== 'bing') {
+          answer = await page.evaluate(() => (document.body.innerText || '').trim());
+        }
+        if (!answer || answer.trim().length < 40) {
+          const reason = engineName === 'bing'
+            ? 'bing: no AI answer block rendered for this prompt (organic results only — never a citation verdict)'
+            : `${engineName}: answer extracted empty`;
+          throw new EngineError(reason, { retriable: true });        }
+        // A sources-panel failure must never discard a completed answer: the
+        // answer was measured, the screenshot was taken — citations can be
+        // empty while the observation still counts, honestly, as rendered.
+        const sources = await config.extractSources(page).catch((cause) => {
+          onEvent(`sources extraction failed (answer kept, citations empty): ${String(cause?.message ?? cause).slice(0, 120)}`);
+          return [];
+        });
+        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
+};