@broberg/lens-daemon 0.1.13 → 0.1.15

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "The Lens module of the cardmem daemon (flows, critic, coverage, capture sessions, the /lens/* routes and the cardmem-lens MCP) as a package. The daemon mounts createLensRouter(deps) + createLensMcpRouter(deps). Bun runtime.",
   "type": "module",
   "license": "MIT",
   "dependencies": {
-    "@broberg/ai-sdk": "0.56.0",
+    "@broberg/ai-sdk": "0.63.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@mozilla/readability": "^0.6.0",
     "hono": "^4.6.14",
@@ -16,7 +16,7 @@
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
     "@broberg/lens-svg": "0.1.0",
-    "@broberg/lens-engine": "0.13.0"
+    "@broberg/lens-engine": "0.13.1"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/critic-vision.ts

@@ -10,6 +10,7 @@
 // when projects.settings_json.composition_critic.vision === true (F126.3). This
 // module makes a call ONLY when asked; it never runs itself.
 
+import { AI_AGENT_NAME } from '@broberg/lens-engine';
 import type { CriticSeverity } from './critic-dom.ts';
 
 export interface VisionFinding {
@@ -126,7 +127,7 @@ function getDaemonAi() {
         if (process.env.OPENROUTER_API_KEY) providers.openrouter = sdk.openrouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY });
         if (Object.keys(providers).length === 0) return null;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        return sdk.createAI({ providers: providers as any }) as any;
+        return sdk.createAI({ providers: providers as any, agentName: AI_AGENT_NAME }) as any;
       } catch {
         return null;
       }

package/src/extension-flow.ts

@@ -15,6 +15,7 @@
 
 import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
