@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/record.ts

@@ -0,0 +1,387 @@
+// F312.1 — record a live surface ON DEMAND, with nothing to script.
+//
+// `record: true` has existed on a flow since F255.5, and it is unreachable for
+// this purpose: a flow REQUIRES steps, and you must know what to drive before you
+// know what is wrong. The defect that motivated F312 only appears while an agent
+// writes into the stream — the reproduction is literally "open it and sit still
+// while something else happens". So the verb is: open, watch, stop.
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { BrowserContext, Page } from 'playwright';
+import { withPage } from './browser.ts';
+import {
+  PROBE_READ,
+  type ScrollNote,
+  findUncausedMoves,
+  probeSource,
+  rankFindings,
+  type FindOptions,
+  type MotionFinding,
+  type MotionSample,
+  type ProbeConfig,
+} from './motion-probe.ts';
+
+/**
+ * F312.11 — put the view back where a reader would keep it, and STAMP IT AS OURS.
+ *
+ * The driver stamp is the load-bearing half. Without it the re-scroll is itself
+ * an uncaused move and the run reports its own instrument; with it, the seconds
+ * that follow are a genuine "he is sitting still, high up, while content
+ * arrives" — which is the exact situation being complained about and the one a
+ * bottom-anchored recording can never observe.
+ */
+export async function scrollUpBy(page: Page, selector: string | null, px: number): Promise<void> {
+  // STAMP BEFORE, NOT ONLY AFTER. The scroll and the stamp are two round-trips
+  // to the page and the probe samples every 50ms, so a stamp that only follows
+  // the scroll can arrive after the move has already been sampled — measured 6
+  // Sept: 2 of 17 driver re-scrolls were reported as uncaused moves, i.e. the
+  // instrument filing its own action as the defect. Opening the grace window
+  // first closes the race in the safe direction.
+  await page.evaluate('window.__lensDriverActed && window.__lensDriverActed()').catch(() => {});
+  await page.evaluate(
+    ([s, n]) => {
+      const el = s ? document.querySelector(s as string) : null;
+      if (el) (el as HTMLElement).scrollTop = Math.max(0, (el as HTMLElement).scrollTop - (n as number));
+    },
+    [selector, px] as const,
+  );
+  await page.evaluate('window.__lensDriverActed && window.__lensDriverActed()').catch(() => {});
+}
+
+/** F312.21 — what the tab seeding did, or why it could not. Never inferred from
+ *  a later click failing: "the tab was not there" and "the click missed" are
+ *  different faults with different fixes. */
+/**
+ * F312.17 — wait until the surface has stopped ARRIVING, not merely stopped
+ * growing for a moment. Three consecutive equal readings of height AND row
+ * count; a transcript renders a few rows, pauses while it fetches, then jumps,
+ * so one quiet moment passes for finished.
+ *
+ * Extracted because I reintroduced the very bug this fixes, one function over:
+ * F312.21's tab seeding reloads the page and waited a FIXED 2500ms, so a run
+ * began with 56 rows on screen and ended with 133. A fix that lives in one call
+ * site is a fix the next call site does not get.
+ */
+async function waitForSettled(page: Page, selector: string | null, rowAttr: string): Promise<void> {
+  let last = '';
+  let stable = 0;
+  const deadline = Date.now() + 25_000;
+  while (Date.now() < deadline) {
+    const sig = (await page
+      .evaluate(
+        ([s2, ra]) => {
+          const el = s2 ? document.querySelector(s2 as string) : null;
+          if (!el) return '';
+          const e = el as HTMLElement;
+          return `${e.scrollHeight}:${e.querySelectorAll('[' + ra + ']').length}`;
+        },
+        [selector, rowAttr] as const,
+      )
+      .catch(() => '')) as string;
+    stable = sig !== '' && sig === last ? stable + 1 : 0;
+    last = sig;
+    if (stable >= 2) break;
+    await page.waitForTimeout(700);
+  }
+}
+
+export type SeedResult = { ok: true; edge: string; tabs: string[] } | { ok: false; reason: string } | null;
+
+export interface RecordOptions extends ProbeConfig, FindOptions {
+  url: string;
+  /**
+   * F312.10 — SCROLL UP BY THIS MANY PIXELS BEFORE WATCHING.
+   *
+   * The experiment was measuring the wrong situation. Parked at the live bottom,
+   * the browser keeps you pinned there as content arrives — every "move" tracks
+   * the growing maximum and nothing is wrong. His complaint is the opposite: he
+   * has scrolled UP to read, and THEN it moves. A recording that never leaves the
+   * bottom cannot show it.
+   */
+  scrollUpPx?: number;
+  /**
+   * F312.21 — SEED THE OPEN TABS before measuring a tab switch.
+   *
+   * Lens runs a fresh browser profile, so the chat's tab strip is empty and there
+   * is nothing to switch BETWEEN. Measured: a three-step switch sequence reported
+   * `pressed: false` on its first press, and the frame confirmed the picker was
+   * not open — the experiment had simply never happened.
+   *
+   * The edge is NOT guessed. It is read back from the tab the app itself wrote
+   * once it had picked a session, so the seeded tabs carry the same edge the
+   * running app uses. A guessed edge produces a tab that renders and cannot be
+   * switched to, which is worse than no tab at all: it looks like the scenario ran.
+   */
+  seedTabs?: { session: string; channel?: string; label?: string }[];
+  /** How long to sit and watch. */
+  seconds: number;
+  viewport?: { width: number; height: number };
+  engine?: 'chromium' | 'webkit' | 'firefox';
+  locale?: string;
+  timezone?: string;
+  reducedMotion?: 'reduce' | 'no-preference';
+  prepareContext?: (context: BrowserContext) => Promise<void>;
+  /** Optional — the point of this verb is that it works with none. Each entry is
+   *  run before the watch begins, and each stamps the driver clock so its own
+   *  scrolling is never reported as a defect. */
+  before?: (page: Page) => Promise<void>;
+  /** F312.5 — run WHILE the probe watches. This is how the typing case is
+   *  reproduced: a browser sitting still cannot show a defect that only appears
+   *  when the caret is in a field. Its keystrokes deliberately do NOT stamp the
+   *  driver clock — typing is not a request to move the view, so a move during it
+   *  must stay reportable. */
+  during?: (page: Page, seconds: number) => Promise<void>;
+}
+
+export interface RecordResult {
+  video: Buffer | null;
+  durationMs: number;
+  /** The scroller the probe actually watched — never assumed, always reported, so
+   *  "no findings" can be told apart from "watched the wrong element". */
+  watched: string | null;
+  samples: MotionSample[];
+  findings: MotionFinding[];
+  /** F312.12 — the page's own record of who moved the view, on the probe's clock.
+   *  Empty on a surface that keeps no ledger. */
+  ledger: ScrollNote[] | null;
+  /** F312.16 — marker → ms after probe start when it first appeared on screen. */
+  markers: Record<string, number>;
+  /** UTC epoch ms at which the probe started, so a marker's arrival on the probe
+   *  clock can be turned back into a wall-clock time and compared with when the
+   *  message was actually sent. Without it `landed at 4213ms` cannot be paired
+   *  with anything. */
+  probeStartedAt: number;
+  /**
+   * F312.18 — did the probe DEMONSTRABLY see a movement it was given on purpose?
+   *
+   * False means the run proves nothing: zero findings from a blind camera and
+   * zero from a fixed product are the same number, and only this tells them
+   * apart. Never inferred from the absence of findings — that is the very
+   * confusion it exists to remove.
+   */
+  detectorAlive: boolean;
+  /** F312.21 — the outcome of seeding the open-tab set, or null when not asked. */
+  seed: SeedResult;
+  /** F312.18 — the working behind `detectorAlive`, so a false can be attributed
+   *  instead of merely believed. */
+  selfTest: { from: number; sampledBefore3s: number; maxDeviation: number | null };
+  probeError: string | null;
+}
+
+/**
+ * Open `url`, attach the motion probe, record for `seconds`, and return the video
+ * with a measured timeline.
+ *
+ * A MISSING RECORDING NEVER FAILS THE RUN (F255.5's rule, inherited on purpose):
+ * the probe data is the primary result, and it survives a video that did not
+ * finalise.
+ */
+export async function recordSurface(opts: RecordOptions): Promise<RecordResult> {
+  const videoDir = await mkdtemp(join(tmpdir(), 'lens-record-'));
+  let videoPage: Page | null = null;
+  const startedAt = Date.now();
+  let samples: MotionSample[] = [];
+  let ledger: ScrollNote[] | null = null;
+  let markers: Record<string, number> = {};
+  let probeStartedAt = 0;
+  let selfTestFrom = -1;
+  let seedResult: SeedResult = null;
+  let probeError: string | null = null;
+  let watched: string | null = null;
+
+  try {
+    await withPage(
+      {
+        recordVideoDir: videoDir,
+        ...(opts.viewport ? { viewport: opts.viewport } : {}),
+        ...(opts.engine ? { engine: opts.engine } : {}),
+        ...(opts.locale ? { locale: opts.locale } : {}),
+        ...(opts.timezone ? { timezone: opts.timezone } : {}),
+        ...(opts.reducedMotion ? { reducedMotion: opts.reducedMotion } : {}),
+        ...(opts.prepareContext ? { prepareContext: opts.prepareContext } : {}),
+      },
+      async (page) => {
+        videoPage = page;
+        await page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        // Let the surface settle BEFORE the probe starts, or the first-load
+        // landing — which is not a defect — becomes finding number one.
+        //
+        // F312.17 — WAIT FOR IT TO STOP GROWING, don't guess a number. Measured 6
+        // Sept: a run began with 6 rows on screen and ended with 131, so the
+        // reading position was taken against a transcript that had not loaded and
+        // the whole recording measured the load instead of the defect. A fixed
+        // 2500ms is a guess about someone else's network; two consecutive equal
+        // heights is the actual question.
+        await page.waitForTimeout(1200);
+        await waitForSettled(page, opts.selector ?? null, opts.rowAttr ?? 'data-ev-uuid');
+
+        // F312.21 — seed the open-tab set, then reload so the strip renders it.
+        // The edge comes from the tab the APP wrote after it picked a session;
+        // guessing it would produce a tab that renders and cannot be switched to,
+        // which looks like the scenario ran.
+        if (opts.seedTabs && opts.seedTabs.length > 0) {
+          const seeded = await page
+            .evaluate((want) => {
+              const KEY = 'cardmem.chat.tabs';
+              let cur: { edge?: string; session?: string; channel?: string; label?: string }[] = [];
+              try {
+                const raw = localStorage.getItem(KEY);
+                if (raw) cur = JSON.parse(raw);
+              } catch {
+                cur = [];
+              }
+              const edge = Array.isArray(cur) && cur[0]?.edge ? String(cur[0].edge) : null;
+              if (!edge) return { ok: false, reason: 'no edge — the app has not picked a session yet' };
+              const have = new Set((cur || []).map((t) => String(t.channel ?? t.session)));
+              for (const w of want as { session: string; channel?: string; label?: string }[]) {
+                const channel = w.channel ?? w.session;
+                if (have.has(channel)) continue;
+                cur.push({ edge, session: w.session, channel, label: w.label ?? channel });
+              }
+              localStorage.setItem(KEY, JSON.stringify(cur));
+              return { ok: true, edge, tabs: cur.map((t) => String(t.channel ?? t.session)) };
+            }, opts.seedTabs)
+            .catch(() => ({ ok: false, reason: 'evaluate failed' }));
+          seedResult = seeded as SeedResult;
+          if ((seeded as { ok?: boolean }).ok) {
+            await page.reload({ waitUntil: 'domcontentloaded', timeout: 30_000 });
+            await page.waitForTimeout(1200);
+            await waitForSettled(page, opts.selector ?? null, opts.rowAttr ?? 'data-ev-uuid');
+          }
+        }
+
+        // F312.10 — take up the reading position BEFORE the probe starts, so the
+        // deliberate scroll is not itself the first finding.
+        if (opts.scrollUpPx && opts.scrollUpPx > 0) {
+          await scrollUpBy(page, opts.selector ?? null, opts.scrollUpPx);
+          await page.waitForTimeout(1200);
+        }
+
+        if (opts.before) {
+          await opts.before(page);
+          // Whatever that did was OURS. Stamp it so the grace window covers it.
+          await page.evaluate('window.__lensDriverActed && window.__lensDriverActed()').catch(() => {});
+        }
+
+        const started = await page.evaluate(
+          probeSource({
+            ...(opts.selector ? { selector: opts.selector } : {}),
+            ...(opts.intervalMs ? { intervalMs: opts.intervalMs } : {}),
+            ...(opts.rowAttr ? { rowAttr: opts.rowAttr } : {}),
+          }),
+        );
+        probeStartedAt = Date.now();
+        if (started === 'no-scroller') probeError = 'no scrollable element found';
+
+        // F312.18 — DOES THE DETECTOR STILL WORK? A deliberate, stamped nudge a
+        // moment after the probe starts, whose only job is to prove the camera is
+        // alive. Raised by the trail session from two failures of exactly this
+        // shape in their own day: a coverage metric that only counted the chunks
+        // that EXISTED, and an indexing job whose `WHERE enabled = 1` selected
+        // zero rows — so it neither failed nor reported. Both read as success.
+        //
+        // The same hole was open here. `exercised` answers "did the surface
+        // change"; nothing answered "would this probe have SEEN a change". A run
+        // whose probe never attached, whose selector matched a static element, or
+        // whose sampling died reports zero findings — identical to a fixed
+        // product. The nudge is classified `driver`, so it is never a finding;
+        // its absence from the samples is the alarm.
+        await page.waitForTimeout(600);
+        const before = (await page
+          .evaluate((s2) => {
+            const el = s2 ? document.querySelector(s2 as string) : null;
+            return el ? (el as HTMLElement).scrollTop : -1;
+          }, opts.selector ?? null)
+          .catch(() => -1)) as number;
+        await scrollUpBy(page, opts.selector ?? null, 140);
+        await page.waitForTimeout(250);
+        await scrollUpBy(page, opts.selector ?? null, -140);
+        await page.waitForTimeout(250);
+        selfTestFrom = before;
+
+        const secs = Math.max(1, opts.seconds);
+        if (opts.during) await opts.during(page, secs);
+        else await page.waitForTimeout(secs * 1000);
+
+        const read = (await page.evaluate(PROBE_READ)) as {
+          error?: string | null;
+          selector?: string | null;
+          samples?: MotionSample[];
+          ledger?: ScrollNote[] | null;
+          markers?: Record<string, number>;
+        };
+        samples = read?.samples ?? [];
+        ledger = read?.ledger ?? null;
+        markers = read?.markers ?? {};
+        watched = read?.selector ?? null;
+        if (read?.error) probeError = read.error;
+      },
+    );
+  } finally {
+    // Playwright only finalises the .webm when the context closes, so this read
+    // has to happen AFTER withPage resolves.
+  }
+
+  let video: Buffer | null = null;
+  try {
+    // `saveAs`, NOT `path()`. Measured: path() resolves immediately and the file
+    // is still 0 bytes — Playwright flushes the webm asynchronously after the
+    // context closes, so reading the path is a race that loses quietly. saveAs
+    // WAITS for the write, which is the difference between a video and an empty
+    // file that ffmpeg then rejects with an unhelpful exit code.
+    const out = join(videoDir, 'run.webm');
+    const v = (videoPage as Page | null)?.video();
+    if (v) {
+      await v.saveAs(out);
+      video = await readFile(out);
+    }
+  } catch {
+    video = null; // a missing recording must never fail an otherwise-good run
+  } finally {
+    await rm(videoDir, { recursive: true, force: true }).catch(() => {});
+  }
+
+  const findings = rankFindings(
+    findUncausedMoves(samples, {
+      ...(opts.minDeltaPx != null ? { minDeltaPx: opts.minDeltaPx } : {}),
+      ...(opts.inputGraceMs != null ? { inputGraceMs: opts.inputGraceMs } : {}),
+      ...(opts.driverGraceMs != null ? { driverGraceMs: opts.driverGraceMs } : {}),
+    }),
+  );
+
+  return {
+    video,
+    durationMs: Date.now() - startedAt,
+    watched,
+    samples,
+    findings,
+    ledger,
+    markers,
+    probeStartedAt,
+    // The nudge moved the position by 140px and back within the first second, so
+    // a probe that was watching MUST have sampled something other than its
+    // starting point. Judged on the samples, not on whether the scroll call
+    // resolved — a resolved call proves the message was sent, not that anyone
+    // was listening.
+    seed: seedResult,
+    detectorAlive:
+      selfTestFrom >= 0 && samples.some((x) => x.t < 3000 && Math.abs(x.top - selfTestFrom) > 40),
+    // F312.18 — WHY it says what it says. A bare false is the same shape as the
+    // silence it exists to detect: it could mean the probe was blind, or that the
+    // nudge never moved anything, or that the position could not be read at all.
+    // Measured twice today, and I could not tell those apart from the field alone
+    // — so the working is reported beside the verdict.
+    selfTest: {
+      from: selfTestFrom,
+      sampledBefore3s: samples.filter((x) => x.t < 3000).length,
+      maxDeviation:
+        selfTestFrom < 0
+          ? null
+          : samples
+              .filter((x) => x.t < 3000)
+              .reduce((m, x) => Math.max(m, Math.abs(x.top - selfTestFrom)), 0),
+    },
+    probeError,
+  };
+}

package/src/sandbox.ts

@@ -0,0 +1,22 @@
+// lens F001.5 — the daemon's sandbox, INJECTED, never copied.
+//
+// resolveSandboxedPath is the cardmem daemon's security boundary (it also guards
+// non-Lens routes there). A second copy inside this package would be two
+// security checks that can drift apart, so the package holds no implementation:
+// the daemon hands its own function in through LensDeps when it mounts the
+// router. Until then every call refuses — fail closed, never "allow".
+
+export type SandboxResolver = (path: string, sandboxRoots: string[]) => string;
+
+let resolver: SandboxResolver | null = null;
+
+export function setSandboxResolver(fn: SandboxResolver): void {
+  resolver = fn;
+}
+
+export function resolveSandboxedPath(path: string, sandboxRoots: string[]): string {
+  if (!resolver) {
+    throw new Error('lens-daemon: no sandbox resolver installed — the daemon must pass resolveSandboxedPath in LensDeps');
+  }
+  return resolver(path, sandboxRoots);
+}