@hasna/browser 0.0.6 → 0.0.9

package/dist/cli/index.js

@@ -2309,6 +2309,38 @@ function runMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_gallery_favorite ON gallery_entries(is_favorite);
         CREATE INDEX IF NOT EXISTS idx_gallery_created ON gallery_entries(created_at);
       `
+    },
+    {
+      version: 3,
+      sql: `
+        -- Session lock/claim for multi-agent ownership
+        ALTER TABLE sessions ADD COLUMN locked_by TEXT;
+        ALTER TABLE sessions ADD COLUMN locked_at TEXT;
+      `
+    },
+    {
+      version: 4,
+      sql: `
+        CREATE TABLE IF NOT EXISTS session_events (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+          event_type TEXT NOT NULL,
+          details TEXT DEFAULT '{}',
+          timestamp TEXT DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_session_events_session ON session_events(session_id, timestamp);
+      `
+    },
+    {
+      version: 5,
+      sql: `
+        CREATE TABLE IF NOT EXISTS session_tags (
+          session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+          tag TEXT NOT NULL,
+          PRIMARY KEY (session_id, tag)
+        );
+        CREATE INDEX IF NOT EXISTS idx_session_tags_tag ON session_tags(tag);
+      `
     }
   ];
   for (const m of migrations) {
@@ -2324,6 +2356,28 @@ var _db = null, _dbPath = null;
 var init_schema = () => {};
 
 // src/db/sessions.ts
+var exports_sessions = {};
+__export(exports_sessions, {
+  updateSessionStatus: () => updateSessionStatus,
+  unlockSession: () => unlockSession,
+  transferSession: () => transferSession,
+  renameSession: () => renameSession,
+  removeSessionTag: () => removeSessionTag,
+  lockSession: () => lockSession,
+  listSessionsByTag: () => listSessionsByTag,
+  listSessions: () => listSessions,
+  isSessionLocked: () => isSessionLocked,
+  getSessionTags: () => getSessionTags,
+  getSessionByName: () => getSessionByName,
+  getSession: () => getSession,
+  getDefaultActiveSession: () => getDefaultActiveSession,
+  getActiveSessionForAgent: () => getActiveSessionForAgent,
+  deleteSession: () => deleteSession,
+  createSession: () => createSession,
+  countActiveSessions: () => countActiveSessions,
+  closeSession: () => closeSession,
+  addSessionTag: () => addSessionTag
+});
 import { randomUUID } from "crypto";
 function createSession(data) {
   const db = getDatabase();
@@ -2376,8 +2430,81 @@ function updateSessionStatus(id, status) {
   return getSession(id);
 }
 function closeSession(id) {
+  const db = getDatabase();
+  db.prepare("UPDATE sessions SET locked_by = NULL, locked_at = NULL WHERE id = ?").run(id);
   return updateSessionStatus(id, "closed");
 }
+function lockSession(id, agentId) {
+  const db = getDatabase();
+  const session = getSession(id);
+  if (session.status !== "active")
+    throw new SessionNotFoundError(id);
+  const row = db.query("SELECT locked_by FROM sessions WHERE id = ?").get(id);
+  if (row?.locked_by && row.locked_by !== agentId) {
+    throw new Error(`Session locked by agent ${row.locked_by}`);
+  }
+  db.prepare("UPDATE sessions SET locked_by = ?, locked_at = datetime('now') WHERE id = ?").run(agentId, id);
+  return getSession(id);
+}
+function unlockSession(id, agentId) {
+  const db = getDatabase();
+  if (agentId) {
+    const row = db.query("SELECT locked_by FROM sessions WHERE id = ?").get(id);
+    if (row?.locked_by && row.locked_by !== agentId) {
+      throw new Error(`Session locked by agent ${row.locked_by}, not ${agentId}`);
+    }
+  }
+  db.prepare("UPDATE sessions SET locked_by = NULL, locked_at = NULL WHERE id = ?").run(id);
+  return getSession(id);
+}
+function isSessionLocked(id) {
+  const db = getDatabase();
+  const row = db.query("SELECT locked_by, locked_at FROM sessions WHERE id = ?").get(id);
+  if (!row)
+    throw new SessionNotFoundError(id);
+  return { locked: !!row.locked_by, locked_by: row.locked_by ?? undefined, locked_at: row.locked_at ?? undefined };
+}
+function transferSession(id, toAgentId) {
+  const db = getDatabase();
+  db.prepare("UPDATE sessions SET agent_id = ?, locked_by = ?, locked_at = datetime('now') WHERE id = ?").run(toAgentId, toAgentId, id);
+  return getSession(id);
+}
+function getActiveSessionForAgent(agentId) {
+  const db = getDatabase();
+  return db.query("SELECT * FROM sessions WHERE agent_id = ? AND status = 'active' ORDER BY created_at DESC LIMIT 1").get(agentId) ?? null;
+}
+function getDefaultActiveSession() {
+  const db = getDatabase();
+  const rows = db.query("SELECT * FROM sessions WHERE status = 'active' ORDER BY created_at DESC LIMIT 2").all();
+  return rows.length === 1 ? rows[0] : null;
+}
+function countActiveSessions() {
+  const db = getDatabase();
+  const row = db.query("SELECT COUNT(*) as count FROM sessions WHERE status = 'active'").get();
+  return row?.count ?? 0;
+}
+function deleteSession(id) {
+  const db = getDatabase();
+  db.prepare("DELETE FROM sessions WHERE id = ?").run(id);
+}
+function addSessionTag(id, tag) {
+  const db = getDatabase();
+  db.prepare("INSERT OR IGNORE INTO session_tags (session_id, tag) VALUES (?, ?)").run(id, tag);
+  return getSessionTags(id);
+}
+function removeSessionTag(id, tag) {
+  const db = getDatabase();
+  db.prepare("DELETE FROM session_tags WHERE session_id = ? AND tag = ?").run(id, tag);
+  return getSessionTags(id);
+}
+function getSessionTags(id) {
+  const db = getDatabase();
+  return db.query("SELECT tag FROM session_tags WHERE session_id = ? ORDER BY tag").all(id).map((r) => r.tag);
+}
+function listSessionsByTag(tag) {
+  const db = getDatabase();
+  return db.query("SELECT s.* FROM sessions s JOIN session_tags t ON s.id = t.session_id WHERE t.tag = ? ORDER BY s.created_at DESC").all(tag);
+}
 var init_sessions = __esm(() => {
   init_schema();
   init_types();
@@ -2403,10 +2530,52 @@ async function getPage(browser, options) {
   });
   return context.newPage();
 }
-async function closeBrowser(browser) {
-  try {
-    await browser.close();
-  } catch {}
+
+class BrowserPool {
+  pool = [];
+  maxSize;
+  options;
+  constructor(maxSize = 3, options) {
+    this.maxSize = maxSize;
+    this.options = options;
+  }
+  async acquire(headless = true) {
+    const available = this.pool.find((e) => !e.inUse);
+    if (available) {
+      available.inUse = true;
+      return available.browser;
+    }
+    if (this.pool.length < this.maxSize) {
+      const browser = await launchPlaywright({ ...this.options, headless });
+      this.pool.push({ browser, inUse: true, createdAt: Date.now() });
+      return browser;
+    }
+    return new Promise((resolve) => {
+      const interval = setInterval(() => {
+        const free = this.pool.find((e) => !e.inUse);
+        if (free) {
+          clearInterval(interval);
+          free.inUse = true;
+          resolve(free.browser);
+        }
+      }, 100);
+    });
+  }
+  release(browser) {
+    const entry = this.pool.find((e) => e.browser === browser);
+    if (entry)
+      entry.inUse = false;
+  }
+  async destroyAll() {
+    await Promise.all(this.pool.map((e) => e.browser.close().catch(() => {})));
+    this.pool = [];
+  }
+  get size() {
+    return this.pool.length;
+  }
+  get available() {
+    return this.pool.filter((e) => !e.inUse).length;
+  }
 }
 var DEFAULT_VIEWPORT;
 var init_playwright = __esm(() => {
@@ -3294,6 +3463,7 @@ __export(exports_session, {
   renameSession: () => renameSession2,
   listSessions: () => listSessions2,
   isBunSession: () => isBunSession,
+  isAutoGallery: () => isAutoGallery,
   hasActiveHandle: () => hasActiveHandle,
   getTokenBudget: () => getTokenBudget,
   getSessionPage: () => getSessionPage,
@@ -3302,10 +3472,14 @@ __export(exports_session, {
   getSessionBunView: () => getSessionBunView,
   getSessionBrowser: () => getSessionBrowser,
   getSession: () => getSession2,
+  getDefaultSession: () => getDefaultSession,
   getActiveSessions: () => getActiveSessions,
+  getActiveSessionForAgent: () => getActiveSessionForAgent2,
   createSession: () => createSession2,
+  countActiveSessions: () => countActiveSessions2,
   closeSession: () => closeSession2,
-  closeAllSessions: () => closeAllSessions
+  closeAllSessions: () => closeAllSessions,
+  browserPool: () => pool
 });
 function createBunProxy(view) {
   return view;
@@ -3335,11 +3509,7 @@ async function createSession2(opts = {}) {
     const context = await browser.newContext({ viewport: opts.viewport ?? { width: 1280, height: 720 } });
     page = await context.newPage();
   } else {
-    browser = await launchPlaywright({
-      headless: opts.headless ?? true,
-      viewport: opts.viewport,
-      userAgent: opts.userAgent
-    });
+    browser = await pool.acquire(opts.headless ?? true);
     page = await getPage(browser, { viewport: opts.viewport, userAgent: opts.userAgent });
   }
   const sessionName = opts.name ?? (opts.startUrl ? (() => {
@@ -3393,7 +3563,7 @@ async function createSession2(opts = {}) {
       } catch {}
     }
   }
-  handles.set(session.id, { browser, bunView, page, engine: bunView ? "bun" : resolvedEngine, cleanups, tokenBudget: { total: 0, used: 0 } });
+  handles.set(session.id, { browser, bunView, page, engine: bunView ? "bun" : resolvedEngine, cleanups, tokenBudget: { total: 0, used: 0 }, lastActivity: Date.now(), autoGallery: opts.autoGallery ?? false });
   if (opts.startUrl) {
     try {
       if (bunView) {
@@ -3419,6 +3589,7 @@ function getSessionPage(sessionId) {
     handles.delete(sessionId);
     throw new SessionNotFoundError(sessionId);
   }
+  handle.lastActivity = Date.now();
   return handle.page;
 }
 function getSessionBunView(sessionId) {
@@ -3466,10 +3637,8 @@ async function closeSession2(sessionId) {
       try {
         await handle.page.context().close();
       } catch {}
-      try {
-        if (handle.browser)
-          await closeBrowser(handle.browser);
-      } catch {}
+      if (handle.browser)
+        pool.release(handle.browser);
     }
     handles.delete(sessionId);
   }
@@ -3488,6 +3657,7 @@ async function closeAllSessions() {
   for (const [id] of handles) {
     await closeSession2(id).catch(() => {});
   }
+  await pool.destroyAll();
 }
 function getSessionByName2(name) {
   return getSessionByName(name);
@@ -3499,7 +3669,49 @@ function getTokenBudget(sessionId) {
   const handle = handles.get(sessionId);
   return handle ? handle.tokenBudget : null;
 }
-var handles;
+function getActiveSessionForAgent2(agentId) {
+  const session = getActiveSessionForAgent(agentId);
+  if (!session)
+    return null;
+  const handle = handles.get(session.id);
+  if (!handle)
+    return null;
+  try {
+    if (handle.bunView)
+      handle.bunView.url();
+    else
+      handle.page.url();
+  } catch {
+    handles.delete(session.id);
+    return null;
+  }
+  return { session, page: handle.page };
+}
+function getDefaultSession() {
+  const session = getDefaultActiveSession();
+  if (!session)
+    return null;
+  const handle = handles.get(session.id);
+  if (!handle)
+    return null;
+  try {
+    if (handle.bunView)
+      handle.bunView.url();
+    else
+      handle.page.url();
+  } catch {
+    handles.delete(session.id);
+    return null;
+  }
+  return { session, page: handle.page };
+}
+function isAutoGallery(sessionId) {
+  return handles.get(sessionId)?.autoGallery ?? false;
+}
+function countActiveSessions2() {
+  return countActiveSessions();
+}
+var handles, pool, SESSION_TTL_MS, ttlInterval;
 var init_session = __esm(() => {
   init_types();
   init_types();
@@ -3513,6 +3725,20 @@ var init_session = __esm(() => {
   init_stealth();
   init_dialogs();
   handles = new Map;
+  pool = new BrowserPool(5);
+  SESSION_TTL_MS = parseInt(process.env["SESSION_TTL_MINUTES"] ?? "10", 10) * 60000;
+  ttlInterval = setInterval(async () => {
+    const now = Date.now();
+    for (const [id, handle] of handles) {
+      if (now - handle.lastActivity > SESSION_TTL_MS) {
+        try {
+          await closeSession2(id);
+        } catch {}
+      }
+    }
+  }, 60000);
+  if (ttlInterval.unref)
+    ttlInterval.unref();
 });
 
 // src/lib/snapshot.ts
@@ -15844,6 +16070,20 @@ async function persistFile(localPath, opts) {
 }
 var init_files_integration = () => {};
 
+// src/db/timeline.ts
+function logEvent(sessionId, eventType, details = {}) {
+  const db = getDatabase();
+  const id = crypto.randomUUID();
+  db.prepare("INSERT INTO session_events (id, session_id, event_type, details) VALUES (?, ?, ?, ?)").run(id, sessionId, eventType, JSON.stringify(details));
+}
+function getTimeline(sessionId, limit = 100) {
+  const db = getDatabase();
+  return db.query("SELECT * FROM session_events WHERE session_id = ? ORDER BY timestamp DESC LIMIT ?").all(sessionId, limit);
+}
+var init_timeline = __esm(() => {
+  init_schema();
+});
+
 // src/lib/tabs.ts
 async function newTab(page, url) {
   const context = page.context();
@@ -16235,6 +16475,7 @@ __export(exports_dist, {
   shortUuid: () => shortUuid,
   setFocus: () => setFocus,
   setActiveProfile: () => setActiveProfile,
+  setActiveModel: () => setActiveModel,
   searchMemories: () => searchMemories,
   runCleanup: () => runCleanup,
   resolveProjectId: () => resolveProjectId,
@@ -16285,6 +16526,8 @@ __export(exports_dist, {
   getAutoMemoryStats: () => getAutoMemoryStats,
   getAgent: () => getAgent2,
   getActiveProfile: () => getActiveProfile,
+  getActiveModel: () => getActiveModel,
+  gatherTrainingData: () => gatherTrainingData,
   focusFilterSQL: () => focusFilterSQL,
   findPath: () => findPath,
   enforceQuotas: () => enforceQuotas,
@@ -16301,6 +16544,7 @@ __export(exports_dist, {
   containsSecrets: () => containsSecrets,
   configureAutoMemory: () => configureAutoMemory,
   closeDatabase: () => closeDatabase,
+  clearActiveModel: () => clearActiveModel,
   cleanExpiredMemories: () => cleanExpiredMemories,
   cleanExpiredLocks: () => cleanExpiredLocks,
   checkMemoryWriteLock: () => checkMemoryWriteLock,
@@ -16321,6 +16565,7 @@ __export(exports_dist, {
   InvalidScopeError: () => InvalidScopeError,
   EntityNotFoundError: () => EntityNotFoundError,
   DuplicateMemoryError: () => DuplicateMemoryError,
+  DEFAULT_MODEL: () => DEFAULT_MODEL,
   DEFAULT_CONFIG: () => DEFAULT_CONFIG
 });
 import { Database as Database2 } from "bun:sqlite";
@@ -16332,6 +16577,9 @@ import { basename as basename2, dirname as dirname2, join as join22, resolve as
 import { existsSync as existsSync32, mkdirSync as mkdirSync32, readFileSync as readFileSync22, writeFileSync as writeFileSync22 } from "fs";
 import { homedir as homedir22 } from "os";
 import { join as join32 } from "path";
+import { existsSync as existsSync42, mkdirSync as mkdirSync42, readFileSync as readFileSync32, writeFileSync as writeFileSync32 } from "fs";
+import { homedir as homedir32 } from "os";
+import { join as join42 } from "path";
 function isInMemoryDb(path) {
   return path === ":memory:" || path.startsWith("file::memory:");
 }
@@ -19365,6 +19613,85 @@ function jaccardSimilarity(a, b) {
   const union = new Set([...a, ...b]).size;
   return intersection / union;
 }
+function memoryToRecallExample(memory) {
+  return {
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: `What do you remember about "${memory.key}"?`
+      },
+      {
+        role: "assistant",
+        content: memory.summary ? `${memory.value}
+
+Summary: ${memory.summary}` : memory.value
+      }
+    ]
+  };
+}
+function memoryToSaveExample(memory) {
+  const tags = memory.tags ?? [];
+  return {
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: `Remember this for me: ${memory.key} = ${memory.value}${tags.length ? ` (tags: ${tags.join(", ")})` : ""}`
+      },
+      {
+        role: "assistant",
+        content: `Saved to memory: "${memory.key}" with ${memory.category} category, importance ${memory.importance}/10, scope: ${memory.scope}.`
+      }
+    ]
+  };
+}
+function memoryToSearchExample(memories, category) {
+  const matched = memories.filter((m) => m.category === category && m.status === "active").slice(0, 5);
+  return {
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: `What ${category} memories do you have?` },
+      {
+        role: "assistant",
+        content: matched.length > 0 ? `Here are my ${category} memories:
+${matched.map((m) => `- ${m.key}: ${m.value.slice(0, 120)}${m.value.length > 120 ? "..." : ""}`).join(`
+`)}` : `I don't have any ${category} memories stored yet.`
+      }
+    ]
+  };
+}
+function readConfig() {
+  if (!existsSync42(CONFIG_PATH))
+    return {};
+  try {
+    const raw = readFileSync32(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function writeConfig(config) {
+  if (!existsSync42(CONFIG_DIR)) {
+    mkdirSync42(CONFIG_DIR, { recursive: true });
+  }
+  writeFileSync32(CONFIG_PATH, JSON.stringify(config, null, 2) + `
+`, "utf-8");
+}
+function getActiveModel() {
+  const config = readConfig();
+  return config.activeModel ?? DEFAULT_MODEL;
+}
+function setActiveModel(modelId) {
+  const config = readConfig();
+  config.activeModel = modelId;
+  writeConfig(config);
+}
+function clearActiveModel() {
+  const config = readConfig();
+  delete config.activeModel;
+  writeConfig(config);
+}
 var __defProp2, __export2 = (target, all) => {
   for (var name in all)
     __defProp2(target, name, {
@@ -19407,7 +19734,27 @@ Return JSON with this exact shape:
   "relations": [
     { "from": string, "to": string, "type": "uses"|"knows"|"depends_on"|"created_by"|"related_to"|"contradicts"|"part_of"|"implements"|"happened_before"|"happened_after"|"caused_by"|"resulted_in"|"supersedes"|"version_of" }
   ]
-}`, ANTHROPIC_MODELS, AnthropicProvider, OpenAICompatProvider, OPENAI_MODELS, OpenAIProvider, CEREBRAS_MODELS, CerebrasProvider, GROK_MODELS, GrokProvider, providerRegistry, MAX_QUEUE_SIZE = 100, CONCURRENCY = 3, autoMemoryQueue, DEDUP_SIMILARITY_THRESHOLD = 0.85, DEFAULT_CONFIG2, _stats;
+}`, ANTHROPIC_MODELS, AnthropicProvider, OpenAICompatProvider, OPENAI_MODELS, OpenAIProvider, CEREBRAS_MODELS, CerebrasProvider, GROK_MODELS, GrokProvider, providerRegistry, MAX_QUEUE_SIZE = 100, CONCURRENCY = 3, autoMemoryQueue, DEDUP_SIMILARITY_THRESHOLD = 0.85, DEFAULT_CONFIG2, _stats, SYSTEM_PROMPT = "You are an AI assistant with persistent memory that recalls and saves information across sessions.", gatherTrainingData = async (options = {}) => {
+  const allMemories = listMemories({ status: "active" });
+  const filtered = options.since ? allMemories.filter((m) => new Date(m.created_at) >= options.since) : allMemories;
+  const sorted = filtered.slice().sort((a, b) => b.importance - a.importance);
+  const fetchSet = options.limit ? sorted.slice(0, options.limit * 3) : sorted;
+  const examples = [];
+  for (const memory of fetchSet) {
+    examples.push(memoryToRecallExample(memory));
+    examples.push(memoryToSaveExample(memory));
+  }
+  const categories = [...new Set(fetchSet.map((m) => m.category))];
+  for (const category of categories) {
+    examples.push(memoryToSearchExample(fetchSet, category));
+  }
+  const finalExamples = options.limit ? examples.slice(0, options.limit) : examples;
+  return {
+    source: "mementos",
+    examples: finalExamples,
+    count: finalExamples.length
+  };
+}, DEFAULT_MODEL = "gpt-4o-mini", CONFIG_DIR, CONFIG_PATH;
 var init_dist = __esm(() => {
   __defProp2 = Object.defineProperty;
   exports_database = {};
@@ -20687,6 +21034,8 @@ Return only a number 0-10.`);
     keepLonger: true
   };
   _stats = { checked: 0, skipped: 0, updated: 0 };
+  CONFIG_DIR = join42(homedir32(), ".mementos");
+  CONFIG_PATH = join42(CONFIG_DIR, "config.json");
 });
 
 // src/lib/page-memory.ts
@@ -20847,13 +21196,13 @@ import { homedir as homedir10 } from "os";
 import { randomUUID as randomUUID10 } from "crypto";
 import { mkdirSync as mkdirSync23, copyFileSync as copyFileSync3, statSync as statSync2 } from "fs";
 import { join as join33 } from "path";
-import { homedir as homedir32 } from "os";
+import { homedir as homedir33 } from "os";
 import { readFileSync as readFileSync5 } from "fs";
 import { join as join23 } from "path";
 import { homedir as homedir23 } from "os";
 import { randomUUID as randomUUID22 } from "crypto";
 import { readFileSync as readFileSync23, writeFileSync as writeFileSync4, mkdirSync as mkdirSync33 } from "fs";
-import { join as join42, dirname as dirname22 } from "path";
+import { join as join43, dirname as dirname22 } from "path";
 import { homedir as homedir42 } from "os";
 function getDbPath2() {
   if (process.env.CONVERSATIONS_DB_PATH)
@@ -21192,7 +21541,7 @@ function parseMessage(row) {
 function getAttachmentsDir() {
   if (process.env.CONVERSATIONS_ATTACHMENTS_DIR)
     return process.env.CONVERSATIONS_ATTACHMENTS_DIR;
-  return join33(homedir32(), ".conversations", "attachments");
+  return join33(homedir33(), ".conversations", "attachments");
 }
 function guessMimeType(name) {
   const ext = name.split(".").pop()?.toLowerCase();
@@ -24863,7 +25212,7 @@ Check the top-level render call using <` + parentName + ">.";
     "zinc-eagle",
     "zone-fox"
   ];
-  AGENT_ID_FILE = join42(homedir42(), ".conversations", "agent-id");
+  AGENT_ID_FILE = join43(homedir42(), ".conversations", "agent-id");
   init_db();
   init_db();
   CONFLICT_THRESHOLD_SECONDS = 30 * 60;
@@ -25205,7 +25554,7 @@ __export(exports_dist3, {
   deleteTemplate: () => deleteTemplate,
   deleteTaskList: () => deleteTaskList,
   deleteTask: () => deleteTask,
-  deleteSession: () => deleteSession,
+  deleteSession: () => deleteSession2,
   deleteProject: () => deleteProject2,
   deletePlan: () => deletePlan,
   deleteOrg: () => deleteOrg,
@@ -25272,11 +25621,11 @@ import { existsSync as existsSync33 } from "fs";
 import { join as join34 } from "path";
 import { existsSync as existsSync23, mkdirSync as mkdirSync24, readFileSync as readFileSync6, readdirSync as readdirSync4, statSync as statSync3, writeFileSync as writeFileSync5 } from "fs";
 import { join as join24 } from "path";
-import { existsSync as existsSync42, readFileSync as readFileSync24, readdirSync as readdirSync22, writeFileSync as writeFileSync23 } from "fs";
-import { join as join43 } from "path";
+import { existsSync as existsSync43, readFileSync as readFileSync24, readdirSync as readdirSync22, writeFileSync as writeFileSync23 } from "fs";
+import { join as join44 } from "path";
 import { existsSync as existsSync52 } from "fs";
 import { join as join52 } from "path";
-import { readFileSync as readFileSync32, statSync as statSync22 } from "fs";
+import { readFileSync as readFileSync33, statSync as statSync22 } from "fs";
 import { relative, resolve as resolve22, join as join62 } from "path";
 import { execSync as execSync2 } from "child_process";
 
@@ -27634,11 +27983,11 @@ function autoReleaseStaleAgents(db2) {
   const result = d.run("UPDATE agents SET session_id = NULL WHERE status = 'active' AND session_id IS NOT NULL AND last_seen_at < ?", [cutoff]);
   return result.changes;
 }
-function getAvailableNamesFromPool(pool, db2) {
+function getAvailableNamesFromPool(pool2, db2) {
   autoReleaseStaleAgents(db2);
   const cutoff = new Date(Date.now() - getActiveWindowMs()).toISOString();
   const activeNames = new Set(db2.query("SELECT name FROM agents WHERE status = 'active' AND last_seen_at > ?").all(cutoff).map((r) => r.name.toLowerCase()));
-  return pool.filter((name) => !activeNames.has(name.toLowerCase()));
+  return pool2.filter((name) => !activeNames.has(name.toLowerCase()));
 }
 function shortUuid2() {
   return crypto.randomUUID().slice(0, 8);
@@ -27715,9 +28064,9 @@ function registerAgent5(input, db2) {
 function isAgentConflict2(result) {
   return result.conflict === true;
 }
-function buildConflictError(existing, lastSeenMs, pool, d) {
+function buildConflictError(existing, lastSeenMs, pool2, d) {
   const minutesAgo = Math.round((Date.now() - lastSeenMs) / 60000);
-  const suggestions = pool ? getAvailableNamesFromPool(pool, d) : [];
+  const suggestions = pool2 ? getAvailableNamesFromPool(pool2, d) : [];
   return {
     conflict: true,
     existing_id: existing.id,
@@ -28003,7 +28352,7 @@ function updateSessionActivity(id, db2) {
   const d = db2 || getDatabase3();
   d.run("UPDATE sessions SET last_activity = ? WHERE id = ?", [now2(), id]);
 }
-function deleteSession(id, db2) {
+function deleteSession2(id, db2) {
   const d = db2 || getDatabase3();
   const result = d.run("DELETE FROM sessions WHERE id = ?", [id]);
   return result.changes > 0;
@@ -28822,13 +29171,13 @@ function searchTasks(options, projectId, taskListId, db2) {
   return rows.map(rowToTask3);
 }
 function getTaskListDir(taskListId) {
-  return join43(HOME, ".claude", "tasks", taskListId);
+  return join44(HOME, ".claude", "tasks", taskListId);
 }
 function readClaudeTask(dir, filename) {
-  return readJsonFile(join43(dir, filename));
+  return readJsonFile(join44(dir, filename));
 }
 function writeClaudeTask(dir, task) {
-  writeJsonFile(join43(dir, `${task.id}.json`), task);
+  writeJsonFile(join44(dir, `${task.id}.json`), task);
 }
 function toClaudeStatus(status) {
   if (status === "pending" || status === "in_progress" || status === "completed") {
@@ -28840,14 +29189,14 @@ function toSqliteStatus(status) {
   return status;
 }
 function readPrefixCounter(dir) {
-  const path = join43(dir, ".prefix-counter");
-  if (!existsSync42(path))
+  const path = join44(dir, ".prefix-counter");
+  if (!existsSync43(path))
     return 0;
   const val = parseInt(readFileSync24(path, "utf-8").trim(), 10);
   return isNaN(val) ? 0 : val;
 }
 function writePrefixCounter(dir, value) {
-  writeFileSync23(join43(dir, ".prefix-counter"), String(value));
+  writeFileSync23(join44(dir, ".prefix-counter"), String(value));
 }
 function formatPrefixedSubject(title, prefix, counter) {
   const padded = String(counter).padStart(5, "0");
@@ -28874,7 +29223,7 @@ function taskToClaudeTask(task, claudeTaskId, existingMeta) {
 }
 function pushToClaudeTaskList(taskListId, projectId, options = {}) {
   const dir = getTaskListDir(taskListId);
-  if (!existsSync42(dir))
+  if (!existsSync43(dir))
     ensureDir22(dir);
   const filter = {};
   if (projectId)
@@ -28883,7 +29232,7 @@ function pushToClaudeTaskList(taskListId, projectId, options = {}) {
   const existingByTodosId = new Map;
   const files = listJsonFiles(dir);
   for (const f of files) {
-    const path = join43(dir, f);
+    const path = join44(dir, f);
     const ct = readClaudeTask(dir, f);
     if (ct?.metadata?.["todos_id"]) {
       existingByTodosId.set(ct.metadata["todos_id"], { task: ct, mtimeMs: getFileMtimeMs(path) });
@@ -28970,7 +29319,7 @@ function pushToClaudeTaskList(taskListId, projectId, options = {}) {
 }
 function pullFromClaudeTaskList(taskListId, projectId, options = {}) {
   const dir = getTaskListDir(taskListId);
-  if (!existsSync42(dir)) {
+  if (!existsSync43(dir)) {
     return { pushed: 0, pulled: 0, errors: [`Task list directory not found: ${dir}`] };
   }
   const files = readdirSync22(dir).filter((f) => f.endsWith(".json"));
@@ -28990,7 +29339,7 @@ function pullFromClaudeTaskList(taskListId, projectId, options = {}) {
   }
   for (const f of files) {
     try {
-      const filePath = join43(dir, f);
+      const filePath = join44(dir, f);
       const ct = readClaudeTask(dir, f);
       if (!ct)
         continue;
@@ -29401,7 +29750,7 @@ function extractTodos(options, db2) {
   for (const file of files) {
     const fullPath = statSync22(basePath).isFile() ? basePath : join62(basePath, file);
     try {
-      const source = readFileSync32(fullPath, "utf-8");
+      const source = readFileSync33(fullPath, "utf-8");
       const relPath = statSync22(basePath).isFile() ? relative(resolve22(basePath, ".."), fullPath) : file;
       const comments = extractFromSource(source, relPath, tags);
       allComments.push(...comments);
@@ -30627,7 +30976,7 @@ import { homedir as homedir11 } from "os";
 import { fileURLToPath } from "url";
 import { existsSync as existsSync24, readFileSync as readFileSync25, readdirSync as readdirSync23 } from "fs";
 import { join as join25 } from "path";
-import { existsSync as existsSync34, readFileSync as readFileSync33, writeFileSync as writeFileSync24, mkdirSync as mkdirSync25 } from "fs";
+import { existsSync as existsSync34, readFileSync as readFileSync34, writeFileSync as writeFileSync24, mkdirSync as mkdirSync25 } from "fs";
 import { join as join35, dirname as dirname23 } from "path";
 import { homedir as homedir24 } from "os";
 function getSkillsByCategory(category) {
@@ -31281,7 +31630,7 @@ function readConfigFile(path) {
   if (!existsSync34(path))
     return {};
   try {
-    const raw = readFileSync33(path, "utf-8");
+    const raw = readFileSync34(path, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
       return {};
@@ -31314,7 +31663,7 @@ function saveConfig(key, value, scope = "project") {
   let existing = {};
   if (existsSync34(filePath)) {
     try {
-      existing = JSON.parse(readFileSync33(filePath, "utf-8"));
+      existing = JSON.parse(readFileSync34(filePath, "utf-8"));
       if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
         existing = {};
       }
@@ -33256,7 +33605,7 @@ ${snap.tree.slice(0, 2000)}`;
     const response = await client.messages.create({
       model,
       max_tokens: 512,
-      system: SYSTEM_PROMPT,
+      system: SYSTEM_PROMPT2,
       messages: [{
         role: "user",
         content: `Task: ${task}
@@ -33321,7 +33670,7 @@ What actions should I take next? Return JSON array.`
   }
   return { success: false, result: null, steps_taken: steps.length, steps, cost_estimate: totalTokens / 1000 * 0.00025, error: `Reached max steps (${maxSteps}) without completing task` };
 }
-var SYSTEM_PROMPT = `You are a browser automation agent. Given a task and the current page state, decide which browser actions to take.
+var SYSTEM_PROMPT2 = `You are a browser automation agent. Given a task and the current page state, decide which browser actions to take.
 
 Return a JSON array of at most 3 actions to execute next:
 [{"tool": "navigate|click|type|scroll|evaluate|done", "args": {...}, "reason": "..."}]
@@ -33347,6 +33696,34 @@ function err(e) {
     isError: true
   };
 }
+async function errWithScreenshot(e, sessionId) {
+  const msg = e instanceof Error ? e.message : String(e);
+  const code = e instanceof BrowserError ? e.code : "ERROR";
+  let screenshot_path;
+  if (sessionId) {
+    try {
+      const sid = resolveSessionId(sessionId);
+      const page = getSessionPage(sid);
+      const result = await takeScreenshot(page, { maxWidth: 800, quality: 50, track: false, thumbnail: false });
+      screenshot_path = result.path;
+    } catch {}
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: msg, code, error_screenshot: screenshot_path }) }],
+    isError: true
+  };
+}
+function resolveSessionId(sessionId) {
+  if (sessionId)
+    return sessionId;
+  const def = getDefaultSession();
+  if (def)
+    return def.session.id;
+  const count = countActiveSessions2();
+  if (count === 0)
+    throw new BrowserError("No active sessions. Create one with browser_session_create first.", "NO_SESSION");
+  throw new BrowserError(`${count} active sessions \u2014 specify session_id to choose one.`, "AMBIGUOUS_SESSION");
+}
 var _pkg, networkLogCleanup, consoleCaptureCleanup, harCaptures, server, activeWatchHandles2, _startupToolCount, transport;
 var init_mcp = __esm(async () => {
   init_zod();
@@ -33368,6 +33745,7 @@ var init_mcp = __esm(async () => {
   init_snapshot();
   init_files_integration();
   init_recordings();
+  init_timeline();
   init_dialogs();
   init_profiles();
   init_types();
@@ -33379,7 +33757,7 @@ var init_mcp = __esm(async () => {
     name: "@hasna/browser",
     version: "0.0.1"
   });
-  server.tool("browser_session_create", "Create a new browser session with the specified engine", {
+  server.tool("browser_session_create", "Create a new browser session. If agent_id is set and already has an active session, returns the existing one (use force_new to override). If session_id is omitted on other tools, the single active session is auto-selected.", {
     engine: exports_external.enum(["playwright", "cdp", "lightpanda", "bun", "auto"]).optional().default("auto"),
     use_case: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
@@ -33388,9 +33766,17 @@ var init_mcp = __esm(async () => {
     headless: exports_external.boolean().optional().default(true),
     viewport_width: exports_external.number().optional().default(1280),
     viewport_height: exports_external.number().optional().default(720),
-    stealth: exports_external.boolean().optional().default(false)
-  }, async ({ engine, use_case, project_id, agent_id, start_url, headless, viewport_width, viewport_height, stealth }) => {
+    stealth: exports_external.boolean().optional().default(false),
+    auto_gallery: exports_external.boolean().optional().default(false),
+    force_new: exports_external.boolean().optional().default(false).describe("Force create a new session even if agent already has one"),
+    tags: exports_external.array(exports_external.string()).optional()
+  }, async ({ engine, use_case, project_id, agent_id, start_url, headless, viewport_width, viewport_height, stealth, auto_gallery, force_new, tags }) => {
     try {
+      if (agent_id && !force_new) {
+        const existing = getActiveSessionForAgent2(agent_id);
+        if (existing)
+          return json({ session: existing.session, reused: true });
+      }
       const { session } = await createSession2({
         engine,
         useCase: use_case,
@@ -33399,44 +33785,66 @@ var init_mcp = __esm(async () => {
         startUrl: start_url,
         headless,
         viewport: { width: viewport_width, height: viewport_height },
-        stealth
+        stealth,
+        autoGallery: auto_gallery
       });
-      return json({ session });
+      if (tags?.length) {
+        const { addSessionTag: addSessionTag2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+        for (const tag of tags)
+          addSessionTag2(session.id, tag);
+      }
+      logEvent(session.id, "session_created", { engine: session.engine });
+      return json({ session, reused: false });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_session_list", "List all browser sessions", { status: exports_external.enum(["active", "closed", "error"]).optional(), project_id: exports_external.string().optional() }, async ({ status, project_id }) => {
+  server.tool("browser_session_list", "List all browser sessions. Optionally filter by tag.", { status: exports_external.enum(["active", "closed", "error"]).optional(), project_id: exports_external.string().optional(), tag: exports_external.string().optional() }, async ({ status, project_id, tag }) => {
     try {
+      if (tag) {
+        const { listSessionsByTag: listSessionsByTag2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+        return json({ sessions: listSessionsByTag2(tag) });
+      }
       return json({ sessions: listSessions2({ status, projectId: project_id }) });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_session_close", "Close a browser session", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_session_close", "Close a browser session", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const session = await closeSession2(session_id);
-      networkLogCleanup.get(session_id)?.();
-      consoleCaptureCleanup.get(session_id)?.();
-      networkLogCleanup.delete(session_id);
-      consoleCaptureCleanup.delete(session_id);
-      harCaptures.delete(session_id);
+      const sid = resolveSessionId(session_id);
+      const session = await closeSession2(sid);
+      networkLogCleanup.get(sid)?.();
+      consoleCaptureCleanup.get(sid)?.();
+      networkLogCleanup.delete(sid);
+      consoleCaptureCleanup.delete(sid);
+      harCaptures.delete(sid);
       return json({ session });
     } catch (e) {
       return err(e);
     }
   });
+  server.tool("browser_session_timeline", "Get chronological action log for a session", { session_id: exports_external.string().optional(), limit: exports_external.number().optional().default(50) }, async ({ session_id, limit }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      const events = getTimeline(sid, limit);
+      return json({ events, count: events.length });
+    } catch (e) {
+      return err(e);
+    }
+  });
   server.tool("browser_navigate", "Navigate to a URL. Auto-detects redirects, auto-names session, returns compact refs + thumbnail.", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     url: exports_external.string(),
     timeout: exports_external.number().optional().default(30000),
     auto_snapshot: exports_external.boolean().optional().default(true),
     auto_thumbnail: exports_external.boolean().optional().default(true)
   }, async ({ session_id, url, timeout, auto_snapshot, auto_thumbnail }) => {
     try {
-      const page = getSessionPage(session_id);
-      if (isBunSession(session_id)) {
-        const bunView = getSessionBunView(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
+      if (isBunSession(sid)) {
+        const bunView = getSessionBunView(sid);
         await bunView.goto(url, { timeout });
         await new Promise((r) => setTimeout(r, 500));
       } else {
@@ -33463,10 +33871,10 @@ var init_mcp = __esm(async () => {
         } catch {}
       }
       try {
-        const session = getSession2(session_id);
+        const session = getSession2(sid);
         if (!session.name) {
           const hostname = new URL(current_url).hostname;
-          renameSession2(session_id, hostname);
+          renameSession2(sid, hostname);
         }
       } catch {}
       const result = {
@@ -33482,86 +33890,104 @@ var init_mcp = __esm(async () => {
           result.thumbnail_base64 = ss.base64.length > 50000 ? "" : ss.base64;
         } catch {}
       }
-      if (isBunSession(session_id) && auto_snapshot) {
+      if (isAutoGallery(sid)) {
+        try {
+          const ss = await takeScreenshot(page, { maxWidth: 1280, quality: 70, thumbnail: true });
+          const { createEntry: createEntry2 } = await Promise.resolve().then(() => (init_gallery(), exports_gallery));
+          createEntry2({ session_id: sid, url: current_url, title, path: ss.path, thumbnail_path: ss.thumbnail_path, format: "webp", width: ss.width, height: ss.height, original_size_bytes: ss.original_size_bytes, compressed_size_bytes: ss.compressed_size_bytes, compression_ratio: ss.compression_ratio, tags: [], is_favorite: false });
+        } catch {}
+      }
+      if (isBunSession(sid) && auto_snapshot) {
         await new Promise((r) => setTimeout(r, 200));
       }
       if (auto_snapshot) {
         try {
-          const snap = await takeSnapshot(page, session_id);
-          setLastSnapshot(session_id, snap);
+          const snap = await takeSnapshot(page, sid);
+          setLastSnapshot(sid, snap);
           const refEntries = Object.entries(snap.refs).slice(0, 30);
           result.snapshot_refs = refEntries.map(([ref, info]) => `${info.role}:${info.name.slice(0, 50)} [${ref}]`).join(", ");
           result.interactive_count = snap.interactive_count;
-          result.has_errors = getConsoleLog(session_id, "error").length > 0;
+          result.has_errors = getConsoleLog(sid, "error").length > 0;
         } catch {}
       }
+      logEvent(sid, "navigate", { url, title, current_url });
       return json(result);
     } catch (e) {
-      return err(e);
+      return errWithScreenshot(e, session_id);
     }
   });
-  server.tool("browser_back", "Navigate back in browser history", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_back", "Navigate back in browser history", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await goBack(page);
       return json({ url: page.url() });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_forward", "Navigate forward in browser history", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_forward", "Navigate forward in browser history", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await goForward(page);
       return json({ url: page.url() });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_reload", "Reload the current page", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_reload", "Reload the current page", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await reload(page);
       return json({ url: page.url() });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_click", "Click an element by ref (from snapshot) or CSS selector. Prefer ref for reliability.", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), button: exports_external.enum(["left", "right", "middle"]).optional(), timeout: exports_external.number().optional() }, async ({ session_id, selector, ref, button, timeout }) => {
+  server.tool("browser_click", "Click an element by ref (from snapshot) or CSS selector. Prefer ref for reliability.", { session_id: exports_external.string().optional(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), button: exports_external.enum(["left", "right", "middle"]).optional(), timeout: exports_external.number().optional() }, async ({ session_id, selector, ref, button, timeout }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (ref) {
-        await clickRef(page, session_id, ref, { timeout });
+        await clickRef(page, sid, ref, { timeout });
+        logEvent(sid, "click", { selector: ref, method: "ref" });
         return json({ clicked: ref, method: "ref" });
       }
       if (!selector)
         return err(new Error("Either ref or selector is required"));
       await click(page, selector, { button, timeout });
+      logEvent(sid, "click", { selector, method: "selector" });
       return json({ clicked: selector, method: "selector" });
     } catch (e) {
-      return err(e);
+      return errWithScreenshot(e, session_id);
     }
   });
-  server.tool("browser_type", "Type text into an element by ref or selector. Prefer ref.", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), text: exports_external.string(), clear: exports_external.boolean().optional().default(false), delay: exports_external.number().optional() }, async ({ session_id, selector, ref, text, clear, delay }) => {
+  server.tool("browser_type", "Type text into an element by ref or selector. Prefer ref.", { session_id: exports_external.string().optional(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), text: exports_external.string(), clear: exports_external.boolean().optional().default(false), delay: exports_external.number().optional() }, async ({ session_id, selector, ref, text, clear, delay }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (ref) {
-        await typeRef(page, session_id, ref, text, { clear, delay });
+        await typeRef(page, sid, ref, text, { clear, delay });
+        logEvent(sid, "type", { selector: ref, text: text.slice(0, 100) });
         return json({ typed: text, ref, method: "ref" });
       }
       if (!selector)
         return err(new Error("Either ref or selector is required"));
       await type(page, selector, text, { clear, delay });
+      logEvent(sid, "type", { selector, text: text.slice(0, 100) });
       return json({ typed: text, selector, method: "selector" });
     } catch (e) {
-      return err(e);
+      return errWithScreenshot(e, session_id);
     }
   });
-  server.tool("browser_hover", "Hover over an element by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional() }, async ({ session_id, selector, ref }) => {
+  server.tool("browser_hover", "Hover over an element by ref or selector", { session_id: exports_external.string().optional(), selector: exports_external.string().optional(), ref: exports_external.string().optional() }, async ({ session_id, selector, ref }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (ref) {
-        await hoverRef(page, session_id, ref);
+        await hoverRef(page, sid, ref);
         return json({ hovered: ref, method: "ref" });
       }
       if (!selector)
@@ -33572,20 +33998,22 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_scroll", "Scroll the page", { session_id: exports_external.string(), direction: exports_external.enum(["up", "down", "left", "right"]).optional().default("down"), amount: exports_external.number().optional().default(300) }, async ({ session_id, direction, amount }) => {
+  server.tool("browser_scroll", "Scroll the page", { session_id: exports_external.string().optional(), direction: exports_external.enum(["up", "down", "left", "right"]).optional().default("down"), amount: exports_external.number().optional().default(300) }, async ({ session_id, direction, amount }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await scroll(page, direction, amount);
       return json({ scrolled: direction, amount });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_select", "Select a dropdown option by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), value: exports_external.string() }, async ({ session_id, selector, ref, value }) => {
+  server.tool("browser_select", "Select a dropdown option by ref or selector", { session_id: exports_external.string().optional(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), value: exports_external.string() }, async ({ session_id, selector, ref, value }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (ref) {
-        const selected2 = await selectRef(page, session_id, ref, value);
+        const selected2 = await selectRef(page, sid, ref, value);
         return json({ selected: selected2, method: "ref" });
       }
       if (!selector)
@@ -33596,11 +34024,12 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_toggle", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
+  server.tool("browser_toggle", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string().optional(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (ref) {
-        await checkRef(page, session_id, ref, checked);
+        await checkRef(page, sid, ref, checked);
         return json({ checked, ref, method: "ref" });
       }
       if (!selector)
@@ -33611,52 +34040,58 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_upload", "Upload a file to an input element", { session_id: exports_external.string(), selector: exports_external.string(), file_path: exports_external.string() }, async ({ session_id, selector, file_path }) => {
+  server.tool("browser_upload", "Upload a file to an input element", { session_id: exports_external.string().optional(), selector: exports_external.string(), file_path: exports_external.string() }, async ({ session_id, selector, file_path }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await uploadFile(page, selector, file_path);
       return json({ uploaded: file_path, selector });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_press_key", "Press a keyboard key", { session_id: exports_external.string(), key: exports_external.string() }, async ({ session_id, key }) => {
+  server.tool("browser_press_key", "Press a keyboard key", { session_id: exports_external.string().optional(), key: exports_external.string() }, async ({ session_id, key }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await pressKey(page, key);
       return json({ pressed: key });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_wait", "Wait for a selector to appear", { session_id: exports_external.string(), selector: exports_external.string(), state: exports_external.enum(["attached", "detached", "visible", "hidden"]).optional(), timeout: exports_external.number().optional() }, async ({ session_id, selector, state, timeout }) => {
+  server.tool("browser_wait", "Wait for a selector to appear", { session_id: exports_external.string().optional(), selector: exports_external.string(), state: exports_external.enum(["attached", "detached", "visible", "hidden"]).optional(), timeout: exports_external.number().optional() }, async ({ session_id, selector, state, timeout }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await waitForSelector(page, selector, { state, timeout });
       return json({ ready: selector });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_get_text", "Get text content from the page or a selector", { session_id: exports_external.string(), selector: exports_external.string().optional() }, async ({ session_id, selector }) => {
+  server.tool("browser_get_text", "Get text content from the page or a selector", { session_id: exports_external.string().optional(), selector: exports_external.string().optional() }, async ({ session_id, selector }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       return json({ text: await getText(page, selector) });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_get_html", "Get HTML content from the page or a selector", { session_id: exports_external.string(), selector: exports_external.string().optional() }, async ({ session_id, selector }) => {
+  server.tool("browser_get_html", "Get HTML content from the page or a selector", { session_id: exports_external.string().optional(), selector: exports_external.string().optional() }, async ({ session_id, selector }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       return json({ html: await getHTML(page, selector) });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_get_links", "Get all links from the current page", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_get_links", "Get all links from the current page", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const links = await getLinks(page);
       return json({ links, count: links.length });
     } catch (e) {
@@ -33664,22 +34099,24 @@ var init_mcp = __esm(async () => {
     }
   });
   server.tool("browser_extract", "Extract content from the page in a specified format", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     format: exports_external.enum(["text", "html", "links", "table", "structured"]).optional().default("text"),
     selector: exports_external.string().optional(),
     schema: exports_external.record(exports_external.string()).optional()
   }, async ({ session_id, format, selector, schema }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const result = await extract(page, { format, selector, schema });
       return json(result);
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_find", "Find elements matching a selector and return their text", { session_id: exports_external.string(), selector: exports_external.string() }, async ({ session_id, selector }) => {
+  server.tool("browser_find", "Find elements matching a selector and return their text", { session_id: exports_external.string().optional(), selector: exports_external.string() }, async ({ session_id, selector }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const elements = await findElements(page, selector);
       const texts = await Promise.all(elements.map((el) => el.textContent()));
       return json({ count: elements.length, texts });
@@ -33688,15 +34125,16 @@ var init_mcp = __esm(async () => {
     }
   });
   server.tool("browser_snapshot", "Get accessibility snapshot with element refs (@e0, @e1...). Use compact=true (default) for token-efficient output. Use refs in browser_click, browser_type, etc.", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     compact: exports_external.boolean().optional().default(true),
     max_refs: exports_external.number().optional().default(50),
     full_tree: exports_external.boolean().optional().default(false)
   }, async ({ session_id, compact, max_refs, full_tree }) => {
     try {
-      const page = getSessionPage(session_id);
-      const result = await takeSnapshot(page, session_id);
-      setLastSnapshot(session_id, result);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
+      const result = await takeSnapshot(page, sid);
+      setLastSnapshot(sid, result);
       const refEntries = Object.entries(result.refs).slice(0, max_refs);
       const limitedRefs = Object.fromEntries(refEntries);
       const truncated = Object.keys(result.refs).length > max_refs;
@@ -33719,21 +34157,22 @@ var init_mcp = __esm(async () => {
     }
   });
   server.tool("browser_screenshot", "Take a screenshot. Use annotate=true to overlay numbered labels on interactive elements for visual+ref workflows.", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     selector: exports_external.string().optional(),
     full_page: exports_external.boolean().optional().default(false),
     format: exports_external.enum(["png", "jpeg", "webp"]).optional().default("webp"),
-    quality: exports_external.number().optional(),
-    max_width: exports_external.number().optional().default(1280),
+    quality: exports_external.number().optional().default(60),
+    max_width: exports_external.number().optional().default(800),
     compress: exports_external.boolean().optional().default(true),
     thumbnail: exports_external.boolean().optional().default(true),
     annotate: exports_external.boolean().optional().default(false)
   }, async ({ session_id, selector, full_page, format, quality, max_width, compress, thumbnail, annotate }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (annotate && !selector && !full_page) {
         const { annotateScreenshot: annotateScreenshot2 } = await Promise.resolve().then(() => (init_annotate(), exports_annotate));
-        const annotated = await annotateScreenshot2(page, session_id);
+        const annotated = await annotateScreenshot2(page, sid);
         const base64 = annotated.buffer.toString("base64");
         return json({
           base64: base64.length > 50000 ? undefined : base64,
@@ -33749,32 +34188,35 @@ var init_mcp = __esm(async () => {
       try {
         const buf = Buffer.from(result.base64, "base64");
         const filename = result.path.split("/").pop() ?? `screenshot.${format ?? "webp"}`;
-        const dl = saveToDownloads(buf, filename, { sessionId: session_id, type: "screenshot", sourceUrl: page.url() });
+        const dl = saveToDownloads(buf, filename, { sessionId: sid, type: "screenshot", sourceUrl: page.url() });
         result.download_id = dl.id;
       } catch {}
-      if (result.base64.length > 50000) {
+      result.estimated_tokens = Math.ceil(result.base64.length / 4);
+      if (result.base64.length > 20000) {
         result.base64_truncated = true;
         result.full_image_path = result.path;
         result.base64 = result.thumbnail_base64 ?? "";
       }
+      logEvent(sid, "screenshot", { path: result.path });
       return json(result);
     } catch (e) {
       return err(e);
     }
   });
   server.tool("browser_pdf", "Generate a PDF of the current page", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     format: exports_external.enum(["A4", "Letter", "A3", "A5"]).optional().default("A4"),
     landscape: exports_external.boolean().optional().default(false),
     print_background: exports_external.boolean().optional().default(true)
   }, async ({ session_id, format, landscape, print_background }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const result = await generatePDF(page, { format, landscape, printBackground: print_background });
       try {
         const buf = Buffer.from(result.base64, "base64");
         const filename = result.path.split("/").pop() ?? "document.pdf";
-        const dl = saveToDownloads(buf, filename, { sessionId: session_id, type: "pdf", sourceUrl: page.url() });
+        const dl = saveToDownloads(buf, filename, { sessionId: sid, type: "pdf", sourceUrl: page.url() });
         result.download_id = dl.id;
       } catch {}
       return json(result);
@@ -33782,25 +34224,27 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_evaluate", "Execute JavaScript in the page context", { session_id: exports_external.string(), script: exports_external.string() }, async ({ session_id, script }) => {
+  server.tool("browser_evaluate", "Execute JavaScript in the page context", { session_id: exports_external.string().optional(), script: exports_external.string() }, async ({ session_id, script }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const result = await page.evaluate(script);
       return json({ result });
     } catch (e) {
-      return err(e);
+      return errWithScreenshot(e, session_id);
     }
   });
-  server.tool("browser_cookies_get", "Get cookies from the current session", { session_id: exports_external.string(), name: exports_external.string().optional(), domain: exports_external.string().optional() }, async ({ session_id, name, domain }) => {
+  server.tool("browser_cookies_get", "Get cookies from the current session", { session_id: exports_external.string().optional(), name: exports_external.string().optional(), domain: exports_external.string().optional() }, async ({ session_id, name, domain }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       return json({ cookies: await getCookies(page, { name, domain }) });
     } catch (e) {
       return err(e);
     }
   });
   server.tool("browser_cookies_set", "Set a cookie in the current session", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     name: exports_external.string(),
     value: exports_external.string(),
     domain: exports_external.string().optional(),
@@ -33810,7 +34254,8 @@ var init_mcp = __esm(async () => {
     secure: exports_external.boolean().optional().default(false)
   }, async ({ session_id, name, value, domain, path, expires, http_only, secure }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await setCookie(page, {
         name,
         value,
@@ -33826,27 +34271,30 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_cookies_clear", "Clear cookies from the current session", { session_id: exports_external.string(), name: exports_external.string().optional(), domain: exports_external.string().optional() }, async ({ session_id, name, domain }) => {
+  server.tool("browser_cookies_clear", "Clear cookies from the current session", { session_id: exports_external.string().optional(), name: exports_external.string().optional(), domain: exports_external.string().optional() }, async ({ session_id, name, domain }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await clearCookies(page, name || domain ? { name, domain } : undefined);
       return json({ cleared: true });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_storage_get", "Get localStorage or sessionStorage values", { session_id: exports_external.string(), key: exports_external.string().optional(), storage_type: exports_external.enum(["local", "session"]).optional().default("local") }, async ({ session_id, key, storage_type }) => {
+  server.tool("browser_storage_get", "Get localStorage or sessionStorage values", { session_id: exports_external.string().optional(), key: exports_external.string().optional(), storage_type: exports_external.enum(["local", "session"]).optional().default("local") }, async ({ session_id, key, storage_type }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const value = storage_type === "session" ? await getSessionStorage(page, key) : await getLocalStorage(page, key);
       return json({ value });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_storage_set", "Set a localStorage or sessionStorage value", { session_id: exports_external.string(), key: exports_external.string(), value: exports_external.string(), storage_type: exports_external.enum(["local", "session"]).optional().default("local") }, async ({ session_id, key, value, storage_type }) => {
+  server.tool("browser_storage_set", "Set a localStorage or sessionStorage value", { session_id: exports_external.string().optional(), key: exports_external.string(), value: exports_external.string(), storage_type: exports_external.enum(["local", "session"]).optional().default("local") }, async ({ session_id, key, value, storage_type }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       if (storage_type === "session") {
         await setSessionStorage(page, key, value);
       } else {
@@ -33857,28 +34305,30 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_network_log", "Get captured network requests for a session", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_network_log", "Get captured network requests for a session", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      if (!networkLogCleanup.has(session_id)) {
-        const page = getSessionPage(session_id);
-        const cleanup = enableNetworkLogging(page, session_id);
-        networkLogCleanup.set(session_id, cleanup);
+      const sid = resolveSessionId(session_id);
+      if (!networkLogCleanup.has(sid)) {
+        const page = getSessionPage(sid);
+        const cleanup = enableNetworkLogging(page, sid);
+        networkLogCleanup.set(sid, cleanup);
       }
-      const log = getNetworkLog(session_id);
+      const log = getNetworkLog(sid);
       return json({ requests: log, count: log.length });
     } catch (e) {
       return err(e);
     }
   });
   server.tool("browser_network_intercept", "Add a network interception rule", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     pattern: exports_external.string(),
     action: exports_external.enum(["block", "modify", "log"]),
     response_status: exports_external.number().optional(),
     response_body: exports_external.string().optional()
   }, async ({ session_id, pattern, action, response_status, response_body }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await addInterceptRule(page, {
         pattern,
         action,
@@ -33889,27 +34339,29 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_har_start", "Start HAR capture for a session", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_har_start", "Start HAR capture for a session", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const capture = startHAR(page);
-      harCaptures.set(session_id, capture);
+      harCaptures.set(sid, capture);
       return json({ started: true });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_har_stop", "Stop HAR capture and return the HAR data", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_har_stop", "Stop HAR capture and return the HAR data", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const capture = harCaptures.get(session_id);
+      const sid = resolveSessionId(session_id);
+      const capture = harCaptures.get(sid);
       if (!capture)
         return err(new Error("No active HAR capture for this session"));
       const har = capture.stop();
-      harCaptures.delete(session_id);
+      harCaptures.delete(sid);
       let download_id;
       try {
         const harBuf = Buffer.from(JSON.stringify(har, null, 2));
-        const dl = saveToDownloads(harBuf, `capture-${Date.now()}.har`, { sessionId: session_id, type: "har" });
+        const dl = saveToDownloads(harBuf, `capture-${Date.now()}.har`, { sessionId: sid, type: "har" });
         download_id = dl.id;
       } catch {}
       return json({ har, entry_count: har.log.entries.length, download_id });
@@ -33917,32 +34369,35 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_performance", "Get performance metrics for the current page", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_performance", "Get performance metrics for the current page", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const metrics = await getPerformanceMetrics(page);
       return json({ metrics });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_console_log", "Get captured console messages for a session", { session_id: exports_external.string(), level: exports_external.enum(["log", "warn", "error", "debug", "info"]).optional() }, async ({ session_id, level }) => {
+  server.tool("browser_console_log", "Get captured console messages for a session", { session_id: exports_external.string().optional(), level: exports_external.enum(["log", "warn", "error", "debug", "info"]).optional() }, async ({ session_id, level }) => {
     try {
-      if (!consoleCaptureCleanup.has(session_id)) {
-        const page = getSessionPage(session_id);
-        const cleanup = enableConsoleCapture(page, session_id);
-        consoleCaptureCleanup.set(session_id, cleanup);
+      const sid = resolveSessionId(session_id);
+      if (!consoleCaptureCleanup.has(sid)) {
+        const page = getSessionPage(sid);
+        const cleanup = enableConsoleCapture(page, sid);
+        consoleCaptureCleanup.set(sid, cleanup);
       }
-      const messages = getConsoleLog(session_id, level);
+      const messages = getConsoleLog(sid, level);
       return json({ messages, count: messages.length });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_record_start", "Start recording actions in a session", { session_id: exports_external.string(), name: exports_external.string(), project_id: exports_external.string().optional() }, async ({ session_id, name }) => {
+  server.tool("browser_record_start", "Start recording actions in a session", { session_id: exports_external.string().optional(), name: exports_external.string(), project_id: exports_external.string().optional() }, async ({ session_id, name }) => {
     try {
-      const page = getSessionPage(session_id);
-      const recording = startRecording(session_id, name, page.url());
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
+      const recording = startRecording(sid, name, page.url());
       return json({ recording_id: recording.id, name: recording.name });
     } catch (e) {
       return err(e);
@@ -33970,9 +34425,10 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_record_replay", "Replay a recorded sequence in a session", { session_id: exports_external.string(), recording_id: exports_external.string() }, async ({ session_id, recording_id }) => {
+  server.tool("browser_record_replay", "Replay a recorded sequence in a session", { session_id: exports_external.string().optional(), recording_id: exports_external.string() }, async ({ session_id, recording_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const result = await replayRecording(recording_id, page);
       return json(result);
     } catch (e) {
@@ -34010,7 +34466,7 @@ var init_mcp = __esm(async () => {
   server.tool("browser_register_agent", "Register an agent with the browser service", {
     name: exports_external.string(),
     description: exports_external.string().optional(),
-    session_id: exports_external.string().optional(),
+    session_id: exports_external.string().optional().optional(),
     project_id: exports_external.string().optional(),
     working_dir: exports_external.string().optional()
   }, async ({ name, description, session_id, project_id, working_dir }) => {
@@ -34051,9 +34507,10 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_scroll_and_screenshot", "Scroll the page and take a screenshot in one call. Saves 3 separate tool calls.", { session_id: exports_external.string(), direction: exports_external.enum(["up", "down", "left", "right"]).optional().default("down"), amount: exports_external.number().optional().default(500), wait_ms: exports_external.number().optional().default(300) }, async ({ session_id, direction, amount, wait_ms }) => {
+  server.tool("browser_scroll_and_screenshot", "Scroll the page and take a screenshot in one call. Saves 3 separate tool calls.", { session_id: exports_external.string().optional(), direction: exports_external.enum(["up", "down", "left", "right"]).optional().default("down"), amount: exports_external.number().optional().default(500), wait_ms: exports_external.number().optional().default(300) }, async ({ session_id, direction, amount, wait_ms }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await scroll(page, direction, amount);
       await new Promise((r) => setTimeout(r, wait_ms));
       const result = await takeScreenshot(page, { maxWidth: 1280, track: true });
@@ -34068,9 +34525,10 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_wait_for_navigation", "Wait for URL change after a click or action. Returns the new URL and title.", { session_id: exports_external.string(), timeout: exports_external.number().optional().default(30000), url_pattern: exports_external.string().optional() }, async ({ session_id, timeout, url_pattern }) => {
+  server.tool("browser_wait_for_navigation", "Wait for URL change after a click or action. Returns the new URL and title.", { session_id: exports_external.string().optional(), timeout: exports_external.number().optional().default(30000), url_pattern: exports_external.string().optional() }, async ({ session_id, timeout, url_pattern }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const start = Date.now();
       if (url_pattern) {
         await page.waitForURL(url_pattern, { timeout });
@@ -34092,16 +34550,63 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_session_rename", "Rename a browser session", { session_id: exports_external.string(), name: exports_external.string() }, async ({ session_id, name }) => {
+  server.tool("browser_session_rename", "Rename a browser session", { session_id: exports_external.string().optional(), name: exports_external.string() }, async ({ session_id, name }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      return json({ session: renameSession2(sid, name) });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_session_lock", "Lock a session so only the specified agent can use it", { session_id: exports_external.string().optional(), agent_id: exports_external.string() }, async ({ session_id, agent_id }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      const { lockSession: lockSession2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+      return json({ session: lockSession2(sid, agent_id) });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_session_unlock", "Unlock a session", { session_id: exports_external.string().optional(), agent_id: exports_external.string().optional() }, async ({ session_id, agent_id }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      const { unlockSession: unlockSession2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+      return json({ session: unlockSession2(sid, agent_id) });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_session_transfer", "Transfer session ownership to another agent", { session_id: exports_external.string().optional(), to_agent_id: exports_external.string() }, async ({ session_id, to_agent_id }) => {
     try {
-      return json({ session: renameSession2(session_id, name) });
+      const sid = resolveSessionId(session_id);
+      const { transferSession: transferSession2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+      return json({ session: transferSession2(sid, to_agent_id) });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_click_text", "Click an element by its visible text content", { session_id: exports_external.string(), text: exports_external.string(), exact: exports_external.boolean().optional().default(false), timeout: exports_external.number().optional() }, async ({ session_id, text, exact, timeout }) => {
+  server.tool("browser_session_tag", "Add a tag to a session for categorization (e.g. qa, scraping, monitoring)", { session_id: exports_external.string().optional(), tag: exports_external.string() }, async ({ session_id, tag }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const { addSessionTag: addSessionTag2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+      return json({ tags: addSessionTag2(sid, tag) });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_session_untag", "Remove a tag from a session", { session_id: exports_external.string().optional(), tag: exports_external.string() }, async ({ session_id, tag }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      const { removeSessionTag: removeSessionTag2 } = await Promise.resolve().then(() => (init_sessions(), exports_sessions));
+      return json({ tags: removeSessionTag2(sid, tag) });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_click_text", "Click an element by its visible text content", { session_id: exports_external.string().optional(), text: exports_external.string(), exact: exports_external.boolean().optional().default(false), timeout: exports_external.number().optional() }, async ({ session_id, text, exact, timeout }) => {
+    try {
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       await clickText(page, text, { exact, timeout });
       return json({ clicked: text });
     } catch (e) {
@@ -34109,21 +34614,23 @@ var init_mcp = __esm(async () => {
     }
   });
   server.tool("browser_fill_form", "Fill multiple form fields in one call. Fields map: { selector: value }. Handles text, checkboxes, selects.", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     fields: exports_external.record(exports_external.union([exports_external.string(), exports_external.boolean()])),
     submit_selector: exports_external.string().optional()
   }, async ({ session_id, fields, submit_selector }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const result = await fillForm(page, fields, submit_selector);
       return json(result);
     } catch (e) {
-      return err(e);
+      return errWithScreenshot(e, session_id);
     }
   });
-  server.tool("browser_wait_for_text", "Wait until specific text appears on the page", { session_id: exports_external.string(), text: exports_external.string(), timeout: exports_external.number().optional().default(1e4), exact: exports_external.boolean().optional().default(false) }, async ({ session_id, text, timeout, exact }) => {
+  server.tool("browser_wait_for_text", "Wait until specific text appears on the page", { session_id: exports_external.string().optional(), text: exports_external.string(), timeout: exports_external.number().optional().default(1e4), exact: exports_external.boolean().optional().default(false) }, async ({ session_id, text, timeout, exact }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const start = Date.now();
       await waitForText(page, text, { timeout, exact });
       return json({ found: true, elapsed_ms: Date.now() - start });
@@ -34131,46 +34638,51 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_element_exists", "Check if a selector exists on the page (no throw, returns boolean)", { session_id: exports_external.string(), selector: exports_external.string(), check_visible: exports_external.boolean().optional().default(false) }, async ({ session_id, selector, check_visible }) => {
+  server.tool("browser_element_exists", "Check if a selector exists on the page (no throw, returns boolean)", { session_id: exports_external.string().optional(), selector: exports_external.string(), check_visible: exports_external.boolean().optional().default(false) }, async ({ session_id, selector, check_visible }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       return json(await elementExists(page, selector, { visible: check_visible }));
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_get_page_info", "Get a full page summary in one call: url, title, meta tags, link/image/form counts, text length", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_get_page_info", "Get a full page summary in one call: url, title, meta tags, link/image/form counts, text length", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const info = await getPageInfo(page);
-      const errors2 = getConsoleLog(session_id, "error");
+      const errors2 = getConsoleLog(sid, "error");
       info.has_console_errors = errors2.length > 0;
       return json(info);
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_has_errors", "Quick check: does the session have any console errors?", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_has_errors", "Quick check: does the session have any console errors?", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const errors2 = getConsoleLog(session_id, "error");
+      const sid = resolveSessionId(session_id);
+      const errors2 = getConsoleLog(sid, "error");
       return json({ has_errors: errors2.length > 0, error_count: errors2.length, errors: errors2 });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_clear_errors", "Clear console error log for a session", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_clear_errors", "Clear console error log for a session", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
+      const sid = resolveSessionId(session_id);
       const { clearConsoleLog: clearConsoleLog2 } = await Promise.resolve().then(() => (init_console_log(), exports_console_log));
-      clearConsoleLog2(session_id);
+      clearConsoleLog2(sid);
       return json({ cleared: true });
     } catch (e) {
       return err(e);
     }
   });
   activeWatchHandles2 = new Map;
-  server.tool("browser_watch_start", "Start watching a page for DOM changes", { session_id: exports_external.string(), selector: exports_external.string().optional(), interval_ms: exports_external.number().optional().default(500), max_changes: exports_external.number().optional().default(50) }, async ({ session_id, selector, interval_ms, max_changes }) => {
+  server.tool("browser_watch_start", "Start watching a page for DOM changes", { session_id: exports_external.string().optional(), selector: exports_external.string().optional(), interval_ms: exports_external.number().optional().default(500), max_changes: exports_external.number().optional().default(50) }, async ({ session_id, selector, interval_ms, max_changes }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const handle = watchPage(page, { selector, intervalMs: interval_ms, maxChanges: max_changes });
       activeWatchHandles2.set(handle.id, handle);
       return json({ watch_id: handle.id });
@@ -34197,7 +34709,7 @@ var init_mcp = __esm(async () => {
   });
   server.tool("browser_gallery_list", "List screenshot gallery entries with optional filters", {
     project_id: exports_external.string().optional(),
-    session_id: exports_external.string().optional(),
+    session_id: exports_external.string().optional().optional(),
     tag: exports_external.string().optional(),
     is_favorite: exports_external.boolean().optional(),
     date_from: exports_external.string().optional(),
@@ -34285,14 +34797,14 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_downloads_list", "List all files in the downloads folder", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
+  server.tool("browser_downloads_list", "List all files in the downloads folder", { session_id: exports_external.string().optional().optional() }, async ({ session_id }) => {
     try {
       return json({ downloads: listDownloads(session_id), count: listDownloads(session_id).length });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_downloads_get", "Get a downloaded file by id, returning base64 content and metadata", { id: exports_external.string(), session_id: exports_external.string().optional() }, async ({ id, session_id }) => {
+  server.tool("browser_downloads_get", "Get a downloaded file by id, returning base64 content and metadata", { id: exports_external.string(), session_id: exports_external.string().optional().optional() }, async ({ id, session_id }) => {
     try {
       const file = getDownload(id, session_id);
       if (!file)
@@ -34303,7 +34815,7 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_downloads_delete", "Delete a downloaded file by id", { id: exports_external.string(), session_id: exports_external.string().optional() }, async ({ id, session_id }) => {
+  server.tool("browser_downloads_delete", "Delete a downloaded file by id", { id: exports_external.string(), session_id: exports_external.string().optional().optional() }, async ({ id, session_id }) => {
     try {
       const deleted = deleteDownload(id, session_id);
       return json({ deleted });
@@ -34318,7 +34830,7 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_downloads_export", "Copy a downloaded file to a target path", { id: exports_external.string(), target_path: exports_external.string(), session_id: exports_external.string().optional() }, async ({ id, target_path, session_id }) => {
+  server.tool("browser_downloads_export", "Copy a downloaded file to a target path", { id: exports_external.string(), target_path: exports_external.string(), session_id: exports_external.string().optional().optional() }, async ({ id, target_path, session_id }) => {
     try {
       const finalPath = exportToPath(id, target_path, session_id);
       return json({ path: finalPath });
@@ -34343,12 +34855,13 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_snapshot_diff", "Take a new accessibility snapshot and diff it against the last snapshot for this session. Shows added/removed/modified interactive elements.", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_snapshot_diff", "Take a new accessibility snapshot and diff it against the last snapshot for this session. Shows added/removed/modified interactive elements.", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
-      const before = getLastSnapshot(session_id);
-      const after = await takeSnapshot(page, session_id);
-      setLastSnapshot(session_id, after);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
+      const before = getLastSnapshot(sid);
+      const after = await takeSnapshot(page, sid);
+      setLastSnapshot(sid, after);
       if (!before) {
         return json({
           message: "No previous snapshot \u2014 returning current snapshot only.",
@@ -34371,12 +34884,13 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_session_stats", "Get session info and estimated token usage (based on network log, console log, and gallery entry sizes).", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_session_stats", "Get session info and estimated token usage (based on network log, console log, and gallery entry sizes).", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const session = getSession2(session_id);
-      const networkLog = getNetworkLog(session_id);
-      const consoleLog = getConsoleLog(session_id);
-      const galleryEntries = listEntries({ sessionId: session_id, limit: 1000 });
+      const sid = resolveSessionId(session_id);
+      const session = getSession2(sid);
+      const networkLog = getNetworkLog(sid);
+      const consoleLog = getConsoleLog(sid);
+      const galleryEntries = listEntries({ sessionId: sid, limit: 1000 });
       let totalChars = 0;
       for (const req of networkLog) {
         totalChars += (req.url?.length ?? 0) + (req.request_headers?.length ?? 0) + (req.response_headers?.length ?? 0) + (req.request_body?.length ?? 0);
@@ -34388,7 +34902,7 @@ var init_mcp = __esm(async () => {
         totalChars += (entry.url?.length ?? 0) + (entry.title?.length ?? 0) + (entry.notes?.length ?? 0) + (entry.tags?.join(",").length ?? 0);
       }
       const estimatedTokens = Math.ceil(totalChars / 4);
-      const tokenBudget = getTokenBudget(session_id);
+      const tokenBudget = getTokenBudget(sid);
       return json({
         session,
         network_request_count: networkLog.length,
@@ -34402,52 +34916,57 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_tab_new", "Open a new tab in the session's browser context, optionally navigating to a URL", { session_id: exports_external.string(), url: exports_external.string().optional() }, async ({ session_id, url }) => {
+  server.tool("browser_tab_new", "Open a new tab in the session's browser context, optionally navigating to a URL", { session_id: exports_external.string().optional(), url: exports_external.string().optional() }, async ({ session_id, url }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const tab = await newTab(page, url);
       return json(tab);
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_tab_list", "List all open tabs in the session's browser context", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_tab_list", "List all open tabs in the session's browser context", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const tabs = await listTabs(page);
       return json({ tabs, count: tabs.length });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_tab_switch", "Switch to a different tab by index. Updates the session's active page.", { session_id: exports_external.string(), tab_id: exports_external.number() }, async ({ session_id, tab_id }) => {
+  server.tool("browser_tab_switch", "Switch to a different tab by index. Updates the session's active page.", { session_id: exports_external.string().optional(), tab_id: exports_external.number() }, async ({ session_id, tab_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const result = await switchTab(page, tab_id);
-      setSessionPage(session_id, result.page);
+      setSessionPage(sid, result.page);
       return json(result.tab);
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_tab_close", "Close a tab by index. Cannot close the last tab.", { session_id: exports_external.string(), tab_id: exports_external.number() }, async ({ session_id, tab_id }) => {
+  server.tool("browser_tab_close", "Close a tab by index. Cannot close the last tab.", { session_id: exports_external.string().optional(), tab_id: exports_external.number() }, async ({ session_id, tab_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const context = page.context();
       const result = await closeTab(page, tab_id);
       const remainingPages = context.pages();
       const newActivePage = remainingPages[result.active_tab.index];
       if (newActivePage) {
-        setSessionPage(session_id, newActivePage);
+        setSessionPage(sid, newActivePage);
       }
       return json(result);
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_handle_dialog", "Accept or dismiss a pending dialog (alert, confirm, prompt). Handles the oldest pending dialog.", { session_id: exports_external.string(), action: exports_external.enum(["accept", "dismiss"]), prompt_text: exports_external.string().optional() }, async ({ session_id, action, prompt_text }) => {
+  server.tool("browser_handle_dialog", "Accept or dismiss a pending dialog (alert, confirm, prompt). Handles the oldest pending dialog.", { session_id: exports_external.string().optional(), action: exports_external.enum(["accept", "dismiss"]), prompt_text: exports_external.string().optional() }, async ({ session_id, action, prompt_text }) => {
     try {
-      const result = await handleDialog(session_id, action, prompt_text);
+      const sid = resolveSessionId(session_id);
+      const result = await handleDialog(sid, action, prompt_text);
       if (!result.handled)
         return err(new Error("No pending dialogs for this session"));
       return json(result);
@@ -34455,28 +34974,31 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_get_dialogs", "Get all pending dialogs for a session", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_get_dialogs", "Get all pending dialogs for a session", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const dialogs = getDialogs(session_id);
+      const sid = resolveSessionId(session_id);
+      const dialogs = getDialogs(sid);
       return json({ dialogs, count: dialogs.length });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_profile_save", "Save cookies + localStorage from the current session as a named profile", { session_id: exports_external.string(), name: exports_external.string() }, async ({ session_id, name }) => {
+  server.tool("browser_profile_save", "Save cookies + localStorage from the current session as a named profile", { session_id: exports_external.string().optional(), name: exports_external.string() }, async ({ session_id, name }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const info = await saveProfile(page, name);
       return json(info);
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_profile_load", "Load a saved profile and apply cookies + localStorage to the current session", { session_id: exports_external.string().optional(), name: exports_external.string() }, async ({ session_id, name }) => {
+  server.tool("browser_profile_load", "Load a saved profile and apply cookies + localStorage to the current session", { session_id: exports_external.string().optional().optional(), name: exports_external.string() }, async ({ session_id, name }) => {
     try {
       const profileData = loadProfile(name);
       if (session_id) {
-        const page = getSessionPage(session_id);
+        const sid = resolveSessionId(session_id);
+        const page = getSessionPage(sid);
         const applied = await applyProfile(page, profileData);
         return json({ ...applied, profile: name });
       }
@@ -34614,7 +35136,13 @@ var init_mcp = __esm(async () => {
           { tool: "browser_session_close", description: "Close a session" },
           { tool: "browser_session_get_by_name", description: "Get session by name" },
           { tool: "browser_session_rename", description: "Rename a session" },
+          { tool: "browser_session_lock", description: "Lock a session for an agent" },
+          { tool: "browser_session_unlock", description: "Unlock a session" },
+          { tool: "browser_session_transfer", description: "Transfer session to another agent" },
+          { tool: "browser_session_tag", description: "Add a tag to a session" },
+          { tool: "browser_session_untag", description: "Remove a tag from a session" },
           { tool: "browser_session_stats", description: "Get session stats and token usage" },
+          { tool: "browser_session_timeline", description: "Get chronological action log" },
           { tool: "browser_tab_new", description: "Open a new tab" },
           { tool: "browser_tab_list", description: "List all open tabs" },
           { tool: "browser_tab_switch", description: "Switch to a tab by index" },
@@ -34652,18 +35180,19 @@ var init_mcp = __esm(async () => {
     }
   });
   server.tool("browser_scroll_to_element", "Scroll an element into view (by ref or selector) then optionally take a screenshot of it. Replaces scroll + wait + screenshot pattern.", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     selector: exports_external.string().optional(),
     ref: exports_external.string().optional(),
     screenshot: exports_external.boolean().optional().default(true),
     wait_ms: exports_external.number().optional().default(200)
   }, async ({ session_id, selector, ref, screenshot: doScreenshot, wait_ms }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       let locator;
       if (ref) {
         const { getRefLocator: getRefLocator2 } = await Promise.resolve().then(() => (init_snapshot(), exports_snapshot));
-        locator = getRefLocator2(page, session_id, ref);
+        locator = getRefLocator2(page, sid, ref);
       } else if (selector) {
         locator = page.locator(selector).first();
       } else {
@@ -34688,11 +35217,12 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_check", "RECOMMENDED FIRST CALL: one-shot page summary \u2014 url, title, errors, performance, thumbnail, refs. Replaces 4+ separate tool calls.", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_check", "RECOMMENDED FIRST CALL: one-shot page summary \u2014 url, title, errors, performance, thumbnail, refs. Replaces 4+ separate tool calls.", { session_id: exports_external.string().optional() }, async ({ session_id }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const info = await getPageInfo(page);
-      const errors2 = getConsoleLog(session_id, "error");
+      const errors2 = getConsoleLog(sid, "error");
       info.has_console_errors = errors2.length > 0;
       let perf = {};
       try {
@@ -34706,8 +35236,8 @@ var init_mcp = __esm(async () => {
       let snapshot_refs = "";
       let interactive_count = 0;
       try {
-        const snap = await takeSnapshot(page, session_id);
-        setLastSnapshot(session_id, snap);
+        const snap = await takeSnapshot(page, sid);
+        setLastSnapshot(sid, snap);
         interactive_count = snap.interactive_count;
         snapshot_refs = Object.entries(snap.refs).slice(0, 30).map(([ref, i]) => `${i.role}:${i.name.slice(0, 50)} [${ref}]`).join(", ");
       } catch {}
@@ -34716,9 +35246,10 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_secrets_login", "Login to a service using credentials from open-secrets vault or ~/.secrets. One call replaces 10+ tool calls.", { session_id: exports_external.string(), service: exports_external.string(), login_url: exports_external.string().optional(), save_profile: exports_external.boolean().optional().default(true) }, async ({ session_id, service, login_url, save_profile }) => {
+  server.tool("browser_secrets_login", "Login to a service using credentials from open-secrets vault or ~/.secrets. One call replaces 10+ tool calls.", { session_id: exports_external.string().optional(), service: exports_external.string(), login_url: exports_external.string().optional(), save_profile: exports_external.boolean().optional().default(true) }, async ({ session_id, service, login_url, save_profile }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const { getCredentials: getCredentials2, loginWithCredentials: loginWithCredentials2 } = await Promise.resolve().then(() => (init_auth(), exports_auth));
       const creds = await getCredentials2(service);
       if (!creds)
@@ -34732,9 +35263,10 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_remember", "Store page facts in open-mementos for future recall. Agents skip re-scraping on repeat visits.", { session_id: exports_external.string(), facts: exports_external.record(exports_external.unknown()), tags: exports_external.array(exports_external.string()).optional() }, async ({ session_id, facts, tags }) => {
+  server.tool("browser_remember", "Store page facts in open-mementos for future recall. Agents skip re-scraping on repeat visits.", { session_id: exports_external.string().optional(), facts: exports_external.record(exports_external.unknown()), tags: exports_external.array(exports_external.string()).optional() }, async ({ session_id, facts, tags }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const { rememberPage: rememberPage2 } = await Promise.resolve().then(() => (init_page_memory(), exports_page_memory));
       const url = page.url();
       await rememberPage2(url, facts, tags);
@@ -34752,12 +35284,13 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_session_announce", "Announce to other agents via open-conversations what this session is browsing.", { session_id: exports_external.string(), message: exports_external.string().optional() }, async ({ session_id, message }) => {
+  server.tool("browser_session_announce", "Announce to other agents via open-conversations what this session is browsing.", { session_id: exports_external.string().optional(), message: exports_external.string().optional() }, async ({ session_id, message }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const { announceNavigation: announceNavigation2 } = await Promise.resolve().then(() => (init_coordination(), exports_coordination));
       const url = page.url();
-      await announceNavigation2(url, session_id);
+      await announceNavigation2(url, sid);
       return json({ announced: true, url, message });
     } catch (e) {
       return err(e);
@@ -34797,9 +35330,10 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_skill_run", "Run a pre-built browser skill (login, extract-pricing, extract-nav-links, monitor-price, get-metadata). One call replaces 5\u201315 tool calls.", { session_id: exports_external.string(), skill: exports_external.string(), params: exports_external.record(exports_external.unknown()).optional().default({}) }, async ({ session_id, skill, params }) => {
+  server.tool("browser_skill_run", "Run a pre-built browser skill (login, extract-pricing, extract-nav-links, monitor-price, get-metadata). One call replaces 5\u201315 tool calls.", { session_id: exports_external.string().optional(), skill: exports_external.string(), params: exports_external.record(exports_external.unknown()).optional().default({}) }, async ({ session_id, skill, params }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const { runBrowserSkill: runBrowserSkill2 } = await Promise.resolve().then(() => (init_skills_runner(), exports_skills_runner));
       return json(await runBrowserSkill2(skill, params, page));
     } catch (e) {
@@ -34815,7 +35349,7 @@ var init_mcp = __esm(async () => {
     }
   });
   server.tool("browser_batch", "Execute multiple browser actions in one call. Returns final snapshot. Eliminates 80% of round trips for multi-step flows.", {
-    session_id: exports_external.string(),
+    session_id: exports_external.string().optional(),
     actions: exports_external.array(exports_external.object({
       tool: exports_external.string(),
       args: exports_external.record(exports_external.unknown()).optional().default({})
@@ -34823,12 +35357,13 @@ var init_mcp = __esm(async () => {
   }, async ({ session_id, actions }) => {
     try {
       const results = [];
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const t0 = Date.now();
       for (const action of actions) {
         try {
           const toolName = action.tool.replace(/^browser_/, "");
-          const args = { session_id, ...action.args };
+          const args = { session_id: sid, ...action.args };
           switch (toolName) {
             case "navigate":
               await navigate(page, action.args.url);
@@ -34837,7 +35372,7 @@ var init_mcp = __esm(async () => {
             case "click":
               if (args.ref) {
                 const { clickRef: clickRef2 } = await Promise.resolve().then(() => (init_actions(), exports_actions));
-                await clickRef2(page, session_id, args.ref);
+                await clickRef2(page, sid, args.ref);
               } else if (args.selector)
                 await page.click(args.selector);
               results.push({ tool: action.tool, success: true });
@@ -34845,7 +35380,7 @@ var init_mcp = __esm(async () => {
             case "type":
               if (args.ref && args.text) {
                 const { typeRef: typeRef2 } = await Promise.resolve().then(() => (init_actions(), exports_actions));
-                await typeRef2(page, session_id, args.ref, args.text);
+                await typeRef2(page, sid, args.ref, args.text);
               } else if (args.selector && args.text)
                 await page.fill(args.selector, args.text);
               results.push({ tool: action.tool, success: true });
@@ -34885,7 +35420,7 @@ var init_mcp = __esm(async () => {
       }
       let final_snapshot = {};
       try {
-        const snap = await takeSnapshot(page, session_id);
+        const snap = await takeSnapshot(page, sid);
         final_snapshot = {
           refs: Object.fromEntries(Object.entries(snap.refs).slice(0, 20)),
           interactive_count: snap.interactive_count
@@ -34982,18 +35517,20 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_task", "Execute a natural language browser task autonomously using Claude Haiku. Returns result + steps taken.", { session_id: exports_external.string(), task: exports_external.string(), max_steps: exports_external.number().optional().default(10), model: exports_external.string().optional() }, async ({ session_id, task, max_steps, model }) => {
+  server.tool("browser_task", "Execute a natural language browser task autonomously using Claude Haiku. Returns result + steps taken.", { session_id: exports_external.string().optional(), task: exports_external.string(), max_steps: exports_external.number().optional().default(10), model: exports_external.string().optional() }, async ({ session_id, task, max_steps, model }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const { executeBrowserTask: executeBrowserTask2 } = await Promise.resolve().then(() => (init_ai_task(), exports_ai_task));
-      return json(await executeBrowserTask2(page, task, { maxSteps: max_steps, model, sessionId: session_id }));
+      return json(await executeBrowserTask2(page, task, { maxSteps: max_steps, model, sessionId: sid }));
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_assert", `Assert page conditions in one call. Conditions: 'url contains X', 'text:"Y" is visible', 'element:"#id" exists', 'count:"a" > 10', 'title contains Z'. Chain with AND.`, { session_id: exports_external.string(), condition: exports_external.string() }, async ({ session_id, condition }) => {
+  server.tool("browser_assert", `Assert page conditions in one call. Conditions: 'url contains X', 'text:"Y" is visible', 'element:"#id" exists', 'count:"a" > 10', 'title contains Z'. Chain with AND.`, { session_id: exports_external.string().optional(), condition: exports_external.string() }, async ({ session_id, condition }) => {
     try {
-      const page = getSessionPage(session_id);
+      const sid = resolveSessionId(session_id);
+      const page = getSessionPage(sid);
       const checks = [];
       let passed = true;
       for (const part of condition.split(/\s+AND\s+/i)) {
@@ -35432,26 +35969,66 @@ import chalk from "chalk";
 var pkg = JSON.parse(readFileSync9(join15(import.meta.dir, "../../package.json"), "utf8"));
 var program2 = new Command;
 program2.name("browser").description("@hasna/browser \u2014 general-purpose browser agent CLI").version(pkg.version);
-program2.command("navigate <url>").description("Navigate to a URL and optionally take a screenshot").option("--engine <engine>", "Browser engine: playwright|cdp|lightpanda|auto", "auto").option("--screenshot", "Take a screenshot after navigation").option("--extract", "Extract page text after navigation").option("--headless", "Run in headless mode (default: true)", true).action(async (url, opts) => {
-  const { session, page } = await createSession2({ engine: opts.engine, headless: true });
-  console.log(chalk.gray(`Session: ${session.id} (${session.engine})`));
+program2.command("navigate <url>").description("Navigate to a URL and optionally take a screenshot").option("--engine <engine>", "Browser engine: playwright|cdp|lightpanda|auto", "auto").option("--screenshot", "Take a screenshot after navigation").option("--extract", "Extract page text after navigation").option("--headed", "Run in headed (visible) mode").option("--json", "Output as JSON").action(async (url, opts) => {
+  const { session, page } = await createSession2({ engine: opts.engine, headless: !opts.headed });
   await navigate(page, url);
   const title = await page.title();
-  console.log(chalk.green(`\u2713 Navigated to: ${url}`));
-  console.log(chalk.blue(`  Title: ${title}`));
+  let screenshotPath;
   if (opts.screenshot) {
     const result = await takeScreenshot(page);
-    console.log(chalk.blue(`  Screenshot: ${result.path}`));
+    screenshotPath = result.path;
   }
+  let text;
   if (opts.extract) {
-    const text = await getText(page);
-    console.log(chalk.white(`
+    text = await getText(page);
+  }
+  if (opts.json) {
+    const output = { session_id: session.id, engine: session.engine, url, title };
+    if (screenshotPath)
+      output.screenshot = screenshotPath;
+    if (text)
+      output.text = text.slice(0, 500);
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(chalk.gray(`Session: ${session.id} (${session.engine})`));
+    console.log(chalk.green(`\u2713 Navigated to: ${url}`));
+    console.log(chalk.blue(`  Title: ${title}`));
+    if (screenshotPath)
+      console.log(chalk.blue(`  Screenshot: ${screenshotPath}`));
+    if (text)
+      console.log(chalk.white(`
 ${text.slice(0, 500)}...`));
   }
   await closeSession2(session.id);
 });
-program2.command("screenshot <url>").description("Navigate to a URL and take a screenshot").option("--engine <engine>", "Browser engine", "auto").option("--selector <selector>", "CSS selector for element screenshot").option("--full-page", "Capture full page").option("--format <format>", "Image format: png|jpeg|webp", "png").action(async (url, opts) => {
-  const { session, page } = await createSession2({ engine: opts.engine, headless: true });
+program2.command("check <url>").description("One-liner page health check: navigate, screenshot, extract info, check errors").option("--engine <engine>", "Browser engine", "auto").option("--headed", "Run in headed (visible) mode").option("--json", "Output as JSON").action(async (url, opts) => {
+  const { session, page } = await createSession2({ engine: opts.engine, headless: !opts.headed });
+  await navigate(page, url);
+  const title = await page.title();
+  const currentUrl = page.url();
+  const text = await getText(page);
+  const links = await getLinks(page);
+  const result = await takeScreenshot(page);
+  const summary = {
+    url: currentUrl,
+    title,
+    text_length: text.length,
+    links_count: links.length,
+    screenshot: result.path,
+    screenshot_size_kb: +(result.size_bytes / 1024).toFixed(1)
+  };
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(chalk.green(`\u2713 ${title}`));
+    console.log(chalk.blue(`  URL: ${currentUrl}`));
+    console.log(chalk.gray(`  Text: ${text.length} chars, Links: ${links.length}`));
+    console.log(chalk.gray(`  Screenshot: ${result.path} (${summary.screenshot_size_kb} KB)`));
+  }
+  await closeSession2(session.id);
+});
+program2.command("screenshot <url>").description("Navigate to a URL and take a screenshot").option("--engine <engine>", "Browser engine", "auto").option("--selector <selector>", "CSS selector for element screenshot").option("--full-page", "Capture full page").option("--format <format>", "Image format: png|jpeg|webp", "png").option("--headed", "Run in headed (visible) mode").action(async (url, opts) => {
+  const { session, page } = await createSession2({ engine: opts.engine, headless: !opts.headed });
   await navigate(page, url);
   const result = await takeScreenshot(page, {
     selector: opts.selector,
@@ -35462,11 +36039,13 @@ program2.command("screenshot <url>").description("Navigate to a URL and take a s
   console.log(chalk.gray(`  Size: ${(result.size_bytes / 1024).toFixed(1)} KB`));
   await closeSession2(session.id);
 });
-program2.command("extract <url>").description("Extract content from a URL").option("--engine <engine>", "Browser engine", "auto").option("--selector <selector>", "CSS selector").option("--format <format>", "Format: text|html|links|table|structured", "text").action(async (url, opts) => {
-  const { session, page } = await createSession2({ engine: opts.engine, headless: true });
+program2.command("extract <url>").description("Extract content from a URL").option("--engine <engine>", "Browser engine", "auto").option("--selector <selector>", "CSS selector").option("--format <format>", "Format: text|html|links|table|structured", "text").option("--headed", "Run in headed (visible) mode").option("--json", "Output as JSON").action(async (url, opts) => {
+  const { session, page } = await createSession2({ engine: opts.engine, headless: !opts.headed });
   await navigate(page, url);
   const result = await extract(page, { format: opts.format, selector: opts.selector });
-  if (opts.format === "links" && result.links) {
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (opts.format === "links" && result.links) {
     result.links.forEach((l) => console.log(l));
   } else if (opts.format === "table" && result.table) {
     result.table.forEach((row) => console.log(row.join("\t")));
@@ -35475,8 +36054,8 @@ program2.command("extract <url>").description("Extract content from a URL").opti
   }
   await closeSession2(session.id);
 });
-program2.command("eval <url> <script>").description("Run JavaScript in a page context").option("--engine <engine>", "Browser engine", "auto").action(async (url, script, opts) => {
-  const { session, page } = await createSession2({ engine: opts.engine, headless: true });
+program2.command("eval <url> <script>").description("Run JavaScript in a page context").option("--engine <engine>", "Browser engine", "auto").option("--headed", "Run in headed (visible) mode").action(async (url, script, opts) => {
+  const { session, page } = await createSession2({ engine: opts.engine, headless: !opts.headed });
   await navigate(page, url);
   const result = await page.evaluate(script);
   console.log(JSON.stringify(result, null, 2));
@@ -35502,14 +36081,16 @@ ${result.errors.length} errors:`));
   }
 });
 var sessionCmd = program2.command("session").description("Manage browser sessions");
-sessionCmd.command("create").description("Create a new browser session").option("--engine <engine>", "Browser engine", "auto").option("--url <url>", "Start URL").action(async (opts) => {
-  const { session } = await createSession2({ engine: opts.engine, startUrl: opts.url });
+sessionCmd.command("create").description("Create a new browser session").option("--engine <engine>", "Browser engine", "auto").option("--url <url>", "Start URL").option("--headed", "Run in headed (visible) mode").action(async (opts) => {
+  const { session } = await createSession2({ engine: opts.engine, startUrl: opts.url, headless: !opts.headed });
   console.log(chalk.green(`\u2713 Session created`));
   console.log(JSON.stringify(session, null, 2));
 });
-sessionCmd.command("list").description("List all sessions").option("--status <status>", "Filter by status").action((opts) => {
+sessionCmd.command("list").description("List all sessions").option("--status <status>", "Filter by status").option("--json", "Output as JSON").action((opts) => {
   const sessions = listSessions2(opts.status ? { status: opts.status } : undefined);
-  if (sessions.length === 0) {
+  if (opts.json) {
+    console.log(JSON.stringify(sessions, null, 2));
+  } else if (sessions.length === 0) {
     console.log(chalk.gray("No sessions found"));
   } else {
     sessions.forEach((s) => console.log(`${s.id} [${s.status}] ${s.engine} ${s.start_url ?? ""}`));
@@ -35520,8 +36101,8 @@ sessionCmd.command("close <id>").description("Close a session").action(async (id
   console.log(chalk.green(`\u2713 Session closed: ${id}`));
 });
 var recordCmd = program2.command("record").description("Manage action recordings");
-recordCmd.command("start <name>").description("Start recording actions in a new session").option("--url <url>", "Start URL").option("--engine <engine>", "Browser engine", "auto").action(async (name, opts) => {
-  const { session } = await createSession2({ engine: opts.engine, startUrl: opts.url });
+recordCmd.command("start <name>").description("Start recording actions in a new session").option("--url <url>", "Start URL").option("--engine <engine>", "Browser engine", "auto").option("--headed", "Run in headed (visible) mode").action(async (name, opts) => {
+  const { session } = await createSession2({ engine: opts.engine, startUrl: opts.url, headless: !opts.headed });
   const recording = startRecording(session.id, name, opts.url);
   console.log(chalk.green(`\u2713 Recording started`));
   console.log(`  Recording ID: ${recording.id}`);
@@ -35532,8 +36113,8 @@ recordCmd.command("stop <recording_id>").description("Stop an active recording")
   console.log(chalk.green(`\u2713 Recording stopped: ${recording.name}`));
   console.log(`  Steps: ${recording.steps.length}`);
 });
-recordCmd.command("replay <recording_id>").description("Replay a recording in a new session").option("--url <url>", "Override start URL").option("--engine <engine>", "Browser engine", "auto").action(async (id, opts) => {
-  const { session, page } = await createSession2({ engine: opts.engine, startUrl: opts.url });
+recordCmd.command("replay <recording_id>").description("Replay a recording in a new session").option("--url <url>", "Override start URL").option("--engine <engine>", "Browser engine", "auto").option("--headed", "Run in headed (visible) mode").action(async (id, opts) => {
+  const { session, page } = await createSession2({ engine: opts.engine, startUrl: opts.url, headless: !opts.headed });
   const result = await replayRecording(id, page);
   console.log(result.success ? chalk.green("\u2713 Replay complete") : chalk.red("\u2717 Replay had errors"));
   console.log(`  Steps: ${result.steps_executed} executed, ${result.steps_failed} failed`);