agentlinkops 0.6.1 → 0.6.3

package/src/citations/alert.js

@@ -10,7 +10,7 @@ export function shouldAlert(cells) {
   return cells.some((c) => c.classification === 'declined');
 }
 
-export async function sendAlertEmail({ to, subject, htmlPath, smtp = {} }) {
+export async function sendAlertEmail({ to, subject, htmlPath, smtp = {}, execFileImpl = execFile }) {
   if (!to || !htmlPath) throw new Error('sendAlertEmail needs to and htmlPath');
   const { host, port, user, pass, from } = smtp;
   if (!host || !user || !pass) {
@@ -28,26 +28,51 @@ export async function sendAlertEmail({ to, subject, htmlPath, smtp = {} }) {
     .slice(0, 2000);
 
   const python = `
-import smtplib
+import json, sys, smtplib
 from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
+data = json.load(sys.stdin)
 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:
+msg['Subject'] = data['subject']
+msg['From'] = data['from']
+msg['To'] = data['to']
+msg.attach(MIMEText(data['text'], 'plain'))
+msg.attach(MIMEText(data['html'], 'html'))
+with smtplib.SMTP(data['host'], data['port'], timeout=30) as s:
     s.starttls()
-    s.login(${JSON.stringify(user)}, ${JSON.stringify(pass)})
+    s.login(data['user'], data['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}`));
+    const child = execFileImpl('python3', ['-c', python], (err) => {
+      if (err) reject(new Error('smtp send failed'));
       else resolve({ delivered: true, htmlPath });
     });
+    child.stdin.on('error', () => reject(new Error('smtp input failed')));
+    child.stdin.end(JSON.stringify({ subject: subject ?? 'Citation decline', from: from ?? user, to,
+      text: textBody, html, host, port: Number(port ?? 587), user, pass }));
   });
 }
+
+// Delivery is opt-in and configured by the person running the local CLI.
+export function validateAlertWebhook(endpoint) {
+  const url = new URL(endpoint);
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (url.username || url.password || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) {
+    throw new Error('citation webhook requires HTTPS (HTTP is allowed only on loopback)');
+  }
+  return url;
+}
+export async function sendAlertWebhook({ endpoint, epochId, cells, htmlPath, fetchImpl = globalThis.fetch }) {
+  const url = validateAlertWebhook(endpoint);
+  if (!shouldAlert(cells)) return { delivered: false, reason: 'no decline' };
+  const html = await readFile(htmlPath, 'utf8');
+  const response = await fetchImpl(url, {
+    method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ schema_version: 1, type: 'citation.declined', epoch_id: epochId,
+      cells: cells.filter(cell => cell.classification === 'declined'), report: { content_type: 'text/html', html } }),
+  }).catch(() => { throw new Error('citation webhook delivery failed'); });
+  if (!response.ok) throw new Error(`citation webhook delivery failed (HTTP ${response.status})`);
+  return { delivered: true };
+}

package/src/citations/browser/engine.js

@@ -10,13 +10,25 @@
 // 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);
