@monoes/monobrowse 1.0.2 → 1.0.4

package/src/browser/record.ts

@@ -15,8 +15,20 @@ export interface RecordOptions {
 export interface RecordingState {
   frames: string[];
   offScreencast: (() => void) | null;
+  totalBytes: number;
+  autoStopped: boolean;
 }
 
+// Unlike har.ts's MAX_REQUESTS_PER_SESSION cap on the analogous network-request
+// buffer, the screencast frame buffer previously had no size or count cap at
+// all — recording for even a few minutes at normal frame rates can accumulate
+// hundreds of MB of base64-encoded JPEG data in memory, and stopRecording()'s
+// single JSON.stringify() of the whole frame array can exceed V8's max string
+// length and crash the process. Cap total accumulated base64 bytes (simpler to
+// check per-push than re-measuring the whole array) and auto-stop recording
+// once the budget is exhausted.
+const MAX_SCREENCAST_BYTES = 200 * 1024 * 1024; // ~200 MB of accumulated base64 frame data
+
 const _sessions = new Map<string, RecordingState>();
 
 export async function startRecording(
@@ -24,17 +36,38 @@ export async function startRecording(
   sessionId: string,
   options: RecordOptions = {}
 ): Promise<void> {
-  if (_sessions.has(sessionId)) {
+  const existing = _sessions.get(sessionId);
+  if (existing && !existing.autoStopped) {
     throw new Error('Recording already in progress for this session');
   }
+  if (existing) {
+    // Previous recording hit the buffer cap and auto-stopped but was never
+    // explicitly saved via stopRecording() — drop it so a fresh recording
+    // can start (its frames are lost; the auto-stop log already warned the
+    // caller to save via "record stop" before starting a new recording).
+    _sessions.delete(sessionId);
+  }
 
-  const state: RecordingState = { frames: [], offScreencast: null };
+  const state: RecordingState = { frames: [], offScreencast: null, totalBytes: 0, autoStopped: false };
   _sessions.set(sessionId, state);
 
   state.offScreencast = client.on('Page.screencastFrame', async (params, sid) => {
     if (sid !== sessionId) return;
     const { data, sessionId: frameSessionId } = params as { data: string; sessionId: number };
-    state.frames.push(data);
+    if (!state.autoStopped) {
+      state.frames.push(data);
+      state.totalBytes += data.length;
+      if (state.totalBytes >= MAX_SCREENCAST_BYTES) {
+        state.autoStopped = true;
+        state.offScreencast?.();
+        // eslint-disable-next-line no-console
+        console.error(
+          `[monobrowse] Screen recording auto-stopped: reached ${Math.round(MAX_SCREENCAST_BYTES / (1024 * 1024))}MB ` +
+          `of buffered frame data (${state.frames.length} frames). Call "record stop" to save what was captured.`
+        );
+        await client.send('Page.stopScreencast', {}, sessionId).catch(() => {});
+      }
+    }
     await client.send('Page.screencastFrameAck', { sessionId: frameSessionId }, sessionId).catch(() => {});
   });
 
@@ -62,7 +95,11 @@ export async function stopRecording(
   if (!state) throw new Error('No active recording for this session');
 
   try {
-    await client.send('Page.stopScreencast', {}, sessionId);
+    // If auto-stop already sent Page.stopScreencast and unsubscribed, don't
+    // send it again — Chrome errors on stopping an already-stopped screencast.
+    if (!state.autoStopped) {
+      await client.send('Page.stopScreencast', {}, sessionId);
+    }
   } finally {
     state.offScreencast?.();
     _sessions.delete(sessionId);
@@ -73,9 +110,9 @@ export async function stopRecording(
   return path;
 }
 
-export function getRecordingStatus(sessionId: string): { recording: boolean; frames: number } {
+export function getRecordingStatus(sessionId: string): { recording: boolean; frames: number; autoStopped: boolean } {
   const state = _sessions.get(sessionId);
-  return { recording: !!state, frames: state?.frames.length ?? 0 };
+  return { recording: !!state && !state.autoStopped, frames: state?.frames.length ?? 0, autoStopped: state?.autoStopped ?? false };
 }
 
 export async function saveFrameAsPng(

package/src/browser/ref-cache.ts

@@ -0,0 +1,141 @@
+/**
+ * AX-tree ref cache persistence.
+ *
+ * `snapshot` and `find` are separate CLI invocations — each starts a fresh
+ * node process, so the in-memory ElementRef Map built by captureSnapshot()
+ * does not survive between them. This module persists a lightweight lookup
+ * index (ref -> role/name/nodeId/backendDOMNodeId, i.e. everything CDP needs
+ * to re-target an element) to disk so a later process can rehydrate it.
+ *
+ * The full AX-tree text/dump is intentionally NOT persisted — only the
+ * per-ref index, to keep the file small.
+ */
+import { readFile, writeFile, mkdir, rm } from 'fs/promises';
+import { join } from 'path';
+import type { ElementRef } from './types.js';
+
+const CACHE_DIR = join(process.cwd(), '.monomind', 'monobrowse');
+const CACHE_FILE = join(CACHE_DIR, 'ax-snapshot.json');
+const PORT_FILE = join(CACHE_DIR, 'active-port.json');
+
+/** Snapshot older than this is flagged as possibly stale (page may have changed). */
+export const REF_CACHE_STALE_MS = 30_000;
+
+interface RefCacheFile {
+  targetId: string;
+  url: string;
+  savedAt: number;
+  refs: ElementRef[];
+}
+
+export interface RefCacheEntry {
+  refs: Map<string, ElementRef>;
+  url: string;
+  savedAt: number;
+  ageMs: number;
+  stale: boolean;
+}
+
+/** Persist the current ref index for a target so a later CLI process can read it back. */
+export async function saveRefCache(
+  targetId: string,
+  url: string,
+  refs: Map<string, ElementRef>
+): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    const data: RefCacheFile = {
+      targetId,
+      url,
+      savedAt: Date.now(),
+      refs: [...refs.values()],
+    };
+    await writeFile(CACHE_FILE, JSON.stringify(data));
+  } catch {
+    // Best-effort — persistence failure just means cross-process rehydration
+    // won't work; in-process (same run) behavior is unaffected.
+  }
+}
+
+/**
+ * Load the persisted ref index, scoped to the given targetId (a cache from a
+ * different tab/target is ignored). Returns null if no usable cache exists —
+ * callers fall back to an empty in-memory Map, matching prior behavior.
+ */
+export async function loadRefCache(targetId: string): Promise<RefCacheEntry | null> {
+  try {
+    const raw = await readFile(CACHE_FILE, 'utf8');
+    const data: RefCacheFile = JSON.parse(raw);
+    if (!data || !Array.isArray(data.refs) || data.targetId !== targetId) return null;
+
+    const refs = new Map<string, ElementRef>();
+    for (const ref of data.refs) {
+      if (ref && typeof ref.ref === 'string') refs.set(ref.ref, ref);
+    }
+    if (refs.size === 0) return null;
+
+    const ageMs = Date.now() - data.savedAt;
+    return { refs, url: data.url, savedAt: data.savedAt, ageMs, stale: ageMs > REF_CACHE_STALE_MS };
+  } catch {
+    return null;
+  }
+}
+
+/** Drop the persisted ref index — call whenever refs are invalidated (navigation, tab switch, close). */
+export async function clearRefCache(): Promise<void> {
+  try {
+    await rm(CACHE_FILE, { force: true });
+  } catch {
+    // Nothing to clear, or not writable — non-fatal.
+  }
+}
+
+/**
+ * Persist the "active" CDP port so a later CLI invocation (each command is a
+ * fresh process — see module header) can find the browser a prior `open
+ * --port N` attached to, instead of every subsequent command silently
+ * falling back to the hardcoded default port and launching/attaching to a
+ * second, unrelated Chrome instance.
+ */
+export async function saveActivePort(port: number, opts?: { launched?: boolean }): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    // `launched` records provenance: true = monobrowse spawned this Chrome
+    // (safe to Browser.close later); false = attached to a browser someone
+    // else owns (must never be killed). Absent (old files) reads as launched
+    // — matches pre-flag behavior where every persisted port came from open.
+    await writeFile(PORT_FILE, JSON.stringify({ port, launched: opts?.launched !== false, savedAt: Date.now() }));
+  } catch {
+    // Best-effort — persistence failure just means the next process falls
+    // back to the hardcoded default port, matching prior behavior.
+  }
+}
+
+/** Forget the persisted active port (session closed) so later invocations
+ *  fall back to the default instead of chasing a dead endpoint. */
+export async function clearActivePort(): Promise<void> {
+  try {
+    await rm(PORT_FILE, { force: true });
+  } catch {
+    // Best-effort — a stale port file only costs one failed probe later.
+  }
+}
+
+/** Load the persisted active port, or null if none was ever saved / it's unreadable. */
+export async function loadActivePort(): Promise<number | null> {
+  return (await loadActivePortInfo())?.port ?? null;
+}
+
+/** Load the persisted active port with its provenance flag. */
+export async function loadActivePortInfo(): Promise<{ port: number; launched: boolean } | null> {
+  try {
+    const raw = await readFile(PORT_FILE, 'utf8');
+    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown };
+    if (typeof data.port === 'number' && Number.isInteger(data.port) && data.port >= 1024 && data.port <= 65535) {
+      return { port: data.port, launched: data.launched !== false };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/browser/session.ts

@@ -3,7 +3,13 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import type { SessionState, CdpCookie } from './types.js';
 import type { CdpClient } from './cdp.js';
-import { getCookies, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+import { getCookiesForUrls, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+
+// Session state files contain cookies/localStorage — treat as secrets:
+// owner-only read/write on the file (0600) and owner-only access on the
+// containing directory (0700) so other local users can't read session tokens.
+const SESSION_FILE_MODE = 0o600;
+const SESSION_DIR_MODE = 0o700;
 
 const SESSION_DIR = join(homedir(), '.monomind', 'browser-sessions');
 
@@ -31,15 +37,15 @@ export async function saveSession(
   title: string
 ): Promise<string> {
   validateSessionName(name);
-  await mkdir(SESSION_DIR, { recursive: true });
+  await mkdir(SESSION_DIR, { recursive: true, mode: SESSION_DIR_MODE });
 
-  const cookies = await getCookies(client, sessionId);
+  const cookies = await getCookiesForUrls(client, sessionId, [url]);
   const localStorage = await getLocalStorage(client, sessionId);
   const sessionStorage = await getSessionStorage(client, sessionId);
 
   const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
   const filePath = join(SESSION_DIR, `${name}.json`);
-  await writeFile(filePath, JSON.stringify(state, null, 2));
+  await writeFile(filePath, JSON.stringify(state, null, 2), { mode: SESSION_FILE_MODE });
   return filePath;
 }
 
@@ -79,12 +85,12 @@ export async function saveStateFile(
   title: string
 ): Promise<void> {
   validateFilePath(filePath);
-  await mkdir(dirname(filePath), { recursive: true });
-  const cookies = await getCookies(client, sessionId);
+  await mkdir(dirname(filePath), { recursive: true, mode: SESSION_DIR_MODE });
+  const cookies = await getCookiesForUrls(client, sessionId, [url]);
   const localStorage = await getLocalStorage(client, sessionId);
   const sessionStorage = await getSessionStorage(client, sessionId);
   const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
-  await writeFile(filePath, JSON.stringify(state, null, 2));
+  await writeFile(filePath, JSON.stringify(state, null, 2), { mode: SESSION_FILE_MODE });
 }
 
 export async function loadStateFile(

package/src/browser/tabs.ts

@@ -25,13 +25,42 @@ export async function activateTab(client: CdpClient, oldSessionId: string, targe
 }
 
 export async function switchToFrame(
-  _client: CdpClient,
-  _sessionId: string,
-  _frameSelector: string
+  client: CdpClient,
+  sessionId: string,
+  frameSelector: string
 ): Promise<string | null> {
-  throw new Error(
-    'switchToFrame is not yet implemented. ' +
-    'For same-origin frames, CDP commands already apply to the whole page. ' +
-    'For cross-origin (OOPIF) frames, call Target.attachToTarget with the frame target ID.'
+  const { result } = await client.send<{ result: { result: { value: string | null } } }>(
+    'Runtime.evaluate',
+    {
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(frameSelector)});
+        if (!el || el.tagName !== 'IFRAME') return null;
+        return el.src || null;
+      })()`,
+      returnByValue: true,
+    },
+    sessionId
   );
+  const frameSrc = result?.result?.value ?? null;
+
+  const { frameTree } = await client.send<{
+    frameTree: { childFrames?: Array<{ frame: { id: string; url: string; securityOrigin: string } }> };
+  }>('Page.getFrameTree', {}, sessionId);
+
+  const match = frameTree.childFrames?.find(
+    (cf) => cf.frame.url === frameSrc || cf.frame.id === frameSelector
+  );
+  if (!match) return frameSrc;
+
+  const targets = await client.send<{ targetInfos: Array<{ targetId: string; type: string; url: string }> }>(
+    'Target.getTargets', {}
+  );
+  const oopif = targets.targetInfos.find(
+    (t) => t.type === 'iframe' && t.url === match.frame.url
+  );
+  if (oopif) {
+    await client.send('Target.attachToTarget', { targetId: oopif.targetId, flatten: true });
+  }
+
+  return frameSrc;
 }

package/src/cli/action.ts

@@ -4,7 +4,7 @@ import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { analyzePageForAction, type AnalyzerPage } from '../index.js';
-import type { ActionDef } from '../index.js';
+import type { ActionDef, StepDef } from '../index.js';
 
 async function readAction(filePath: string): Promise<ActionDef> {
   return JSON.parse(await readFile(filePath, 'utf8')) as ActionDef;
@@ -96,8 +96,90 @@ export function createActionCommand(): Command {
         if (eq > 0) params[pair.slice(0, eq)] = pair.slice(eq + 1);
       }
       console.log(`Running action: ${actionId} with account: ${opts.account}`);
-      console.log('Params:', params);
-      console.log('(Action runner not yet implemented — use browse playbook run for full execution)');
+
+      const custom = await getCustomActions();
+      const def = custom.find(a => a.id === actionId);
+      if (!def) {
+        console.error(`Action not found in custom actions: ${actionId}`);
+        console.error('Built-in actions require adapter step definitions — use "action build" to create a custom action.');
+        process.exit(1);
+      }
+
+      const { connectToTarget } = await import('../browser/browser.js');
+      const { openUrl } = await import('../browser/browser.js');
+      const { clickElement, fillElement, evaluateJs } = await import('../browser/actions.js');
+      const { findBySelector } = await import('../browser/find.js');
+      const { waitFor } = await import('../browser/wait.js');
+      const port = parseInt(process.env.MONOBROWSE_PORT ?? '9222', 10);
+      const { client, sessionId } = await connectToTarget(port);
+      const refs = new Map<string, import('../browser/types.js').ElementRef>();
+
+      const interpolate = (s: string) =>
+        s.replace(/\{\{(\w+)\}\}/g, (_, k: string) => params[k] ?? `{{${k}}}`);
+
+      async function runSteps(steps: StepDef[]): Promise<void> {
+        for (const step of steps) {
+          switch (step.type) {
+            case 'navigate':
+              await openUrl(client, sessionId, interpolate(step.url));
+              console.log(`  navigate → ${step.url}`);
+              break;
+            case 'find': {
+              for (const sel of step.selectors) {
+                const found = await findBySelector(client, sessionId, refs, interpolate(sel)).catch(() => null);
+                if (found) { refs.set(step.as, found); break; }
+              }
+              console.log(`  find → ${step.as}`);
+              break;
+            }
+            case 'click': {
+              const ref = refs.get(step.target);
+              if (!ref) throw new Error(`Element "${step.target}" not found`);
+              await clickElement(client, sessionId, ref);
+              console.log(`  click → ${step.target}`);
+              break;
+            }
+            case 'type': {
+              const ref = refs.get(step.target);
+              if (!ref) throw new Error(`Element "${step.target}" not found`);
+              await fillElement(client, sessionId, ref, interpolate(step.text));
+              console.log(`  type → ${step.target}`);
+              break;
+            }
+            case 'wait':
+              if (step.condition === 'network_idle') {
+                await waitFor(client, sessionId, { load: 'networkidle', timeout: step.timeout });
+              } else if (step.condition === 'selector' && step.selector) {
+                await waitFor(client, sessionId, { selector: step.selector, timeout: step.timeout });
+              } else if (step.condition === 'duration') {
+                await new Promise(r => setTimeout(r, step.timeout ?? 1000));
+              }
+              console.log(`  wait → ${step.condition}`);
+              break;
+            case 'extract': {
+              const ref = refs.get(step.target);
+              if (!ref) throw new Error(`Element "${step.target}" not found`);
+              const val = step.attribute
+                ? await evaluateJs(client, sessionId, `document.querySelector('[data-ref="${ref.ref}"]')?.getAttribute('${step.attribute}')`)
+                : await evaluateJs(client, sessionId, `document.querySelector('[data-ref="${ref.ref}"]')?.textContent`);
+              console.log(`  extract → ${step.as}: ${val}`);
+              break;
+            }
+            case 'condition': {
+              const result = await evaluateJs(client, sessionId, step.expression);
+              if (result) {
+                await runSteps(step.then);
+              } else if (step.else) {
+                await runSteps(step.else);
+              }
+              break;
+            }
+          }
+        }
+      }
+
+      await runSteps(def.steps);
+      console.log(`\nAction ${actionId} completed successfully.`);
     });
 
   cmd