agentlinkops 0.5.1 → 0.6.0

package/src/citations/browser/engine.js

@@ -30,11 +30,11 @@ async function firefox() {
   return playwrightFirefox;
 }
 
-export const BROWSER_PROVIDERS = Object.freeze(['chatgpt', 'perplexity', 'gemini', 'claude', 'ai-overview']);
+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.004;
+const NOMINAL_COST_USD = 0.03;
 
 function parseProxyUrl(raw) {
   if (!raw) return null;
@@ -64,17 +64,18 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
   async function ensureProviderConfig() {
     if (providerConfig) return providerConfig;
     const { PROVIDER_CONFIGS } = await lazy('./gen/core/providers/index.js');
-    providerConfig = PROVIDER_CONFIGS[engineName];
+    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, { firefox: launchFirefox }] = [
+    const [{ resolveCamoufoxLaunchOptions }, display, fw] = [
       await lazy('./gen/lib/browser/camoufox.js'),
       await lazy('./gen/lib/browser/display.js'),
-      { firefox: await firefox() },
+      await firefox(),
     ];
 
     // Linux without a display gets the vendored self-bootstrapped Xvfb — the
@@ -90,11 +91,16 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     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 browser = await launchFirefox({ ...options, executablePath: options.executablePath, proxy });
+    const launchOpts = { ...options, executablePath: options.executablePath };
+    if (proxy) launchOpts.proxy = proxy;
+    const browser = await fw.launch(launchOpts);
 
     browserHandle = {
       browser,
@@ -128,12 +134,61 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
         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);
@@ -158,11 +213,27 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
         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 });
+        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());
         }