+const MODULE_LOADERS = {
+  'playwright-core': () => import('playwright-core'),
+  'node:fs/promises': () => import('node:fs/promises'),
+  './gen/core/providers/index.js': () => import('./gen/core/providers/index.js'),
+  './providers.js': () => import('./providers.js'),
+  './gen/lib/browser/camoufox.js': () => import('./gen/lib/browser/camoufox.js'),
+  './gen/lib/browser/display.js': () => import('./gen/lib/browser/display.js'),
+  './shims/utils.js': () => import('./shims/utils.js'),
+  './gen/lib/browser/domOps.js': () => import('./gen/lib/browser/domOps.js'),
+};
+const lazy = async path => {
+  if (!MODULE_LOADERS[path]) throw new Error('Unsupported browser module');
+  return MODULE_LOADERS[path]();
+};
 
 let playwrightFirefox = null;
 async function firefox() {
@@ -32,9 +44,17 @@ async function firefox() {
 
 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;
+// Per-engine nominal estimates for the pre-call budget check. Measured from
+// actual proxy burn during the 2026-09-17/18 sessions: browser engines burn
+// 3-8 MB per observation (full page + assets) while the duck HTTP lane uses
+// kilobytes. These are the estimates the cap enforces against, checked BEFORE
+// each call. These are estimates, not metered bandwidth or a hard invoice cap.
+const ENGINE_NOMINAL_COST = Object.freeze({
+  chatgpt: 0.03, 'ai-overview': 0.03, copilot: 0.03, grok: 0.03,
+  gemini: 0.03, claude: 0.03, perplexity: 0.02, bing: 0.02,
+  duckai: 0.001,
+});
+const DEFAULT_NOMINAL_COST = 0.03;
 
 function parseProxyUrl(raw) {
   if (!raw) return null;
@@ -50,21 +70,28 @@ function parseProxyUrl(raw) {
   }
 }
 
-export function createBrowserEngine({ engineName, env = process.env, onEvent = () => {} } = {}) {
+export function createBrowserEngine({ engineName, env = process.env, onEvent = () => {}, runtime = {} } = {}) {
   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');
+  const sessionDir = runtime.sessionDir ?? join(homedir(), '.agentlinkops', 'citations', 'sessions');
+  const load = runtime.loadModule ?? lazy;
+  const platform = runtime.platform ?? process.platform;
 
   let browserHandle = null;   // { browser, cleanup } for the whole epoch
   let displayHandle = null;
   let providerConfig = null;
+  async function closeQuietly(action) {
+    let timer;
+    try { await Promise.race([Promise.resolve().then(action).catch(() => null), new Promise(resolve => { timer = setTimeout(resolve, runtime.cleanupTimeoutMs ?? 5000); })]); }
+    finally { clearTimeout(timer); }
+  }
 
   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');
+    const { PROVIDER_CONFIGS } = await load('./gen/core/providers/index.js');
+    const { OWN_PROVIDER_CONFIGS } = await load('./providers.js');
     providerConfig = OWN_PROVIDER_CONFIGS[engineName] ?? PROVIDER_CONFIGS[engineName];
     if (!providerConfig) throw new EngineError(`no provider config for ${engineName}`);
     return providerConfig;
@@ -73,14 +100,14 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
   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(),
+      await load('./gen/lib/browser/camoufox.js'),
+      await load('./gen/lib/browser/display.js'),
+      runtime.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()) {
+    if (platform === 'linux' && !display.detectDisplay()) {
       displayHandle = await display.ensureDisplay({ allowExistingDisplay: false });
       onEvent(`display: ${displayHandle.display}`);
     }
@@ -96,7 +123,7 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
       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',
+      headlessMode: platform === 'linux' ? 'virtual' : 'headful',
     });
     const launchOpts = { ...options, executablePath: options.executablePath };
     if (proxy) launchOpts.proxy = proxy;
@@ -105,7 +132,7 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     browserHandle = {
       browser,
       cleanup: async () => {
-        await browser.close().catch(() => null);
+        await closeQuietly(() => browser.close());
         await displayHandle?.cleanup?.().catch(() => null);
         displayHandle = null;
       },
@@ -115,25 +142,71 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
 
   async function loadStorageState() {
     try {
-      const { readFile } = await lazy('node:fs/promises');
+      const { readFile } = await load('node:fs/promises');
       return JSON.parse(await readFile(join(sessionDir, `${engineName}.json`), 'utf8'));
     } catch {
       return undefined; // anonymous session: several surfaces work logged-out
     }
   }
 
+  // Stock playwright-core editor finder. The vendored finder checks
+  // Locator.getEditableState(), a patchright-only API that silently nulls on
+  // stock playwright and rejects every candidate; this version expresses the
+  // same intent (visible, sized, editable, enabled) with portable calls.
+  // Pierces shadow DOM because some surfaces nest their composer inside one.
+  async function findEditor(page, selectors) {
+    for (const selector of selectors) {
+      const nodes = page.locator(selector);
+      const count = await nodes.count().catch(() => 0);
+      for (let i = 0; i < count; i += 1) {
+        const el = nodes.nth(i);
+        if (!(await el.isVisible().catch(() => false))) continue;
+        const box = await el.boundingBox().catch(() => null);
+        if (!box || box.width < 8 || box.height < 8) continue;
+        await el.scrollIntoViewIfNeeded().catch(() => {});
+        if (!(await el.isEditable().catch(() => false))) continue;
+        if (!(await el.isEnabled().catch(() => false))) continue;
+        return { locator: el, selector };
+      }
+    }
+    // Shadow DOM fallback: pierce roots for composer elements not reachable
+    // through the document-level selectors above.
+    const shadowSpot = await page.evaluate(() => {
+      const all = [];
+      const walk = (root) => {
+        for (const el of root.querySelectorAll('textarea, [contenteditable="true"], [role="textbox"]')) all.push(el);
+        for (const el of root.querySelectorAll('*')) { if (el.shadowRoot) walk(el.shadowRoot); }
+      };
+      walk(document);
+      for (const el of all) {
+        const r = el.getBoundingClientRect();
+        if (r.width > 60 && r.height > 10) return { found: true, tag: el.tagName };
+      }
+      return { found: false };
+    }).catch(() => ({ found: false }));
+    if (shadowSpot.found) {
+      // A composer exists in shadow DOM but our selectors can't reach it.
+      // Fall through to the generic locator on the broadest selector.
+      const broad = page.locator('textarea, [contenteditable="true"], [role="textbox"]').first();
+      if (await broad.isVisible().catch(() => false)) return { locator: broad, selector: 'shadow-dom-fallback' };
+    }
+    return null;
+  }
+
   return {
     identity,
-    estimateCostUsd: () => NOMINAL_COST_USD,
+    estimateCostUsd: () => ENGINE_NOMINAL_COST[engineName] ?? DEFAULT_NOMINAL_COST,
 
     async run({ prompt }) {
       const config = await ensureProviderConfig();
-      const { browser, cleanup } = await ensureBrowser();
+      const { browser } = await ensureBrowser();
+      const storageState = await loadStorageState();
       const context = await browser.newContext({
-        storageState: await loadStorageState(),
+        storageState,
         locale: 'en-US',
         timezoneId: 'America/New_York',
       });
+      try {
       // 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.
@@ -144,8 +217,10 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
           return route.continue();
         });
       }
-      try {
         const page = await context.newPage();
+        const { runPageDomOp } = await load('./gen/lib/browser/domOps.js');
+        page.runDomOp = (operation, params = {}) => runPageDomOp(page, operation, params);
+        let answer = '';
         page.setDefaultTimeout(45_000);
 
         if (config.navigateToPrompt) {
@@ -159,7 +234,13 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
           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"]')];
+              // Pierce shadow DOM: grok's composer may live inside a shadow root.
+              const els = [];
+              const walk = (root) => {
+                for (const el of root.querySelectorAll('textarea, [contenteditable="true"], [role="textbox"]')) els.push(el);
+                for (const el of root.querySelectorAll('*')) { if (el.shadowRoot) walk(el.shadowRoot); }
+              };
+              walk(document);
               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)) };
@@ -178,7 +259,7 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
           // 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 { duckChat } = await load('./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 });
@@ -192,46 +273,54 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
         } 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)`);
+          // Hydration retry: first paint is not hydration. Poll for a real editor.
+          const { PROVIDER_EDITOR_SELECTORS } = await load('./shims/utils.js');
+          let editor = null;
+          const editorDeadline = Date.now() + 50_000;
+          while (!editor && Date.now() < editorDeadline) {
+            await config.beforePromptHook?.(page).catch(() => {});
+            editor = await findEditor(page, PROVIDER_EDITOR_SELECTORS[engineName]);
+            if (!editor) await page.waitForTimeout(3000);
+          }
+          if (!editor) throw new EngineError(`${engineName}: no prompt editor found after hydration retries (surface may be gated or changed)`, { retriable: true });
 
-          const { insertPromptIntoEditor } = await lazy('./gen/lib/input/editor/promptInput.js');
-          await insertPromptIntoEditor(page, editor.locator, prompt, engineName);
+          // Humanized typing: instant fill is a bot tell. Real keystrokes with
+          // jittered cadence; fill stays as the recovery path when typing fails.
+          await editor.locator.click().catch(() => {});
+          await page.waitForTimeout(400);
+          const typeDelay = 70 + Math.floor(Math.random() * 110);
+          await editor.locator.pressSequentially(prompt, { delay: typeDelay }).catch(async () => {
+            await editor.locator.fill(prompt);
+          });
+          await page.waitForTimeout(600);
+          const typedCheck = await editor.locator.inputValue().catch(() => '');
+          if (typedCheck.trim().length === 0) {
+            await editor.locator.fill(prompt).catch(() => {});
+          }
           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(); }
+          // Submit: the surface's own send button when it exposes one; Enter fallback.
+          // Submission is verified: the composer clears or a user turn appears.
+          const send = await page.locator('button[aria-label="Send message"], button[data-testid="send-button"], button[aria-label*="Submit" i], button[aria-label*="Send" i]').first();
+          if (await send.isVisible().catch(() => false)) { await send.click(); }
           else { await editor.locator.press('Enter'); }
+          await page.waitForTimeout(2500);
         }
         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)}`);
