browserzap 0.4.0 → 0.5.0

package/bridge-server/session-log.js

@@ -1,188 +1,188 @@
-/**
- * BrowserZap — session log: what every session did, for transparency and debugging.
- *
- * One JSON line per tool call or workflow step, appended to
- *   <config dir>/logs/YYYY-MM-DD.jsonl   (0600, kept 14 days)
- * by the MCP server (agent calls, agent-run workflows) and the bridge's panel
- * runner (workflows run from the side panel).
- *
- * Recorded: time, session and client, tool, the target as it was named, the
- * outcome (ok, state, error code), timing, and evidence useful for debugging
- * (waited-for-target time, click path, risk, navigation, where a workflow
- * stopped), plus the page as origin + path.
- *
- * Never recorded: typed values (only their length), parameter values (only
- * their names), URL query strings or fragments, page text, approval ids,
- * screenshots. Result summaries quote page content, so they are added only
- * with BROWSERZAP_LOG=verbose. BROWSERZAP_LOG=off disables the file.
- *
- * Read it with `npm run logs` (bridge-server/index.js --logs).
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const { configDir } = require('./secret');
-
-const KEEP_DAYS = 14;
-const MAX_DAY_BYTES = 20 * 1024 * 1024;
-const MAX_TEXT = 80;
-const EVIDENCE_KEYS = [
-  'waitedForTargetMs', 'clickVia', 'input', 'risk', 'navigated', 'urlChanged', 'domChanged', 'noObservableChange',
-  'expectationMet', 'verified', 'redirected', 'crossOrigin', 'reResolvedStaleRef', 'elapsedMs',
-  'workflow', 'version', 'stoppedAt', 'completedSteps', 'totalSteps', 'completedRuns',
-  // slow-server evidence (docs/AUDIT.md AU-02, AU-06, AU-07, AU-05)
-  'loaded', 'httpStatus', 'retryable', 'ttfbMs', 'domContentLoadedMs', 'loadMs', 'waitingFor', 'pageBusyMs', 'waitedForPersonMs',
-  // why a step was slow or failed (AU-12); slowestRequest is origin + path only. busyIndicator is page text: verbose only.
-  'likelyCause', 'slowestRequest', 'pendingRequests', 'readyState', 'slowSteps',
-];
-const PLAIN_ARGS = [
-  'key', 'direction', 'amount', 'timeoutMs', 'maxElements', 'includeText', 'maxTextChars', 'within', 'tabId',
-  'name', 'startAt', 'version', 'action', 'restoreVersion', 'limit', 'includeTab', 'waitMs', 'overwrite', 'keepValues',
-];
-
-const mode = () => (process.env.BROWSERZAP_LOG || 'standard').toLowerCase();
-const logDir = () => path.join(configDir(), 'logs');
-const dayFile = (date = new Date()) => path.join(logDir(), `${date.toISOString().slice(0, 10)}.jsonl`);
-const clip = (v) => (typeof v === 'string' && v.length > MAX_TEXT ? `${v.slice(0, MAX_TEXT)}…` : v);
-
-/** origin + path only: query strings and fragments often carry tokens or personal data. */
-function safeUrl(raw) {
-  if (typeof raw !== 'string' || !raw) return undefined;
-  if (raw.includes('{{')) return clip(raw.split(/[?#]/)[0]);
-  try {
-    const u = new URL(raw);
-    return `${u.origin}${u.pathname}`;
-  } catch {
-    return '(invalid url)';
-  }
-}
-
-function targetOf(target) {
-  if (!target || typeof target !== 'object') return undefined;
-  const out = {};
-  for (const key of ['ref', 'role', 'name', 'label', 'text', 'within']) if (typeof target[key] === 'string') out[key] = clip(target[key]);
-  if (typeof target.href === 'string') out.href = safeUrl(target.href) ?? clip(target.href);
-  return out;
-}
-
-/** What a call asked for, without values. */
-function describeArgs(args = {}) {
-  if (!args || typeof args !== 'object') return {};
-  const out = {};
-  if (args.target) out.target = targetOf(args.target);
-  if (args.expect && typeof args.expect === 'object') out.expect = Object.keys(args.expect);
-  if (args.url !== undefined) out.url = safeUrl(args.url);
-  if (args.value !== undefined) out.valueLength = String(args.value).length;
-  if (args.option && typeof args.option === 'object') out.option = Object.keys(args.option);
-  for (const key of PLAIN_ARGS) if (args[key] !== undefined && typeof args[key] !== 'object') out[key] = clip(args[key]);
-  if (args.params && typeof args.params === 'object') out.params = Object.keys(args.params);
-  if (Array.isArray(args.paramSets)) out.paramSets = args.paramSets.length;
-  if (Array.isArray(args.steps)) out.steps = args.steps.length;
-  if (args.approvalId) out.approval = true;
-  if (typeof args.message === 'string') out.messageLength = args.message.length;
-  return out;
-}
-
-/** What came back, without page text unless verbose. */
-function describeResult(env = {}) {
-  const out = { ok: env.ok === true, state: env.state };
-  if (env.error?.code) out.code = env.error.code;
-  const page = safeUrl(env.page?.url);
-  if (page) out.page = page;
-  const evidence = {};
-  for (const key of EVIDENCE_KEYS) if (env.evidence?.[key] !== undefined) evidence[key] = env.evidence[key];
-  if (Object.keys(evidence).length) out.evidence = evidence;
-  if (Array.isArray(env.candidates)) out.candidates = env.candidates.length;
-  if (mode() === 'verbose') {
-    if (env.evidence?.busyIndicator) (out.evidence ??= {}).busyIndicator = env.evidence.busyIndicator;
-    out.summary = env.summary;
-    if (env.nextAction) out.nextAction = env.nextAction;
-  }
-  return out;
-}
-
-let pruned = false;
-function prune() {
-  if (pruned) return;
-  pruned = true;
-  const cutoff = Date.now() - KEEP_DAYS * 86_400_000;
-  try {
-    for (const file of fs.readdirSync(logDir())) {
-      const day = Date.parse(file.slice(0, 10));
-      if (/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(file) && day < cutoff) fs.unlinkSync(path.join(logDir(), file));
-    }
-  } catch { /* nothing to prune */ }
-}
-
-/**
- * @param {{ session: string, client: () => string }} who
- * @returns {{ write(entry: object): void, file(): string }}
- */
-/**
- * One file call per entry (audit AU-21): the folder is created once per
- * process and per folder, and the day file's size is read once per day file
- * and then tracked in memory.
- */
-let madeDir = null;
-function createSessionLog({ session, client }) {
-  let full = false;
-  let current = { file: null, size: 0 };
-  function write(entry) {
-    if (mode() === 'off') return;
-    try {
-      const dir = logDir();
-      if (madeDir !== dir) {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-        madeDir = dir;
-      }
-      prune();
-      const file = dayFile();
-      if (current.file !== file) {
-        let size = 0;
-        try {
-          size = fs.statSync(file).size;
-        } catch { /* a new day */ }
-        current = { file, size };
-        full = false;
-      }
-      if (current.size > MAX_DAY_BYTES) {
-        if (!full) fs.appendFileSync(file, `${JSON.stringify({ ts: new Date().toISOString(), session, kind: 'log_full', note: 'Daily log limit reached; further entries today are dropped.' })}\n`);
-        full = true;
-        return;
-      }
-      const line = `${JSON.stringify({ ts: new Date().toISOString(), session, client: client(), ...entry })}\n`;
-      fs.appendFileSync(file, line, { mode: 0o600 });
-      current.size += Buffer.byteLength(line);
-    } catch {
-      // logging must never break a call; look at the folder again next time
-      madeDir = null;
-    }
-  }
-  return { write, file: () => dayFile() };
-}
-
-/** The last `limit` entries from the newest `days` daily files, optionally for one session. */
-function readLog({ days = 2, limit = 50, session } = {}) {
-  const out = [];
-  for (let i = days - 1; i >= 0; i--) {
-    const file = dayFile(new Date(Date.now() - i * 86_400_000));
-    let lines = [];
-    try {
-      lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
-    } catch {
-      continue;
-    }
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        if (!session || entry.session === session) out.push(entry);
-      } catch { /* skip a torn line */ }
-    }
-  }
-  return out.slice(-limit);
-}
-
-module.exports = { createSessionLog, readLog, describeArgs, describeResult, safeUrl, logDir, dayFile, KEEP_DAYS };
+/**
+ * BrowserZap — session log: what every session did, for transparency and debugging.
+ *
+ * One JSON line per tool call or workflow step, appended to
+ *   <config dir>/logs/YYYY-MM-DD.jsonl   (0600, kept 14 days)
+ * by the MCP server (agent calls, agent-run workflows) and the bridge's panel
+ * runner (workflows run from the side panel).
+ *
+ * Recorded: time, session and client, tool, the target as it was named, the
+ * outcome (ok, state, error code), timing, and evidence useful for debugging
+ * (waited-for-target time, click path, risk, navigation, where a workflow
+ * stopped), plus the page as origin + path.
+ *
+ * Never recorded: typed values (only their length), parameter values (only
+ * their names), URL query strings or fragments, page text, approval ids,
+ * screenshots. Result summaries quote page content, so they are added only
+ * with BROWSERZAP_LOG=verbose. BROWSERZAP_LOG=off disables the file.
+ *
+ * Read it with `npm run logs` (bridge-server/index.js --logs).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { configDir } = require('./secret');
+
+const KEEP_DAYS = 14;
+const MAX_DAY_BYTES = 20 * 1024 * 1024;
+const MAX_TEXT = 80;
+const EVIDENCE_KEYS = [
+  'waitedForTargetMs', 'clickVia', 'input', 'risk', 'navigated', 'urlChanged', 'domChanged', 'noObservableChange',
+  'expectationMet', 'verified', 'redirected', 'crossOrigin', 'reResolvedStaleRef', 'elapsedMs',
+  'workflow', 'version', 'stoppedAt', 'completedSteps', 'totalSteps', 'completedRuns',
+  // slow-server evidence (docs/AUDIT.md AU-02, AU-06, AU-07, AU-05)
+  'loaded', 'httpStatus', 'retryable', 'ttfbMs', 'domContentLoadedMs', 'loadMs', 'waitingFor', 'pageBusyMs', 'waitedForPersonMs',
+  // why a step was slow or failed (AU-12); slowestRequest is origin + path only. busyIndicator is page text: verbose only.
+  'likelyCause', 'slowestRequest', 'pendingRequests', 'readyState', 'slowSteps',
+];
+const PLAIN_ARGS = [
+  'key', 'direction', 'amount', 'timeoutMs', 'maxElements', 'includeText', 'maxTextChars', 'within', 'tabId',
+  'name', 'startAt', 'version', 'action', 'restoreVersion', 'limit', 'includeTab', 'waitMs', 'overwrite', 'keepValues',
+];
+
+const mode = () => (process.env.BROWSERZAP_LOG || 'standard').toLowerCase();
+const logDir = () => path.join(configDir(), 'logs');
+const dayFile = (date = new Date()) => path.join(logDir(), `${date.toISOString().slice(0, 10)}.jsonl`);
+const clip = (v) => (typeof v === 'string' && v.length > MAX_TEXT ? `${v.slice(0, MAX_TEXT)}…` : v);
+
+/** origin + path only: query strings and fragments often carry tokens or personal data. */
+function safeUrl(raw) {
+  if (typeof raw !== 'string' || !raw) return undefined;
+  if (raw.includes('{{')) return clip(raw.split(/[?#]/)[0]);
+  try {
+    const u = new URL(raw);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return '(invalid url)';
+  }
+}
+
+function targetOf(target) {
+  if (!target || typeof target !== 'object') return undefined;
+  const out = {};
+  for (const key of ['ref', 'role', 'name', 'label', 'text', 'within']) if (typeof target[key] === 'string') out[key] = clip(target[key]);
+  if (typeof target.href === 'string') out.href = safeUrl(target.href) ?? clip(target.href);
+  return out;
+}
+
+/** What a call asked for, without values. */
+function describeArgs(args = {}) {
+  if (!args || typeof args !== 'object') return {};
+  const out = {};
+  if (args.target) out.target = targetOf(args.target);
+  if (args.expect && typeof args.expect === 'object') out.expect = Object.keys(args.expect);
+  if (args.url !== undefined) out.url = safeUrl(args.url);
+  if (args.value !== undefined) out.valueLength = String(args.value).length;
+  if (args.option && typeof args.option === 'object') out.option = Object.keys(args.option);
+  for (const key of PLAIN_ARGS) if (args[key] !== undefined && typeof args[key] !== 'object') out[key] = clip(args[key]);
+  if (args.params && typeof args.params === 'object') out.params = Object.keys(args.params);
+  if (Array.isArray(args.paramSets)) out.paramSets = args.paramSets.length;
+  if (Array.isArray(args.steps)) out.steps = args.steps.length;
+  if (args.approvalId) out.approval = true;
+  if (typeof args.message === 'string') out.messageLength = args.message.length;
+  return out;
+}
+
+/** What came back, without page text unless verbose. */
+function describeResult(env = {}) {
+  const out = { ok: env.ok === true, state: env.state };
+  if (env.error?.code) out.code = env.error.code;
+  const page = safeUrl(env.page?.url);
+  if (page) out.page = page;
+  const evidence = {};
+  for (const key of EVIDENCE_KEYS) if (env.evidence?.[key] !== undefined) evidence[key] = env.evidence[key];
+  if (Object.keys(evidence).length) out.evidence = evidence;
+  if (Array.isArray(env.candidates)) out.candidates = env.candidates.length;
+  if (mode() === 'verbose') {
+    if (env.evidence?.busyIndicator) (out.evidence ??= {}).busyIndicator = env.evidence.busyIndicator;
+    out.summary = env.summary;
+    if (env.nextAction) out.nextAction = env.nextAction;
+  }
+  return out;
+}
+
+let pruned = false;
+function prune() {
+  if (pruned) return;
+  pruned = true;
+  const cutoff = Date.now() - KEEP_DAYS * 86_400_000;
+  try {
+    for (const file of fs.readdirSync(logDir())) {
+      const day = Date.parse(file.slice(0, 10));
+      if (/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(file) && day < cutoff) fs.unlinkSync(path.join(logDir(), file));
+    }
+  } catch { /* nothing to prune */ }
+}
+
+/**
+ * @param {{ session: string, client: () => string }} who
+ * @returns {{ write(entry: object): void, file(): string }}
+ */
+/**
+ * One file call per entry (audit AU-21): the folder is created once per
+ * process and per folder, and the day file's size is read once per day file
+ * and then tracked in memory.
+ */
+let madeDir = null;
+function createSessionLog({ session, client }) {
+  let full = false;
+  let current = { file: null, size: 0 };
+  function write(entry) {
+    if (mode() === 'off') return;
+    try {
+      const dir = logDir();
+      if (madeDir !== dir) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        madeDir = dir;
+      }
+      prune();
+      const file = dayFile();
+      if (current.file !== file) {
+        let size = 0;
+        try {
+          size = fs.statSync(file).size;
+        } catch { /* a new day */ }
+        current = { file, size };
+        full = false;
+      }
+      if (current.size > MAX_DAY_BYTES) {
+        if (!full) fs.appendFileSync(file, `${JSON.stringify({ ts: new Date().toISOString(), session, kind: 'log_full', note: 'Daily log limit reached; further entries today are dropped.' })}\n`);
+        full = true;
+        return;
+      }
+      const line = `${JSON.stringify({ ts: new Date().toISOString(), session, client: client(), ...entry })}\n`;
+      fs.appendFileSync(file, line, { mode: 0o600 });
+      current.size += Buffer.byteLength(line);
+    } catch {
+      // logging must never break a call; look at the folder again next time
+      madeDir = null;
+    }
+  }
+  return { write, file: () => dayFile() };
+}
+
+/** The last `limit` entries from the newest `days` daily files, optionally for one session. */
+function readLog({ days = 2, limit = 50, session } = {}) {
+  const out = [];
+  for (let i = days - 1; i >= 0; i--) {
+    const file = dayFile(new Date(Date.now() - i * 86_400_000));
+    let lines = [];
+    try {
+      lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    } catch {
+      continue;
+    }
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (!session || entry.session === session) out.push(entry);
+      } catch { /* skip a torn line */ }
+    }
+  }
+  return out.slice(-limit);
+}
+
+module.exports = { createSessionLog, readLog, describeArgs, describeResult, safeUrl, logDir, dayFile, KEEP_DAYS };

package/bridge-server/tools.js

@@ -289,7 +289,9 @@ const MCP_TOOLS = [
   },
   {
     name: 'browser_new_tab',
-    description: 'Open a new tab in this session\'s tab group and make it the session tab.',
+    description: 'Open a helper tab in this session\'s tab group and make it the session tab. Only for a side trip ' +
+      '(research, a comparison): for a new task, navigate the main tab instead. Close the helper with browser_close_tab ' +
+      'when done. At 5 tabs, the least recently used helper is closed to make room.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -311,6 +313,16 @@ const MCP_TOOLS = [
       properties: { tabId: { type: 'integer', minimum: 0 } },
     },
   },
+  {
+    name: 'browser_close_tab',
+    description: 'Close a helper tab of this session (the current tab when tabId is omitted) and go back to the main ' +
+      'tab. The main tab cannot be closed: navigate it for the next task.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { tabId: { type: 'integer', minimum: 0 } },
+    },
+  },
   {
     name: 'browser_set_session_name',
     description: 'Name this session; the name appears on the Chrome tab group so the user knows what it is doing.',
@@ -534,6 +546,7 @@ const ANNOTATIONS = {
   browser_new_tab: ['New tab', { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }],
   browser_list_tabs: ['List tabs', LOCAL_READ],
   browser_switch_tab: ['Switch tab', { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }],
+  browser_close_tab: ['Close helper tab', { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }],
   browser_set_session_name: ['Name session', { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }],
   browser_list_profiles: ['List Chrome profiles', LOCAL_READ],
   browser_select_profile: ['Choose Chrome profile', { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }],
@@ -577,6 +590,7 @@ const TOOL_TO_ACTION = {
   browser_new_tab: 'new_tab',
   browser_list_tabs: 'list_tabs',
   browser_switch_tab: 'switch_tab',
+  browser_close_tab: 'close_tab',
 };
 
 /**