agentlinkops 0.5.0 → 0.6.0

package/src/citations/browser/gen/utils/agent-constants.js

@@ -0,0 +1,87 @@
+const PROVIDER_NO_OUTPUT_TIMEOUT_MS = {
+  chatgpt: 9e4,
+  perplexity: 45e3,
+  gemini: 45e3,
+  claude: 6e4,
+  "ai-overview": 45e3
+};
+const PROVIDER_FORCE_EXIT_STABLE_MS = {
+  chatgpt: 45e3,
+  perplexity: 3e4,
+  gemini: 45e3,
+  claude: 45e3,
+  "ai-overview": 3e4
+};
+const PROVIDER_EDITOR_SELECTORS = {
+  chatgpt: [
+    "#prompt-textarea",
+    'div#prompt-textarea[contenteditable="true"][role="textbox"]',
+    'div.ProseMirror[contenteditable="true"][role="textbox"]',
+    'div[contenteditable="true"][role="textbox"][aria-multiline="true"][aria-label="Chat with ChatGPT"]'
+  ],
+  perplexity: [
+    "#ask-input",
+    'div#ask-input[contenteditable="true"][role="textbox"]',
+    'div[role="textbox"][data-lexical-editor="true"]',
+    'div[contenteditable="true"][role="textbox"][data-lexical-editor="true"]'
+  ],
+  gemini: [
+    'div[aria-label="Enter a prompt for Gemini"]',
+    'rich-textarea [contenteditable="true"][role="textbox"]',
+    'div[contenteditable="true"][role="textbox"][aria-multiline="true"]'
+  ],
+  claude: [
+    '[data-testid="chat-input"]',
+    'div[data-testid="chat-input"][contenteditable="true"][role="textbox"]',
+    '[data-testid="chat-input"][aria-multiline="true"]'
+  ],
+  "ai-overview": ['textarea[name="q"][role="combobox"]', 'textarea[role="combobox"][aria-label="Search"]']
+};
+const PROVIDER_SUBMIT_BTN_SELECTORS = {
+  chatgpt: ['button[data-testid="send-button"]'],
+  perplexity: ['button[aria-label*="Submit"]'],
+  gemini: ['button[aria-label*="Send"]'],
+  claude: ['button[aria-label*="Send"]'],
+  "ai-overview": []
+};
+const PROVIDER_MODEL_RESPONSE_SELECTORS = {
+  chatgpt: [
+    '[data-message-author-role="assistant"]',
+    '[data-testid^="conversation-turn"][data-turn="assistant"]'
+  ],
+  perplexity: [
+    'div[id^="markdown-content-"]',
+    '[id^="markdown-content-"] .prose'
+  ],
+  gemini: ["message-content .markdown"],
+  claude: [
+    '[data-is-streaming="false"] .standard-markdown',
+    ".standard-markdown"
+  ],
+  "ai-overview": [
+    '[data-container-id="main-col"]'
+  ]
+};
+const PROVIDER_RESPONSE_GENERATION_SELECTORS = {
+  chatgpt: ['button[data-testid="stop-button"]', 'button[aria-label*="stop" i]'],
+  perplexity: ['button[aria-label*="stop" i]'],
+  gemini: ['button[aria-label*="stop" i]'],
+  claude: ['button[aria-label*="stop" i]'],
+  "ai-overview": []
+};
+const RETRYABLE_ERRORS = [
+  "ERR_SSL_PROTOCOL_ERROR",
+  "ERR_CONNECTION",
+  "ERR_TIMED_OUT",
+  "ERR_PROXY_CONNECTION_FAILED",
+  "Timeout"
+];
+export {
+  PROVIDER_EDITOR_SELECTORS,
+  PROVIDER_FORCE_EXIT_STABLE_MS,
+  PROVIDER_MODEL_RESPONSE_SELECTORS,
+  PROVIDER_NO_OUTPUT_TIMEOUT_MS,
+  PROVIDER_RESPONSE_GENERATION_SELECTORS,
+  PROVIDER_SUBMIT_BTN_SELECTORS,
+  RETRYABLE_ERRORS
+};

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/browser/shims/errors.js