+        let extractionFailed = config.citationExtraction === 'unsupported';
+        const sources = await config.extractSources(page).catch(() => {
+          extractionFailed = true;
+          onEvent('sources extraction failed; observation retained as unknown');
           return [];
         });
         const screenshotPng = await page.screenshot({ fullPage: false }).catch(() => null);
@@ -241,26 +330,32 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
           provider: 'web-own-browser',
           model: engineName,
           providerModelVersion: `${engineName}-web`,
+          browserContext: { surface: 'web', authentication: storageState ? 'saved-session' : 'anonymous', account_tier: 'unknown' },
           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),
+          ...(extractionFailed ? { unknown: true, failure: { code: 'CITATION_EXTRACTION_UNAVAILABLE', message: 'Citation extraction was unavailable; this is not a confirmed absence' } } : {}),
+          citations: (sources ?? []).map((s) => ({ url: s.url, ...(s.title || s.cited_text ? { title: s.title ?? s.cited_text } : {}) })).filter((c) => typeof c.url === 'string' && c.url.length > 0),
           fanOut: [],
           usage: { input_tokens: 0, output_tokens: 0 },
-          costEstimateUsd: NOMINAL_COST_USD,
+          costEstimateUsd: ENGINE_NOMINAL_COST[engineName] ?? DEFAULT_NOMINAL_COST,
           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 });
