@broberg/lens-daemon 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",
@@ -15,8 +15,8 @@
     "sharp": "^0.33.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-engine": "0.13.1",
-    "@broberg/lens-svg": "0.1.0"
+    "@broberg/lens-svg": "0.1.0",
+    "@broberg/lens-engine": "0.13.1"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/artifact-uploads.ts

@@ -168,7 +168,7 @@ export async function drainUploads(
     idle_reason: reason,
   });
 
-  if (!cloud) return empty('not signed in to cardmem — run `cardmem login`; nothing was uploaded');
+  if (!cloud) return empty('not signed in to cardmem — this daemon has no cloud key (the cardmem session logs it in via the daemon\'s POST /login); nothing was uploaded');
 
   const batch = Math.max(1, Math.min(opts.batch ?? 25, 200));
   const now = opts.now?.() ?? Date.now();

package/src/browser.ts

@@ -10,6 +10,7 @@
 // auth (F074.4) and concurrent captures never bleed into each other. The
 // context + page are always closed in a finally, even on capture error.
 
+import { claimProfile, profileDir } from './profiles.ts';
 import {
   chromium,
   webkit,
@@ -226,7 +227,7 @@ export interface WithPageOptions {
    *
    *  This is a SECOND launch path, not a flag on the warm browser: extensions
    *  need launchPersistentContext with a real user-data dir on disk. */
-  extension?: { path: string };
+  extension?: { path: string; /** F009.132 — a kept profile instead of a temp dir. */ profile?: string };
 }
 
 /** Exported for test: F074.57's central promise to everyone who did NOT ask for
@@ -319,7 +320,7 @@ export interface LoadedExtension {
  *  Chromium binary does, in the new headless mode. That distinction is the whole
  *  reason this can run on a headless host (and therefore on Cloud Lens) instead
  *  of needing a screen. */
-const EXTENSION_CHANNEL = 'chromium';
+export const EXTENSION_CHANNEL = 'chromium';
 const EXTENSION_LAUNCH_TIMEOUT_MS = 30_000;
 const EXTENSION_LAUNCH_ATTEMPTS = 2;
 
@@ -333,8 +334,10 @@ async function launchWithExtension(
   let userDataDir = '';
   let context: BrowserContext | null = null;
   let lastLaunchError = '';
+  const profile = opts.extension?.profile;
   for (let attempt = 1; attempt <= EXTENSION_LAUNCH_ATTEMPTS && !context; attempt++) {
-    userDataDir = await mkdtemp(join(tmpdir(), 'lens-ext-'));
+    // F009.132 — a named profile is KEPT: that is where a site's login lives.
+    userDataDir = profile ? profileDir(profile) : await mkdtemp(join(tmpdir(), 'lens-ext-'));
     try {
       context = await chromium.launchPersistentContext(userDataDir, {
         ...contextOptions(opts),
@@ -350,7 +353,7 @@ async function launchWithExtension(
       });
     } catch (err) {
       lastLaunchError = err instanceof Error ? err.message.split('\n')[0]! : String(err);
-      await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+      if (!profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
     }
   }
   if (!context) {
@@ -369,7 +372,7 @@ async function launchWithExtension(
   const bg = worker?.url() ?? context.backgroundPages()[0]?.url();
   if (!bg) {
     await context.close().catch(() => {});
-    await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+    if (!profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
     throw new Error(
       `extension at ${extPath} loaded no service worker or background page within 15s — ` +
         'its id cannot be resolved, so nothing can be captured from it. Check that the path is ' +
@@ -398,7 +401,15 @@ export async function withPage<T>(
           'Drop the engine option or pass engine:"chromium".',
       );
     }
-    const { context, extension, userDataDir } = await launchWithExtension(opts, opts.extension.path);
+    const release = opts.extension.profile ? claimProfile(opts.extension.profile) : () => {};
+    let launched: Awaited<ReturnType<typeof launchWithExtension>>;
+    try {
+      launched = await launchWithExtension(opts, opts.extension.path);
+    } catch (err) {
+      release();
+      throw err;
+    }
+    const { context, extension, userDataDir } = launched;
     try {
       await context.addInitScript(READINESS_INIT_SCRIPT);
       if (opts.prepareContext) await opts.prepareContext(context);
@@ -414,8 +425,9 @@ export async function withPage<T>(
     } finally {
       await withDeadline(context.close(), 5_000, 'extension context close').catch(() => {});
       // The user-data dir is ours and nobody else's; leaving it leaks a real
-      // directory per capture.
-      await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+      // directory per capture. A named profile is the exception: it IS the login.
+      if (!opts.extension.profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+      release();
     }
   }
 

package/src/capture-session.ts

@@ -18,6 +18,8 @@
 // are confined to ~/.lens/state so a bad state_path can't clobber an arbitrary
 // file. The endpoint is loopback-only (127.0.0.1) behind the daemon's auth.
 
+import { claimProfile, profileDir } from './profiles.ts';
+import { EXTENSION_CHANNEL } from './browser.ts';
 import { chromium, type Browser, type BrowserContext, type Page } from 'playwright';
 import { z } from 'zod';
 import { mkdirSync, existsSync, copyFileSync, writeFileSync } from 'node:fs';
@@ -57,6 +59,18 @@ export interface FinishableSession {
  *  disable the AutomationControlled blink feature. --disable-gpu = software compositing
  *  (a launchd-context window otherwise paints black). Falls back to bundled chromium
  *  (still de-flagged) if real Chrome isn't installed. */
+/** F009.132 — a login for a kept profile must happen in the SAME browser build
+ *  the extension runs use (Google binds its session to the browser), visibly, so
+ *  a human can type the password and 2FA. Exported so the build is asserted. */
+export function profileLaunchOptions() {
+  return {
+    headless: false,
+    channel: EXTENSION_CHANNEL,
+    ignoreDefaultArgs: ['--enable-automation'],
+    args: ['--disable-blink-features=AutomationControlled'],
+  };
+}
+
 async function launchHeaded(): Promise<{ browser: Browser; appName: string }> {
   const opts = {
     headless: false,
@@ -360,6 +374,8 @@ export async function startCaptureSession(input: {
   password?: string;
   /** F240.7 — a storageState file to LOAD so the browser opens already logged in. */
   loadStatePath?: string;
+  /** F009.132 — log in INSIDE the kept profile ~/.lens/profiles/<name>. */
+  profile?: string;
 }): Promise<{
   sessionId: string;
   url: string;
@@ -384,17 +400,39 @@ export async function startCaptureSession(input: {
   mkdirSync(dirname(statePath), { recursive: true });
   const loadStatePath = input.loadStatePath ? validateLoadStatePath(input.loadStatePath) : undefined;
 
-  const { browser, appName } = await launchHeaded();
-  // Load an existing storageState so the browser opens ALREADY authenticated
-  // (skip the whole login; drive only the agreement + step-up 2FA). F240.7.
-  const context = await browser.newContext(loadStatePath ? { storageState: loadStatePath } : undefined);
+  let browser: Browser;
+  let appName: string;
+  let context: BrowserContext;
+  let releaseProfile: () => void = () => {};
+  if (input.profile) {
+    // F009.132 — the login lands in the profile itself; the state file written at
+    // finish is a copy for runs that do not use the profile.
+    const dir = profileDir(input.profile);
+    releaseProfile = claimProfile(input.profile);
+    try {
+      context = await chromium.launchPersistentContext(dir, profileLaunchOptions());
+    } catch (err) {
+      releaseProfile();
+      throw err;
+    }
+    const release = releaseProfile;
+    browser = { close: async () => { try { await context.close(); } finally { release(); } } } as unknown as Browser;
+    // Measured 16 Oct: the channel build runs as this app, not "Chromium" — activating
+    // "Chromium" failed and the window stayed behind the others.
+    appName = 'Google Chrome for Testing';
+  } else {
+    ({ browser, appName } = await launchHeaded());
+    // Load an existing storageState so the browser opens ALREADY authenticated
+    // (skip the whole login; drive only the agreement + step-up 2FA). F240.7.
+    context = await browser.newContext(loadStatePath ? { storageState: loadStatePath } : undefined);
+  }
   // Mask the most-checked automation signal before any page script runs — pairs
   // with the de-flagged launch so Google's "browser may not be secure" bot-check
   // treats this like a real user's Chrome.
   await context.addInitScript(() => {
     Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
   });
-  const page = await context.newPage();
+  const page = context.pages()[0] ?? (await context.newPage());
   // Best-effort nav — a slow login portal shouldn't fail start; the human is
   // driving from here and can navigate themselves if the first load stalls.
   await page.goto(input.url, { waitUntil: 'domcontentloaded', timeout: 60_000 }).catch(() => {});

package/src/daemon-routes.ts

@@ -9,6 +9,8 @@
 // and `err instanceof SandboxError` became isSandboxError(err), because the
 // sandbox (and its error class) stays the daemon's — see sandbox.ts.
 
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 import type { Hono } from 'hono';
 import { scrapeArticle } from './scrape.ts';
 import { startCaptureSession, finishCaptureSession, cancelCaptureSession, execCaptureSession, parseExecBody } from './capture-session.ts';
@@ -107,16 +109,21 @@ export function registerDaemonRoutes(r: Hono, deps: LensDeps): void {
       email?: string;
       password?: string;
       load_state_path?: string;
+      profile?: string;
     };
     if (!body.url) return c.json({ ok: false, error: 'url required' }, 400);
-    if (!body.state_path) return c.json({ ok: false, error: 'state_path required' }, 400);
+    // F009.132 — with a profile the login lives in the profile; the state file is
+    // an optional copy and defaults next to the other states.
+    const statePath = body.state_path ?? (typeof body.profile === 'string' ? join(homedir(), '.lens', 'state', `profile-${body.profile}.json`) : undefined);
+    if (!statePath) return c.json({ ok: false, error: 'state_path required (or pass profile)' }, 400);
     try {
       const r = await startCaptureSession({
         url: body.url,
-        statePath: body.state_path,
+        statePath,
         email: body.email,
         password: body.password,
         loadStatePath: body.load_state_path,
+        ...(typeof body.profile === 'string' ? { profile: body.profile } : {}),
       });
       // F240.10 — pass the window verdict through UNCHANGED. A remote caller is the
       // one who has to tell a human "the browser is open"; it must see what the

package/src/flow.ts

@@ -199,6 +199,9 @@ export interface FlowExtension {
    *  token never passes through the calling agent. Wins over storage_local on the
    *  same key. */
   storage_local_mint?: StorageLocalMint;
+  /** F009.132 — run in the kept browser profile ~/.lens/profiles/<name> (where a
+   *  site's login lives) instead of a fresh temp profile. */
+  profile?: string;
 }
 export interface StorageLocalMint {
   key: string;
@@ -518,8 +521,8 @@ 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) => !['path', 'grant_host_access', 'storage_local', 'storage_local_mint'].includes(k))) {
-      throw new Error('flow.extension must be {path: "<unpacked build dir>", grant_host_access?: boolean, storage_local?: {…}, storage_local_mint?: {…}}');
+    if (!keys || typeof e.path !== 'string' || !e.path || keys.some((k) => !['path', 'grant_host_access', 'storage_local', 'storage_local_mint', 'profile'].includes(k))) {
+      throw new Error('flow.extension must be {path: "<unpacked build dir>", grant_host_access?: boolean, storage_local?: {…}, storage_local_mint?: {…}, profile?: "<name>"}');
     }
     if (e.grant_host_access !== undefined && typeof e.grant_host_access !== 'boolean') {
       throw new Error('flow.extension.grant_host_access must be a boolean');
@@ -529,11 +532,15 @@ export function parseFlow(input: unknown): Flow {
       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');
     }
     const mint = e.storage_local_mint === undefined ? undefined : parseStorageLocalMint(e.storage_local_mint);
+    if (e.profile !== undefined && (typeof e.profile !== 'string' || !/^[a-z0-9][a-z0-9-]{0,39}$/.test(e.profile))) {
+      throw new Error('flow.extension.profile must be 1-40 characters of a-z, 0-9 and dash, starting with a letter or digit');
+    }
     extension = {
       path: e.path,
       ...(e.grant_host_access === true ? { grant_host_access: true } : {}),
       ...(sl !== undefined ? { storage_local: sl as Record<string, unknown> } : {}),
       ...(mint ? { storage_local_mint: mint } : {}),
+      ...(typeof e.profile === 'string' ? { profile: e.profile } : {}),
     };
   }
   persistTarget(f.auth as AuthConfig | undefined); // F009.131 — refuse a persist that cannot be honoured
@@ -3149,7 +3156,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         timezone: opts.timezone,
         reducedMotion: opts.reducedMotion,
         ...(videoDir ? { recordVideoDir: videoDir } : {}),
-        ...(prepared ? { extension: { path: prepared.dir } } : {}),
+        ...(prepared ? { extension: { path: prepared.dir, ...(flow.extension?.profile ? { profile: flow.extension.profile } : {}) } } : {}),
       },
       async (page, context, ext) => {
         videoPage = page;

package/src/profiles.ts

@@ -0,0 +1,31 @@
+// F009.132 — a fixed browser profile per site. Google binds its session to the
+// browser that holds it, so a login only survives if it happens in, and is reused
+// from, ONE profile of ONE browser build. The profile lives on the daemon host.
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// LENS_PROFILE_ROOT exists for tests, so a suite never writes into the real ~/.lens.
+const profileRoot = () => process.env.LENS_PROFILE_ROOT || join(homedir(), '.lens', 'profiles');
+const NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/** The profile's user-data dir. The name is checked because it becomes a path. */
+export function profileDir(name: string): string {
+  if (typeof name !== 'string' || !NAME.test(name)) {
+    throw new Error(`profile must be 1-40 characters of a-z, 0-9 and dash, starting with a letter or digit (got ${JSON.stringify(name)})`);
+  }
+  const dir = join(profileRoot(), name);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+// One Chromium per profile at a time: a second one on the same dir either fails
+// on Chromium's own lock with an unhelpful message or corrupts it. Refused here,
+// by name, before a browser starts.
+const inUse = new Set<string>();
+
+export function claimProfile(name: string): () => void {
+  if (inUse.has(name)) throw new Error(`browser profile "${name}" is already in use by another run — wait for it to finish`);
+  inUse.add(name);
+  return () => inUse.delete(name);
+}

package/src/service.ts

@@ -1190,7 +1190,7 @@ export async function promoteEvidence(
   const cloud = deps.cloud?.();
   if (!cloud) {
     throw new Error(
-      'not signed in to cardmem — promoting evidence needs the daemon\'s cloud key (run `cardmem login`). Nothing was copied.',
+      'not signed in to cardmem — promoting evidence needs the daemon\'s cloud key, and this daemon has none (the cardmem session logs it in via the daemon\'s POST /login). Nothing was copied.',
     );
   }