agentlinkops 0.5.0 → 0.5.1

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/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

@@ -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(),
 });
 
@@ -95,7 +98,8 @@ export const citationPanelSchema = z.object({
 // 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 +121,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/runner.js

@@ -94,6 +94,9 @@ export async function runEpoch(panelInput, options = {}) {
         run = await cell.engine.run({ prompt: cell.prompt.text, runIndex });
       } catch (cause) {
         if (cause instanceof EngineError && cause.retriable) {
+          // An unknown is honest, but never silent: the reason travels to
+          // stderr so a run of unknowns names its wall.
+          if (options.err) options.err(`unknown observation (${cell.id}): ${cause.message}`);
           outcomesByCell.get(cell.id).push('unknown');
           continue;
         }
@@ -101,7 +104,7 @@ export async function runEpoch(panelInput, options = {}) {
       }
       spent += run.costEstimateUsd ?? 0;
 
-      const envelope = evidenceEnvelopeSchema.parse({
+      const envelope = {
         schema_version: CITATIONS_VERSION,
         epoch_id: epochId, cell_id: cell.id, run_index: runIndex, prompt: cell.prompt.text,
         engine_identity: cell.identity,
@@ -110,10 +113,17 @@ export async function runEpoch(panelInput, options = {}) {
         usage: run.usage ?? { input_tokens: 0, output_tokens: 0 },
         cost_estimate_usd: run.costEstimateUsd ?? 0,
         at: nowIso(),
-      });
-      const evidenceJson = JSON.stringify(envelope);
-      const digest = sha256(evidenceJson);
-      await writeFile(join(evidenceRoot, `${digest}.json`), evidenceJson, 'utf8');
+      };
+      const digest = sha256(JSON.stringify(envelope));
+      // The screenshot is a sibling of the envelope: same content-addressed
+      // directory, named by the envelope digest it belongs to. An observation
+      // of a rendered surface carries the pixels of that surface.
+      if (run.screenshotPng) {
+        const shotName = `${digest}.screenshot.png`;
+        await writeFile(join(evidenceRoot, shotName), run.screenshotPng);
+        envelope.screenshot_file = shotName;
+      }
+      await writeFile(join(evidenceRoot, `${digest}.json`), JSON.stringify(evidenceEnvelopeSchema.parse(envelope)), 'utf8');
 
       const tiered = classifyOutcome(cell.target, run, options.verifyFetch ?? null);
       outcomesByCell.get(cell.id).push(tiered.outcome);
@@ -147,5 +157,11 @@ export async function runEpoch(panelInput, options = {}) {
   await writeFile(join(dir, CITATION_FILES.observations), observationRows.map((r) => JSON.stringify(r)).join('\n') + (observationRows.length ? '\n' : ''), { flag: 'a' });
   await writeFile(join(dir, CITATION_FILES.epochs), epochRows.map((r) => JSON.stringify(r)).join('\n') + (epochRows.length ? '\n' : ''), { flag: 'a' });
 
+  // Browser engines hold a browser and maybe an Xvfb display for the whole
+  // epoch; release both once the tallies are written.
+  for (const engine of new Set(cells.map((c) => c.engine))) {
+    try { await engine.close?.(); } catch { /* cleanup is best-effort */ }
+  }
+
   return { epochId, cells: epochRows, spentEstimateUsd: Number(spent.toFixed(6)), aborted, samples, maxUsd };
 }