+        const error = new EngineError(`${engineName}: browser run failed (${cause?.name === 'TypeError' ? 'compatibility error' : retriable ? 'timeout or connection error' : 'surface error'})`, { retriable, cause });
+        error.unknown = true;
+        throw error;
       } finally {
-        await context.close().catch(() => null);
+        await closeQuietly(() => context.close());
       }
     },
 
     // Called by the runner at epoch end.
     async close() {
       await browserHandle?.cleanup?.();
+      await displayHandle?.cleanup?.().catch(() => null);
+      displayHandle = null;
       browserHandle = null;
     },
   };

package/src/citations/browser/providers.js

@@ -142,7 +142,8 @@ export const OWN_PROVIDER_CONFIGS = {
     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
+    citationExtraction: 'unsupported',
+    extractSources: async () => [], // retain unknown until a scoped citation extractor is proven
   },
   copilot: {
     url: 'https://copilot.microsoft.com/',
@@ -150,6 +151,7 @@ export const OWN_PROVIDER_CONFIGS = {
     experimental: true,
     waitForResponse: (page) => waitForStableBody(page),
     extractResponse: (page) => page.evaluate(() => (document.body.innerText || '').trim()),
+    citationExtraction: 'unsupported',
     extractSources: async () => [],
   },
   bing: {

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

@@ -14,6 +14,7 @@ export {
 const envQuiet = () => Boolean(process.env.AGENTLINKOPS_BROWSER_QUIET);
 
 export const logger = {
+  debug: (...args) => { if (!envQuiet()) console.error('[browser:debug]', ...args); },
   log: (...args) => { if (!envQuiet()) console.error('[browser]', ...args); },
   warn: (...args) => { if (!envQuiet()) console.error('[browser:warn]', ...args); },
   error: (...args) => { console.error('[browser:error]', ...args); },