-        const sources = await config.extractSources(page);
+        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 {

package/src/citations/browser/providers.js

@@ -0,0 +1,166 @@
+// AgentLinkOps-owned browser provider configs: surfaces the vendored oneglanse
+// layer never shipped, written against the same ProviderConfig shape so the
+// engine treats them identically. Each config is probe-proven on the real
+// surface through Camoufox + US residential (receipts: 2026-09-17/18).
+//
+// GROK (grok.com): Cloudflare passes from residential exits; anonymous use
+// grants one full answer per fresh context, then a signup nudge — which the
+// fresh-context-per-sample rule already assumes.
+//
+// COPILOT (copilot.microsoft.com): anonymous composer behind a sign-in modal
+// whose Close control resisted automated dismissal; EXPERIMENTAL until the
+// session-login command (T04) lands.
+//
+// BING (bing.com/search): the generative answer block renders WITH cited
+// outbound links, anonymously, no challenge. Pure URL navigation — the prompt
+// is the URL. The block is found by content signature, never position.
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Generic answer wait: poll the body until its text stabilizes (the vendored
+// signature-based waiter needs provider constants these surfaces lack).
+async function waitForStableBody(page, { stableMs = 2500, timeoutMs = 90000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let last = -1;
+  let stableSince = null;
+  while (Date.now() < deadline) {
+    const text = await page.evaluate(() => (document.body.innerText || '').length).catch(() => 0);
+    if (text === last && text > 300) {
+      if (stableSince && Date.now() - stableSince >= stableMs) return true;
+      if (!stableSince) stableSince = Date.now();
+    } else {
+      stableSince = null;
+      last = text;
+    }
+    await sleep(800);
+  }
+  return false;
+}
+
+// One page-context collector for bing: find the generative block by signature
+// (several sentences of prose plus >=2 distinct outbound citation hosts in one
+// container) and return answer text and citation links together. An organic
+// result for a different intent can never masquerade as an AI answer, and a
+// missing block returns empty — which the engine reports as
+// "no AI answer block rendered", an unknown, never a citation verdict.
+const bingCollect = () => {
+  const findAiBlock = () => {
+    // Only result items that are NOT organic cards (b_algo is a plain organic
+    // result; the generative block renders under other classes), never the
+    // outer wrapper div whose text begins with page chrome.
+    const candidates = document.querySelectorAll('#b_results > li:not(.b_algo)');
+    for (const el of candidates) {
+      const text = (el.innerText || '').trim();
+      if (text.length < 300) continue;
+      if (/^(skip to|about \d|accessibility)/i.test(text.slice(0, 24))) continue;
+      const sentences = text.split(/[.!?]+\s/).filter((x) => x.trim().length > 30).length;
+      if (sentences < 3) continue;
+      const hosts = new Set();
+      for (const a of el.querySelectorAll('a[href^="http"]')) {
+        try {
+          const u = new URL(a.href);
+          if (/bing\.com|microsoft\.com/.test(u.hostname)) continue;
+          hosts.add(u.hostname);
+        } catch { /* skip malformed */ }
+      }
+      if (hosts.size >= 3) return el;
+    }
+    return null;
+  };
+  const block = findAiBlock();
+  if (!block) return { answer: '', sources: [] };
+  const seen = new Set();
+  const sources = [];
+  for (const a of block.querySelectorAll('a[href^="http"]')) {
+    try {
+      const u = new URL(a.href);
+      if (/bing\.com|microsoft\.com/.test(u.hostname)) continue;
+      const key = u.hostname + u.pathname;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      sources.push({ url: a.href, title: (a.textContent || '').trim().slice(0, 200) || null, domain: u.hostname });
+    } catch { /* skip malformed */ }
+  }
+  return { answer: (block.innerText || '').trim(), sources };
+};
+
+// duck.ai in-page chat flow: the surface's own JS solves the VQD challenge,
+// so the engine drives fetch() from inside a real duck.ai page — cookies,
+// headers and challenge all native. Claude Haiku 4.5 serves anonymously.
+const DUCK_MODEL = 'claude-haiku-4-5';
+
+export async function duckChat(page, prompt) {
+  const result = await page.evaluate(async ({ model, text }) => {
+    const j = async (r) => { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json().catch(() => ({})); };
+    // Status first: same-origin response headers carry the VQD token.
+    const statusRes = await fetch('https://duck.ai/duckchat/v1/status', { credentials: 'include' });
+    const vqd = statusRes.headers.get('x-vqd-4') || statusRes.headers.get('x-vqd');
+    if (!vqd) throw new Error('no vqd token in status response');
+    const models = await j(await fetch('https://duck.ai/duckchat/v1/models', { credentials: 'include', headers: { 'x-vqd-4': vqd, 'x-vqd': vqd } }));
+    const ids = (models.data ?? []).map((m) => m.id ?? m.model ?? String(m));
+    if (!ids.some((id) => String(id).includes('claude'))) {
+      throw new Error('no claude model in duck lineup: ' + ids.slice(0, 6).join(','));
+    }
+    const chatRes = await fetch('https://duck.ai/duckchat/v1/chat', {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'content-type': 'application/json', 'x-vqd-4': vqd, 'x-vqd': vqd },
+      body: JSON.stringify({ model, messages: [{ role: 'user', content: text }], stream: true }),
+    });
+    if (!chatRes.ok) throw new Error('chat HTTP ' + chatRes.status);
+    const reader = chatRes.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let message = '';
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split('\n');
+      buf = lines.pop() ?? '';
+      for (const line of lines) {
+        const t = line.trim();
+        if (!t.startsWith('data:')) continue;
+        const payload = t.slice(5).trim();
+        if (!payload || payload === '[DONE]') continue;
+        try {
+          const obj = JSON.parse(payload);
+          message += obj.message ?? obj.content ?? '';
+        } catch { /* partial json across chunks */ }
+      }
+    }
+    return { message, models: ids };
+  }, { model: DUCK_MODEL, text: prompt });
+  return result;
+}
+
+export const OWN_PROVIDER_CONFIGS = {
+  grok: {
+    url: 'https://grok.com/',
+    label: 'Grok',
+    experimental: false,
+    navigateToPrompt: null, // the engine's grok branch owns the flow
+    waitForResponse: (page) => waitForStableBody(page),
+    extractResponse: (page) => page.evaluate(() => (document.body.innerText || '').trim()),
+    extractSources: async () => [], // inline links in text; panel extraction unproven
+  },
+  copilot: {
+    url: 'https://copilot.microsoft.com/',
+    label: 'Copilot',
+    experimental: true,
+    waitForResponse: (page) => waitForStableBody(page),
+    extractResponse: (page) => page.evaluate(() => (document.body.innerText || '').trim()),
+    extractSources: async () => [],
+  },
+  bing: {
+    url: 'https://www.bing.com/',
+    label: 'Bing AI answers',
+    experimental: false,
+    waitForResponse: async (page) => {
+      await sleep(6000);
+      await waitForStableBody(page, { stableMs: 1800, timeoutMs: 30000 });
+    },
+    extractResponse: async (page) => (await page.evaluate(bingCollect)).answer,
+    extractSources: async (page) => (await page.evaluate(bingCollect)).sources,
+  },
+};

package/src/citations/contract.js

@@ -29,7 +29,7 @@ export const CITATION_TARGET_SCOPES = Object.freeze(['domain', 'url']);
 
 // Engines this version knows. `mock` costs nothing, is deterministic per seed, and
 // exists so every test and every dry-run proves the pipeline without spending money.
-export const CITATION_ENGINES = Object.freeze(['mock', 'perplexity']);
+export const CITATION_ENGINES = Object.freeze(['mock', 'perplexity', 'duck', 'google-aio']);
 
 // Token rates used ONLY for the pre-call budget estimate. These are not bills; they
 // are the numbers the hard maxUsd cap is enforced against, so they are deliberately
@@ -92,6 +92,15 @@ export const citationPanelSchema = z.object({
   // weights, mentionText, fanOut, costEstimateUsd. This is how a dry run simulates a
   // real panel (and how a test simulates a collapse) without spending anything.
   mockFixtures: z.record(z.string(), z.any()).optional(),
+  // Competitor domains: the panel watches them alongside the primary target,
+  // each as its own cell identity (never averaged with the target).
+  competitors: z.array(z.object({
+    domain: z.string().min(3).max(253),
+    brand: z.string().min(1).max(100),
+    aliases: z.array(z.string().min(1).max(100)).max(12).default([]),
+  })).max(10).default([]),
+  // Locale pinning: surfaces vary answers by geography. Default en-US.
+  locale: z.string().min(2).max(10).default('en-US'),
   note: z.string().max(500).optional(),
 });
 

package/src/citations/fixtures/dataforseo-aio.json

@@ -0,0 +1,82 @@
+{
+  "version": "0.0.0",
+  "status_code": 20000,
+  "status_message": "Ok.",
+  "cost": 0.0012,
+  "tasks_count": 1,
+  "tasks_error": 0,
+  "tasks": [
+    {
+      "id": "09211815-1535-0067-0000-7b8e2b4e5c91",
+      "status_code": 20000,
+      "status_message": "Ok.",
+      "cost": 0.0012,
+      "result_count": 1,
+      "result": [
+        {
+          "keyword": "what is backlink monitoring",
+          "type": "organic",
+          "se_domain": "google.com",
+          "location_code": 2840,
+          "language_code": "en",
+          "check_url": "https://www.google.com/search?q=what%20is%20backlink%20monitoring&num=10&hl=en&gl=us&gws_rd=cr",
+          "datetime": "2026-09-18 18:15:03 +00:00",
+          "item_types": ["ai_overview", "organic", "featured_snippet", "people_also_ask"],
+          "se_results_count": 12400000,
+          "items": [
+            {
+              "type": "ai_overview",
+              "rank_group": 1,
+              "rank_absolute": 1,
+              "position": "top",
+              "xpath": "/html[1]/body[1]/div[6]/div[2]/div[9]/div[1]/div[2]/div[2]/div[1]/div[1]",
+              "text": "Backlink monitoring is the process of regularly tracking and analyzing the links pointing to your website from other sites. It involves checking whether your existing backlinks are still active, identifying new backlinks as they appear, and analyzing the quality and relevance of those links. Effective backlink monitoring helps you maintain a healthy link profile, identify potentially harmful links, and find opportunities for new link building. Common tools for backlink monitoring include Ahrefs, Semrush, and Moz, which provide comprehensive dashboards for tracking your link profile over time.",
+              "items": [
+                {
+                  "type": "ai_overview_item",
+                  "source": "backlinkmonitoring.ai",
+                  "domain": "backlinkmonitoring.ai",
+                  "title": "What Is Backlink Monitoring and Why It Matters",
+                  "url": "https://backlinkmonitoring.ai/blog/what-is-backlink-monitoring",
+                  "snippet": "Backlink monitoring is the practice of regularly tracking and analyzing inbound links to your website..."
+                },
+                {
+                  "type": "ai_overview_item",
+                  "source": "adaptify.ai",
+                  "domain": "adaptify.ai",
+                  "title": "What is Backlink Monitoring and Why Your SEO Needs It",
+                  "url": "https://adaptify.ai/blog/what-is-backlink-monitoring-and-why-your-seo-needs-it",
+                  "snippet": "Effective backlink monitoring helps you maintain a healthy link profile and identify harmful links..."
+                },
+                {
+                  "type": "ai_overview_item",
+                  "source": "lynkdog.com",
+                  "domain": "lynkdog.com",
+                  "title": "Backlink Monitoring: A Complete Beginner's Guide",
+                  "url": "https://lynkdog.com/blog/backlink-monitoring-beginners-guide",
+                  "snippet": "Backlink monitoring involves checking whether your existing backlinks are still active..."
+                },
+                {
+                  "type": "ai_overview_item",
+                  "source": "brand24.com",
+                  "domain": "brand24.com",
+                  "title": "Backlinks Monitoring 101: Tools, Tips, and Best Practices",
+                  "url": "https://brand24.com/blog/backlinks-monitoring-101/",
+                  "snippet": "Common tools for backlink monitoring include Ahrefs, Semrush, and Moz..."
+                }
+              ]
+            },
+            {
+              "type": "organic",
+              "rank_group": 1,
+              "rank_absolute": 2,
+              "url": "https://backlinko.com/hub/seo/backlinks",
+              "domain": "backlinko.com",
+              "title": "What Are Backlinks in SEO & Why You Need Them"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/citations/panel-builder.js

@@ -0,0 +1,44 @@
+// Guided panel authoring: turn a domain + optional brand into a ready-to-run
+// panel with sensible defaults. The buyer who doesn't want to write JSON
+// gets a starting point they can edit.
+export function buildStarterPanel({ domain, brand, aliases = [], engines = [
+  { engine: 'chatgpt', via: 'browser' },
+  { engine: 'duck', model: 'claude-haiku-4-5' },
+  { engine: 'google-aio' },
+], samples = 10, maxUsd = 1.0, competitors = [] } = {}) {
+  if (!domain || !brand) throw new Error('domain and brand are required');
+  const prompts = defaultPrompts(domain);
+  const targets = [
+    { domain, scope: 'domain', brand, aliases },
+    ...competitors.map((c) => ({ domain: c.domain, scope: 'domain', brand: c.brand, aliases: c.aliases ?? [] })),
+  ];
+  return {
+    schema_version: 1,
+    note: `Citation watch for ${brand}`,
+    targets,
+    prompts,
+    engines,
+    samples,
+    maxUsd,
+    competitors: competitors.map((c) => ({ domain: c.domain, brand: c.brand, aliases: c.aliases ?? [] })),
+    locale: 'en-US',
+  };
+}
+
+// Ten sensible starting prompts: category, how-to, comparison, tool-seeking.
+// Replace with GSC-derived panels (DP-0032) once search data is wired.
+function defaultPrompts(domain) {
+  const base = domain.split('.')[0];
+  return [
+    { id: 'category', text: `what is ${base}` },
+    { id: 'best-tools', text: `best ${base} tools` },
+    { id: 'how-to', text: `how to use ${base}` },
+    { id: 'comparison', text: `${base} vs alternatives` },
+    { id: 'open-source', text: `open source ${base}` },
+    { id: 'pricing', text: `${base} pricing` },
+    { id: 'reviews', text: `${base} reviews` },
+    { id: 'tutorial', text: `${base} tutorial` },
+    { id: 'alternatives', text: `${base} alternatives free` },
+    { id: 'for-beginners', text: `${base} for beginners` },
+  ];
+}