+import type { BrowserContext } from 'playwright';
 import { join } from 'node:path';
 
 interface Manifest {
@@ -80,3 +81,23 @@ export async function prepareExtension(path: string, grantHostAccess: boolean):
 export const SIMULATED_ACCESS_NOTE =
   'host access SIMULATED: the extension ran from a temporary copy that may read every page, ' +
   'standing in for the toolbar click (activeTab) a headless run cannot make';
+
+/** F009.126 — write `values` into the loaded extension's chrome.storage.local, from
+ *  the extension's own context (MV3 service worker, or MV2 background page), so the
+ *  popup's first render already finds them — a login it keeps there, for example.
+ *  Read back and compared, so a seed that did not land fails the run here instead
+ *  of showing up later as a popup that is mysteriously logged out. */
+export async function seedExtensionStorage(context: BrowserContext, values: Record<string, unknown>): Promise<void> {
+  const target = context.serviceWorkers()[0] ?? context.backgroundPages()[0];
+  if (!target) throw new Error('storage_local: the extension has no service worker or background page to write chrome.storage.local from');
+  const keys = Object.keys(values);
+  const back = await target.evaluate(async (v: Record<string, unknown>) => {
+    const c = (globalThis as unknown as { chrome: { storage?: { local: { set(x: object): Promise<void>; get(k: string[]): Promise<Record<string, unknown>> } } } }).chrome;
+    if (!c.storage) return null;
+    await c.storage.local.set(v);
+    return c.storage.local.get(Object.keys(v));
+  }, values);
+  if (!back) throw new Error('storage_local: the extension has no chrome.storage — its manifest does not request the "storage" permission, so there is nowhere to seed');
+  const missing = keys.filter((k) => JSON.stringify(back[k]) !== JSON.stringify(values[k]));
+  if (missing.length) throw new Error(`storage_local: chrome.storage.local did not keep ${missing.join(', ')} — read back differs from what was written`);
+}

package/src/flow.ts

@@ -24,7 +24,7 @@ import {
   type Target,
 } from '@broberg/lens-engine';
 import { withPage, type LensEngine } from './browser.ts';
-import { defaultPopupOf, prepareExtension, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
+import { defaultPopupOf, prepareExtension, seedExtensionStorage, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
 import { authPrepare, type AuthConfig, type AuthEnv } from './auth/index.ts';
 import { takeShot, settleForShot } from './capture.ts';
 import { runCritic, topFindingMessage, type CriticMode, type CriticReport } from './critic.ts';
@@ -158,7 +158,11 @@ export type FlowStep =
   // F009.125 — open the loaded extension's popup as its own page in the SAME browser,
   // then put the page under test back in front so the extension sees it as the active
   // tab (measured). `path` defaults to the manifest's action.default_popup.
-  | { type: 'openPopup'; path?: string; label?: string; timeout?: number };
+  | { type: 'openPopup'; path?: string; label?: string; timeout?: number }
+  // F009.126 — pass when the run made a matching request (page, popup, any page in the
+  // run's browser). `url` is a substring, or a regex with match:"regex" (a path like
+  // "/api/clips" would otherwise read as a /pattern/flags literal). Fails listing what WAS seen.
+  | { type: 'expectRequest'; url: string; match?: 'contains' | 'regex'; method?: string; status?: number; label?: string; timeout?: number };
 
 export interface Flow {
   name: string;
@@ -187,6 +191,9 @@ export interface Flow {
 export interface FlowExtension {
   path: string;
   grant_host_access?: boolean;
+  /** F009.126 — written to the extension's chrome.storage.local before step 0, so a
+   *  popup that keeps its login there starts signed in (OAuth cannot run headless). */
+  storage_local?: Record<string, unknown>;
 }
 
 /**
@@ -425,6 +432,8 @@ export const STEP_TYPES = new Set([
   'waitForReady',
   // F009.125 — drive a loaded extension's popup
   'openPopup',
+  // F009.126 — assert a request the run made
+  'expectRequest',
 ]);
 
 /** Validate + normalise an untrusted flow (HTTP/MCP boundary). Throws on the
@@ -458,13 +467,21 @@ export function parseFlow(input: unknown): Flow {
   if (f.extension !== undefined) {
     const e = f.extension as unknown as Record<string, unknown>;
     const keys = e && typeof e === 'object' && !Array.isArray(e) ? Object.keys(e) : null;
-    if (!keys || typeof e.path !== 'string' || !e.path || keys.some((k) => k !== 'path' && k !== 'grant_host_access')) {
-      throw new Error('flow.extension must be {path: "<unpacked build dir>", grant_host_access?: boolean}');
+    if (!keys || typeof e.path !== 'string' || !e.path || keys.some((k) => k !== 'path' && k !== 'grant_host_access' && k !== 'storage_local')) {
+      throw new Error('flow.extension must be {path: "<unpacked build dir>", grant_host_access?: boolean, storage_local?: {…}}');
     }
     if (e.grant_host_access !== undefined && typeof e.grant_host_access !== 'boolean') {
       throw new Error('flow.extension.grant_host_access must be a boolean');
     }
-    extension = { path: e.path, ...(e.grant_host_access === true ? { grant_host_access: true } : {}) };
+    const sl = e.storage_local;
+    if (sl !== undefined && (sl === null || typeof sl !== 'object' || Array.isArray(sl))) {
+      throw new Error('flow.extension.storage_local must be an object of {key: JSON value} — it is passed to chrome.storage.local.set as-is');
+    }
+    extension = {
+      path: e.path,
+      ...(e.grant_host_access === true ? { grant_host_access: true } : {}),
+      ...(sl !== undefined ? { storage_local: sl as Record<string, unknown> } : {}),
+    };
   }
   validateAndNormalizeSteps(f.steps);
   if (!extension && usesPopup(f.steps as FlowStep[])) {
@@ -482,6 +499,38 @@ export function parseFlow(input: unknown): Flow {
   };
 }
 
+function requestRegex(u: string): RegExp {
+  try {
+    return new RegExp(u);
+  } catch (err) {
+    throw new Error(`expectRequest: url ${u} is not a valid regex — ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** F009.126 — one request the run's browser made, as expectRequest sees it. */
+export interface SeenRequest {
+  method: string;
+  url: string;
+  /** null while in flight, or when it failed before a response. */
+  status: number | null;
+  failed?: string;
+}
+
+/** F009.126 — does this request satisfy the step? Exported for test. */
+export function requestMatches(r: SeenRequest, want: { url: string; match?: 'contains' | 'regex'; method?: string; status?: number }): boolean {
+  const urlOk = want.match === 'regex' ? requestRegex(want.url).test(r.url) : r.url.includes(want.url);
+  if (!urlOk) return false;
+  if (want.method && r.method.toUpperCase() !== want.method.toUpperCase()) return false;
+  if (want.status !== undefined && r.status !== want.status) return false;
+  return true;
+}
+
+/** Query strings can carry tokens; a failure report shows the path only. */
+function redactQuery(u: string): string {
+  const q = u.indexOf('?');
+  return q === -1 ? u : `${u.slice(0, q)}?…`;
+}
+
 function usesPopup(steps: FlowStep[]): boolean {
   return steps.some(
     (st) =>
@@ -551,6 +600,7 @@ export const STEP_FIELDS: Record<string, string[]> = {
   conditional: ['testid', 'present', 'steps'],
   loop: ['data', 'steps', 'parallel'],
   openPopup: ['path'],
+  expectRequest: ['url', 'match', 'method', 'status'],
 };
 
 function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = false): void {
@@ -633,6 +683,20 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = fal
       }
       if ('browser' in s || inParallel) throw new Error(`step ${index} (openPopup): the popup opens in the main browser only`);
     }
+    if (s.type === 'expectRequest') {
+      const r = s as { url?: unknown; match?: unknown; method?: unknown; status?: unknown };
+      if (typeof r.url !== 'string' || !r.url) throw new Error(`step ${index} (expectRequest): url is required — a substring, or a regex with match:"regex"`);
+      if (r.match !== undefined && r.match !== 'contains' && r.match !== 'regex') {
+        throw new Error(`step ${index} (expectRequest): match must be "contains" (default) or "regex"`);
+      }
+      if (r.match === 'regex') requestRegex(r.url); // throws on a bad pattern now, not mid-run
+      if (r.method !== undefined && (typeof r.method !== 'string' || !/^[A-Za-z]+$/.test(r.method))) {
+        throw new Error(`step ${index} (expectRequest): method must be an HTTP method like "POST"`);
+      }
+      if (r.status !== undefined && (typeof r.status !== 'number' || !Number.isInteger(r.status) || r.status < 100 || r.status > 599)) {
+        throw new Error(`step ${index} (expectRequest): status must be an HTTP status code (100–599)`);
+      }
+    }
     if (s.type === 'autocomplete') {
       if (typeof (s as { value?: unknown }).value !== 'string') throw new Error('autocomplete step requires a string value');
       if (typeof (s as { option?: unknown }).option !== 'string') throw new Error('autocomplete step requires a string option testid');
@@ -1365,6 +1429,7 @@ function describe(step: FlowStep): string {
     case 'conditional': return `${step.present ? 'if' : 'unless'} [${step.testid}]`;
     case 'loop': return 'loop';
     case 'openPopup': return `openPopup ${step.path ?? '(manifest popup)'}`;
+    case 'expectRequest': return `expectRequest ${step.method ? `${step.method.toUpperCase()} ` : ''}${step.url}${step.status ? ` → ${step.status}` : ''}`;
     case 'waitForBuild': return `waitForBuild${step.sha ? ` ${step.sha.slice(0, 8)}` : ' (changed)'}`;
     // F255.4 — show the offset in the step label so a positioned click is
     // recognisable in the report (a plain "click canvas" hides where it aimed).
@@ -2329,6 +2394,8 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       throw new Error('loop steps are flattened before execution');
     case 'openPopup':
       throw new Error('openPopup steps are handled by runSeq, never execStep');
+    case 'expectRequest':
+      throw new Error('expectRequest steps are handled by runSeq, never execStep');
   }
 }
 
@@ -2693,6 +2760,8 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         const out =
           step.type === 'openPopup'
             ? await openPopup(step)
+            : step.type === 'expectRequest'
+            ? await expectRequest(step, vars)
             : await execStep(sp, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening, opts.secretRoot);
         const obj = out !== null && !Buffer.isBuffer(out) && typeof out === 'object' ? out : null;
         const inspect = obj && '__inspect' in obj ? (obj as { __inspect: string }).__inspect : null;
@@ -2859,6 +2928,41 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     extCtx.popup = popup;
     return null;
   };
+  // F009.126 — every request the run's main browser makes, from the first step on.
+  const seenRequests: SeenRequest[] = [];
+  const watchRequests = (context: BrowserContext): void => {
+    const byReq = new Map<object, SeenRequest>();
+    context.on('request', (req) => {
+      const r: SeenRequest = { method: req.method(), url: req.url(), status: null };
+      byReq.set(req, r);
+      seenRequests.push(r);
+    });
+    context.on('requestfinished', async (req) => {
+      const r = byReq.get(req);
+      if (r) r.status = (await req.response().catch(() => null))?.status() ?? null;
+    });
+    context.on('requestfailed', (req) => {
+      const r = byReq.get(req);
+      if (r) r.failed = req.failure()?.errorText ?? 'failed';
+    });
+  };
+  const expectRequest = async (step: Extract<FlowStep, { type: 'expectRequest' }>, vars: Record<string, unknown>): Promise<null> => {
+    const want = { url: subst(step.url, vars), match: step.match, method: step.method, status: step.status };
+    const deadline = Date.now() + stepTimeout(step);
+    for (;;) {
+      if (seenRequests.some((r) => requestMatches(r, want))) return null;
+      if (Date.now() >= deadline) break;
+      await new Promise((res) => setTimeout(res, 100));
+    }
+    const seen = seenRequests
+      .filter((r) => !/^(data|chrome-extension):/.test(r.url))
+      .slice(-10)
+      .map((r) => `${r.method} ${redactQuery(r.url)} → ${r.failed ? `failed (${r.failed})` : r.status ?? 'no response'}`);
+    throw new Error(
+      `no request matched ${want.method ? `${want.method.toUpperCase()} ` : ''}${want.url}${want.status ? ` → ${want.status}` : ''}. ` +
+        (seen.length ? `Seen (last ${seen.length}): ${seen.join('; ')}.` : 'The run made no http(s) requests at all.'),
+    );
+  };
   const readVideo = async (): Promise<Buffer | null> => {
     if (!videoDir) return null;
     try {
@@ -2912,8 +3016,10 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       async (page, context, ext) => {
         videoPage = page;
         collectFailures(page);
+        watchRequests(context);
         if (ext && flow.extension && prepared) {
           extCtx = { context, id: ext.id, main: page, popup: null };
+          if (flow.extension.storage_local) await seedExtensionStorage(context, flow.extension.storage_local);
           extensionInfo = {
             id: ext.id,
             path: flow.extension.path,

package/src/mcp.ts

@@ -364,16 +364,17 @@ export const TOOLS = [
               type: 'object',
               required: ['path'],
               description:
-                'F009.125 — run the flow in a Chromium with this UNPACKED extension loaded (the build dir holding manifest.json; relative = relative to local_path; must be inside the daemon sandbox). Then: {type:"openPopup", path?} opens the popup (default: the manifest action.default_popup) as its own page and keeps the page under test as the extension\'s ACTIVE tab (measured), and any step with in:"popup" runs in the popup. grant_host_access:true loads a TEMPORARY COPY with <all_urls> host access, standing in for the toolbar click (activeTab) a headless run cannot make — without it chrome.scripting on the page fails ("Cannot access contents of the page"). The original build is never written; the report carries extension {id, host_access:"simulated"|"as-built"}. CHROMIUM ONLY.',
+                'F009.125 — run the flow in a Chromium with this UNPACKED extension loaded (the build dir holding manifest.json; relative = relative to local_path; must be inside the daemon sandbox). Then: {type:"openPopup", path?} opens the popup (default: the manifest action.default_popup) as its own page and keeps the page under test as the extension\'s ACTIVE tab (measured), and any step with in:"popup" runs in the popup. grant_host_access:true loads a TEMPORARY COPY with <all_urls> host access, standing in for the toolbar click (activeTab) a headless run cannot make — without it chrome.scripting on the page fails ("Cannot access contents of the page"). The original build is never written; the report carries extension {id, host_access:"simulated"|"as-built"}. CHROMIUM ONLY. F009.126 — storage_local:{key: JSON} is written to the extension\'s chrome.storage.local before step 0 (read back and compared), so a popup that keeps its login there starts signed in; needs the "storage" permission in the manifest. Pair with {type:"expectRequest", url, match?:"contains"|"regex", method?, status?} to assert a request the page, popup or extension worker made (fails listing what was seen).',
               properties: {
                 path: { type: 'string' },
                 grant_host_access: { type: 'boolean' },
+                storage_local: { type: 'object', description: 'F009.126 — {key: JSON value} for chrome.storage.local, set before step 0.' },
               },
             },
             steps: {
               type: 'array',
               description: 'Ordered steps. Each has a "type"; testid-anchored steps carry a "testid". fillSelector/clickSelector carry a CSS "selector" + optional "frame" (one iframe selector or an outer→inner string[] chain) to reach a cross-origin iframe; fillSelector also carries "value". waitForUrl carries a "url" substring. A "loop" step has data[] + steps[] and substitutes {{field}}/{{__index}}.',
-              items: { type: 'object', required: ['type'], properties: { type: { type: 'string' }, testid: { type: 'string' }, selector: { type: 'string' }, frame: { type: ['string', 'array'], items: { type: 'string' } }, url: { type: 'string' }, value: { type: 'string' }, text: { type: 'string' }, path: { type: 'string' }, js: { type: 'string' }, label: { type: 'string' }, timeout: { type: 'number' }, sha: { type: 'string', description: 'F255.7 — waitForBuild step: the commit sha to wait for. Omit to wait for any change from the build live when the step starts.' }, at: { type: 'string', description: 'F255.4 — click a POINT inside the element instead of its centre: "50%,28%" (fraction of the box) or "40,120" (css px). For canvas/3D surfaces where the centre hits nothing. Works on click + clickSelector.' }, activate: { type: 'string', enum: ['auto', 'click', 'enter'], description: 'F255.1 — how a button is fired. auto (default) clicks and falls back to focus+Enter only if nothing observable happened; enter forces focus+Enter (Angular/MDC forms); click keeps mouse-only.' }, in: { type: 'string', enum: ['popup'], description: 'F009.125 — run this step in the extension popup an earlier openPopup opened (needs flow.extension).' } } },
+              items: { type: 'object', required: ['type'], properties: { type: { type: 'string' }, testid: { type: 'string' }, selector: { type: 'string' }, frame: { type: ['string', 'array'], items: { type: 'string' } }, url: { type: 'string' }, value: { type: 'string' }, text: { type: 'string' }, path: { type: 'string' }, js: { type: 'string' }, label: { type: 'string' }, timeout: { type: 'number' }, sha: { type: 'string', description: 'F255.7 — waitForBuild step: the commit sha to wait for. Omit to wait for any change from the build live when the step starts.' }, at: { type: 'string', description: 'F255.4 — click a POINT inside the element instead of its centre: "50%,28%" (fraction of the box) or "40,120" (css px). For canvas/3D surfaces where the centre hits nothing. Works on click + clickSelector.' }, activate: { type: 'string', enum: ['auto', 'click', 'enter'], description: 'F255.1 — how a button is fired. auto (default) clicks and falls back to focus+Enter only if nothing observable happened; enter forces focus+Enter (Angular/MDC forms); click keeps mouse-only.' }, in: { type: 'string', enum: ['popup'], description: 'F009.125 — run this step in the extension popup an earlier openPopup opened (needs flow.extension).' }, method: { type: 'string', description: 'F009.126 — expectRequest: HTTP method to require, e.g. "POST".' }, status: { type: 'number', description: 'F009.126 — expectRequest: response status to require, e.g. 201.' } } },
             },
           },
         },

package/src/validate-vision.ts

@@ -11,6 +11,7 @@
 //   MISTRAL_API_KEY auto-loaded from .env:
 //     bun run apps/agent/src/lens/validate-vision.ts
 
+import { AI_AGENT_NAME } from '@broberg/lens-engine';
 import { withPage } from './browser.ts';
 
 const FIXTURES = [
@@ -58,7 +59,7 @@ const sdk = await import('@broberg/ai-sdk');
 const providers: Record<string, unknown> = {};
 if (process.env.MISTRAL_API_KEY) providers.mistral = sdk.mistralAdapter({ apiKey: process.env.MISTRAL_API_KEY });
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const ai = sdk.createAI({ providers: providers as any }) as any;
+const ai = sdk.createAI({ providers: providers as any, agentName: AI_AGENT_NAME }) as any;
 
 for (const fx of FIXTURES) {
   const url = 'data:text/html;charset=utf-8,' + encodeURIComponent(fx.html);