agentlinkops 0.5.1 → 0.6.0

package/cli/citation.js

@@ -8,7 +8,7 @@
 // Exit codes follow the link commands: 0 nothing actionable (including
 // insufficient_data — an unknown never fails), 1 a cell classified declined with
 // complete evidence, 2 usage, configuration or budget-abort errors.
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
 
 import { parseArgs } from './args.js';
 import { loadPanel, runEpoch } from '../src/citations/runner.js';
@@ -25,6 +25,17 @@ const USAGE = `agentlinkops citation — AI citation watches in this repository
                                             measure the consumer UI through Camoufox
                                             (dedicated account, personal cadence; evidence
                                             includes a screenshot of every answer)
+  agentlinkops citation report PANEL.json [--out FILE] [--dir DIR]
+                                            render the latest epoch as a self-contained
+                                            HTML report: trends, screenshots inline,
+                                            Wilson intervals, honest classifications
+  agentlinkops citation watch PANEL.json --cadence weekly|daily|hourly|monthly
+                                            register a cron entry that runs the epoch
+                                            and generates the report on schedule
+  agentlinkops citation watch --list         list registered citation watches
+  agentlinkops citation watch --remove NAME  remove a registered watch
+  agentlinkops citation alert PANEL.json     check the latest epoch for declines;
+                                            logs an alert line if any cell declined
   agentlinkops citation help                 this help
 
 Panel (JSON): targets (domain or url, brand, aliases), prompts, engines
@@ -41,6 +52,81 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
   const args = parseArgs(argv);
   const command = args._[0] ?? 'help';
   if (command === 'help' || args.help) { out(USAGE); return 0; }
+  if (command === 'alert') {
+    const panelPath = args._[1];
+    if (!panelPath) { err('citation alert needs a panel file'); return 2; }
+    const { readFile } = await import('node:fs/promises');
+    const dir = resolve(cwd, args.dir ?? '.agentlinkops');
+    let latestEpochId = null;
+    try {
+      const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
+      const rows = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+      if (rows.length > 0) latestEpochId = rows[rows.length - 1].epoch_id;
+    } catch { /* no epochs */ }
+    if (!latestEpochId) { out('no epochs to check'); return 0; }
+    const { shouldAlert } = await import('../src/citations/alert.js');
+    const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
+    const cells = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l)).filter((r) => r.epoch_id === latestEpochId);
+    if (shouldAlert(cells)) {
+      const declined = cells.filter((c) => c.classification === 'declined');
+      err(`ALERT: ${declined.length} cell${declined.length === 1 ? '' : 's'} declined:`);
+      for (const c of declined) err(`  ${c.cell_id}: rate ${c.rate.toFixed(2)} (was ${c.baseline?.rate?.toFixed(2) ?? 'n/a'})`);
+      return 1; // exit 1 = actionable, same convention as link checks
+    }
+    out('no declines detected');
+    return 0;
+  }
+  if (command === 'watch') {
+    const { registerWatch, listWatches, removeWatch } = await import('../src/citations/watch.js');
+    if (args.list) {
+      const watches = await listWatches();
+      if (watches.length === 0) { out('no citation watches registered'); return 0; }
+      for (const w of watches) out(`${w.panel}  ${w.cron}`);
+      return 0;
+    }
+    if (args.remove) {
+      const result = await removeWatch(args.remove);
+      out(`removed watch: ${result.removed}`);
+      return 0;
+    }
+    const panelPath = args._[1];
+    if (!panelPath) { err('citation watch needs a panel file (or --list / --remove)'); return 2; }
+    const cadence = args.cadence ?? 'weekly';
+    try {
+      const result = await registerWatch({ panelPath, cadence });
+      out(`citation watch registered: ${result.panelPath}`);
+      out(`cadence: ${result.cadence} (${result.next})`);
+      out(`cron: ${result.cronSpec}`);
+      return 0;
+    } catch (cause) {
+      err(cause.message);
+      return 2;
+    }
+  }
+  if (command === 'report') {
+    const panelPath = args._[1];
+    if (!panelPath) { err('citation report needs a panel file'); return 2; }
+    const dir = resolve(cwd, args.dir ?? '.agentlinkops');
+    const { generateReport } = await import('../src/citations/report.js');
+    const { readFile, writeFile: wf } = await import('node:fs/promises');
+    // Find the latest epoch for this panel by reading the epochs file
+    let latestEpochId = null;
+    try {
+      const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
+      const rows = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+      if (rows.length > 0) latestEpochId = rows[rows.length - 1].epoch_id;
+    } catch { /* no epochs yet */ }
+    if (!latestEpochId) { err('no epochs found — run an epoch first'); return 2; }
+    const panel = JSON.parse(await readFile(resolve(cwd, panelPath), 'utf8'));
+    const html = await generateReport({ dir, epochId: latestEpochId, panel });
+    const outPath = args.out ? resolve(cwd, args.out) : join(dir, 'citations', `report-${latestEpochId.slice(0, 15)}.html`);
+    const { dirname, join: j } = await import('node:path');
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(dirname(outPath), { recursive: true });
+    await wf(outPath, html, 'utf8');
+    out(`report written: ${outPath} (${Math.round(html.length / 1024)} KB, self-contained)`);
+    return 0;
+  }
   if (command !== 'run') { err(`unknown citation command: ${command}`); err(USAGE); return 2; }
 
   const panelPath = args._[1];
@@ -83,6 +169,24 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
     }
     if (spec.engine === 'mock') {
       engines.set(identity, createMockEngine({ fixtures: panel.mockFixtures ?? {} }));
+    } else if (spec.engine === 'google-aio') {
+      // Fixture-first: runs against the recorded response with no credentials.
+      // Activates live the moment DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD exist.
+      const { createGoogleAioEngine } = await import('../src/citations/adapter.js');
+      const creds = env.DATAFORSEO_LOGIN && env.DATAFORSEO_PASSWORD
+        ? { login: env.DATAFORSEO_LOGIN, password: env.DATAFORSEO_PASSWORD }
+        : null;
+      engines.set(identity, createGoogleAioEngine({ credentials: creds }));
+      if (!creds) err(`google-aio: fixture mode (set DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD for live)`);
+    } else if (spec.engine === 'duck') {
+      // Self-hosted Duck2api on the VPS: the whole Claude family plus GPT-5.6
+      // anonymously through duck.ai. Localhost endpoint, no key.
+      const { createOpenAiCompatibleEngine } = await import('../src/citations/adapter.js');
+      engines.set(identity, createOpenAiCompatibleEngine({
+        baseUrl: env.DUCK2API_URL ?? 'http://127.0.0.1:8090/v1',
+        model: spec.model ?? 'claude-haiku-4-5',
+        providerLabel: 'duck-anon',
+      }));
     } else if (spec.engine === 'perplexity') {
       // Presence only, never the value — the same rule doctor applies to tokens.
       if (!env.PERPLEXITY_API_KEY) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentlinkops",
-  "version": "0.5.1",
-  "description": "A backlink ledger that lives in your repository: local link checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
+  "version": "0.6.0",
+  "description": "A backlink and AI citation ledger that lives in your repository: local link and citation checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,9 +46,12 @@
     "mcp",
     "backlinks",
     "seo",
+    "citation-monitoring",
+    "ai-citations",
     "agent",
     "cli",
     "link-monitoring",
+    "citation-watch",
     "ledger",
     "jsonl"
   ],
@@ -64,4 +67,4 @@
   "optionalDependencies": {
     "playwright-core": "^1.63.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 });
+    });
+  });
+}