@@ -0,0 +1,26 @@
+// Local shims for the @oneglanse/* runtime imports in the vendored browser
+// layer. Upstream, these live in workspace packages we did not vendor; the
+// behavior below is the minimal honest equivalent. The logger writes to
+// stderr so a --json stdout reader never sees framework chatter.
+export class ExternalServiceError extends Error {
+  constructor(service, message, status, meta, cause) {
+    super(`${service}: ${message}`);
+    this.name = 'ExternalServiceError';
+    this.service = service;
+    this.status = status ?? null;
+    this.meta = meta ?? null;
+    if (cause) this.cause = cause;
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+export function toErrorMessage(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}

package/src/citations/browser/shims/types.js

@@ -0,0 +1,6 @@
+// Shim for @oneglanse/types runtime exports used outside the excluded
+// orchestration files. resolveAppMode upstream picks self-host vs cloud app
+// modes; we always run the local (self-host) shape.
+export function resolveAppMode() {
+  return 'selfhost';
+}

package/src/citations/browser/shims/utils.js

@@ -0,0 +1,32 @@
+// Shim for @oneglanse/utils runtime exports. The selector/timeout constants
+// are re-exported from the vendored agent-constants module unchanged; logger,
+// getDomain and getFaviconUrls are minimal equivalents.
+export {
+  PROVIDER_NO_OUTPUT_TIMEOUT_MS,
+  PROVIDER_FORCE_EXIT_STABLE_MS,
+  PROVIDER_EDITOR_SELECTORS,
+  PROVIDER_SUBMIT_BTN_SELECTORS,
+  PROVIDER_MODEL_RESPONSE_SELECTORS,
+  PROVIDER_RESPONSE_GENERATION_SELECTORS,
+  RETRYABLE_ERRORS,
+} from '../gen/utils/agent-constants.js';
+
+const envQuiet = () => Boolean(process.env.AGENTLINKOPS_BROWSER_QUIET);
+
+export const logger = {
+  log: (...args) => { if (!envQuiet()) console.error('[browser]', ...args); },
+  warn: (...args) => { if (!envQuiet()) console.error('[browser:warn]', ...args); },
+  error: (...args) => { console.error('[browser:error]', ...args); },
+};
+
+export function getDomain(url) {
+  try { return new URL(url).hostname.replace(/^www\./, ''); }
+  catch { return null; }
+}
+
+export function getFaviconUrls(url) {
+  try {
+    const u = new URL(url);
+    return [`https://www.google.com/s2/favicons?domain=${u.hostname}&sz=32`];
+  } catch { return []; }
+}

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
@@ -74,7 +74,10 @@ export const citationPromptSchema = z.object({
 });
 
 export const citationEngineSpecSchema = z.object({
-  engine: z.enum(CITATION_ENGINES),
+  // API engines ('mock', 'perplexity') or browser surfaces ('chatgpt',
+  // 'perplexity', 'gemini', 'claude', 'ai-overview' with via:'browser').
+  engine: z.string().min(2).max(40),
+  via: z.enum(['api', 'browser']).default('api'),
   model: z.string().min(1).max(80).optional(),
 });
 
@@ -89,13 +92,23 @@ 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(),
 });
 
 // The engine identity names HOW a surface was reached, because the same engine two
 // ways is two different measurements and is never averaged (limelitgeo/open's rule).
 export function engineIdentity(spec) {
-  const parts = [spec.engine, spec.engine === 'mock' ? 'builtin' : 'api'];
+  const provider = spec.via === 'browser' ? 'web-own-browser' : spec.engine === 'mock' ? 'builtin' : 'api';
+  const parts = [spec.engine, provider];
   if (spec.model) parts.push(spec.model);
   return parts.join(':');
 }
@@ -117,6 +130,9 @@ export const evidenceEnvelopeSchema = z.object({
   // evidence snapshots distinct content-addressed objects rather than silent
   // duplicates of each other.
   run_index: z.number().int().nonnegative(),
+  // Sibling screenshot of the answer surface, same directory as this envelope;
+  // present when the engine captures pixels (browser surfaces always do).
+  screenshot_file: z.string().max(120).optional(),
   prompt: z.string().min(1),
   engine_identity: z.string().min(1),
   provider_model_version: z.string().min(1),

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` },
+  ];
+}