aiden-runtime 4.1.5 → 4.6.0

package/dist/tools/v4/browser/browserBlocker.js

@@ -0,0 +1,396 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/browser/browserBlocker.ts — v4.3 Phase 3: Manual-blocker
+ * detection.
+ *
+ * Five-tier substring + URL pattern pipeline that surfaces "the
+ * agent needs your help" situations: CAPTCHA challenges, sign-in
+ * walls, 2FA prompts, identity verification, cookie/GDPR consent.
+ *
+ * Distinct from Phase 1's BrowserState observer (which records
+ * state-delta evidence) and Phase 2's stale-ref retry (which auto-
+ * corrects transient races). Phase 3 detects situations that
+ * **cannot be solved by retry** — the page is asking for a human
+ * action — and surfaces them as structured cards so the model
+ * doesn't grind through retry attempts.
+ *
+ * Non-negotiable: NEVER auto-solve a CAPTCHA. The pause-and-surface
+ * contract from Q-CDP5(c) is enforced structurally — this module
+ * only detects + surfaces. No vision-attempt fallback, no clicking
+ * "I'm not a robot" tickboxes, no submitting forms blindly. The
+ * model reads `result.browserState.blocker` in its tool message and
+ * tells the user.
+ *
+ * The CAPTCHA tier reuses Aiden's existing `captchaCheck.ts` 24-
+ * marker scan — Phase 3 doesn't refactor it, only wraps it as one
+ * of five detectors. The other four tiers (2FA, login, verification,
+ * consent) are new in Phase 3.
+ *
+ * Priority order: captcha > 2fa > login > verification > consent.
+ * Only ONE blocker reported per detection (highest priority wins).
+ * Pages that match multiple tiers (a 2FA challenge inside an
+ * obscured cookie banner) report the most-blocking kind — the
+ * lower-priority match can wait until the higher-priority is
+ * cleared.
+ *
+ * Pure module — types + 5 detectors + 1 orchestrator. No I/O, no
+ * async, no Playwright dependency. Easy to unit-test against
+ * canonical page-text fixtures. The observer HOC consumes the
+ * `pwSnapshot()` text via the existing playwrightBridge helper.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectBlocker = detectBlocker;
+const captchaCheck_1 = require("./captchaCheck");
+// ── Pattern tables ──────────────────────────────────────────────────────────
+// CAPTCHA tier reuses captchaCheck.ts markers + adds subtype detection.
+const CAPTCHA_SUBTYPE_MARKERS = [
+    ['recaptcha', 'recaptcha'],
+    ['g-recaptcha', 'recaptcha'],
+    ['hcaptcha.com', 'hcaptcha'],
+    ['cf-turnstile', 'turnstile'],
+    ['cloudflare', 'cloudflare'],
+    ['just a moment', 'cloudflare'],
+    ['checking your browser', 'cloudflare'],
+];
+// 2FA / MFA tier — input attributes, text, and URL.
+const TWOFA_TEXT_PATTERNS = [
+    'enter the code',
+    'enter your code',
+    'verification code',
+    'authentication code',
+    '6-digit code',
+    'two-factor',
+    'two factor',
+    '2-step verification',
+    'two-step verification',
+    'authenticator app',
+    'sms code',
+    'sent a code',
+    'we sent you a code',
+    'text message',
+    'security code',
+    'one-time code',
+    'one-time password',
+];
+const TWOFA_URL_PATTERNS = [
+    '/2fa',
+    '/mfa',
+    '/verify-code',
+    '/verify_code',
+    '/auth/challenge',
+    '/two-factor',
+    '/two_factor',
+];
+const TWOFA_DOM_HINTS = [
+    'autocomplete="one-time-code"',
+    "autocomplete='one-time-code'",
+    'inputmode="numeric"',
+];
+const TWOFA_SUBTYPE_HINTS = [
+    ['authenticator app', 'totp'],
+    ['totp', 'totp'],
+    ['sms', 'sms'],
+    ['text message', 'sms'],
+    ['phone', 'sms'],
+];
+// Login tier — sign-in forms, OAuth, SSO.
+const LOGIN_TEXT_PATTERNS = [
+    'sign in',
+    'sign-in',
+    'log in',
+    'log-in',
+    'login',
+    'enter your password',
+    'enter password',
+    'continue with google',
+    'continue with apple',
+    'continue with github',
+    'continue with microsoft',
+    'sign in with',
+    'single sign-on',
+    'single sign on',
+];
+const LOGIN_URL_PATTERNS = [
+    '/login',
+    '/signin',
+    '/sign-in',
+    '/auth',
+    '/oauth',
+    '/sso',
+    '/account/login',
+];
+const LOGIN_DOM_HINTS = [
+    'type="password"',
+    "type='password'",
+    'input password', // generic fallback
+];
+const LOGIN_SUBTYPE_HINTS = [
+    ['oauth', 'oauth'],
+    ['sso', 'oauth'],
+    ['continue with google', 'oauth'],
+    ['continue with apple', 'oauth'],
+    ['continue with github', 'oauth'],
+];
+// Verification tier — identity / phone / email confirmation.
+const VERIFY_TEXT_PATTERNS = [
+    'verify your phone',
+    'phone verification',
+    'verify your email',
+    'email verification',
+    'confirm your email',
+    'verify your identity',
+    'identity verification',
+    'identity check',
+    'prove your identity',
+];
+const VERIFY_URL_PATTERNS = [
+    '/verify',
+    '/verification',
+    '/confirm',
+    '/confirm-email',
+    '/confirm_email',
+];
+const VERIFY_SUBTYPE_HINTS = [
+    ['phone', 'phone'],
+    ['email', 'email'],
+    ['identity', 'identity'],
+];
+// Consent tier — cookie banners, GDPR.
+const CONSENT_TEXT_PATTERNS = [
+    'accept all cookies',
+    'reject all cookies',
+    'manage cookies',
+    'manage your preferences',
+    'we use cookies',
+    'this site uses cookies',
+    'gdpr',
+    'cookie preferences',
+    'cookie consent',
+    'privacy preferences',
+];
+const CONSENT_URL_PATTERNS = [
+    '/cookie',
+    '/consent',
+];
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function lowercase(s) {
+    return (s ?? '').toLowerCase();
+}
+function matchesAny(haystack, patterns) {
+    for (const p of patterns) {
+        if (haystack.includes(p))
+            return p;
+    }
+    return null;
+}
+function pickSubtype(haystack, hints, fallback) {
+    for (const [marker, subtype] of hints) {
+        if (haystack.includes(marker))
+            return subtype;
+    }
+    return fallback;
+}
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname || url;
+    }
+    catch {
+        return url;
+    }
+}
+// ── Per-tier detectors ─────────────────────────────────────────────────────
+/**
+ * Markers from captchaCheck.ts that aren't CAPTCHA-specific —
+ * they overlap semantically with the Verification tier (phone /
+ * email / identity confirmation). When captchaCheck's only hit
+ * is one of these, defer to the Verification tier; CAPTCHA needs
+ * a more specific signal.
+ */
+const AMBIGUOUS_CAPTCHA_MARKERS = new Set([
+    'verify your identity',
+]);
+function detectCaptcha(text, url) {
+    const result = (0, captchaCheck_1.detectCaptchaMarkers)(text);
+    if (!result.detected)
+        return null;
+    // Demote: when the only matched marker is an ambiguous one (e.g.
+    // "verify your identity" — used by both CAPTCHAs and identity-
+    // verification flows), let the Verification tier handle it.
+    // CAPTCHA needs at least one specific signal.
+    if (result.markers.length === 1 &&
+        AMBIGUOUS_CAPTCHA_MARKERS.has(result.markers[0])) {
+        return null;
+    }
+    const lowerText = lowercase(text);
+    const subtype = pickSubtype(lowerText, CAPTCHA_SUBTYPE_MARKERS, 'unknown');
+    const evidence = result.markers.map((m) => `captcha-marker:${m}`);
+    // Multi-marker boosts confidence.
+    const confidence = result.markers.length >= 3 ? 0.95 :
+        result.markers.length === 2 ? 0.85 : 0.7;
+    return {
+        kind: 'captcha',
+        subtype,
+        url,
+        confidence,
+        evidence,
+        message: `${subtype === 'unknown' ? 'CAPTCHA' : subtype} challenge at ${hostnameOf(url)}. Solve it in the browser tab, then tell me when ready.`,
+    };
+}
+function detect2FA(text, url) {
+    const lowerText = lowercase(text);
+    const lowerUrl = lowercase(url);
+    const textHit = matchesAny(lowerText, TWOFA_TEXT_PATTERNS);
+    const urlHit = matchesAny(lowerUrl, TWOFA_URL_PATTERNS);
+    const domHit = matchesAny(lowerText, TWOFA_DOM_HINTS);
+    // Need at least ONE strong signal — text or URL match. DOM hint
+    // alone isn't enough (the text may be misleading on a docs page).
+    if (!textHit && !urlHit)
+        return null;
+    const evidence = [];
+    if (textHit)
+        evidence.push(`text:${textHit}`);
+    if (urlHit)
+        evidence.push(`url:${urlHit}`);
+    if (domHit)
+        evidence.push(`dom:${domHit}`);
+    const subtype = pickSubtype(lowerText, TWOFA_SUBTYPE_HINTS, 'unknown');
+    // Confidence: text+url+dom = 0.9, text+url = 0.8, text+dom = 0.75,
+    // text-only or url-only = 0.6.
+    let confidence = 0.6;
+    const signals = (textHit ? 1 : 0) + (urlHit ? 1 : 0) + (domHit ? 1 : 0);
+    if (signals === 2)
+        confidence = textHit && urlHit ? 0.8 : 0.75;
+    if (signals === 3)
+        confidence = 0.9;
+    return {
+        kind: '2fa',
+        subtype,
+        url,
+        confidence,
+        evidence,
+        message: `Two-factor code required at ${hostnameOf(url)}. Enter your ${subtype === 'totp' ? 'authenticator app code' : subtype === 'sms' ? 'SMS code' : 'verification code'} in the browser tab and tell me when complete.`,
+    };
+}
+function detectLogin(text, url) {
+    const lowerText = lowercase(text);
+    const lowerUrl = lowercase(url);
+    const textHit = matchesAny(lowerText, LOGIN_TEXT_PATTERNS);
+    const urlHit = matchesAny(lowerUrl, LOGIN_URL_PATTERNS);
+    const domHit = matchesAny(lowerText, LOGIN_DOM_HINTS);
+    if (!textHit && !urlHit)
+        return null;
+    const evidence = [];
+    if (textHit)
+        evidence.push(`text:${textHit}`);
+    if (urlHit)
+        evidence.push(`url:${urlHit}`);
+    if (domHit)
+        evidence.push(`dom:${domHit}`);
+    // Subtype: prefer text-marker match, then check URL for oauth/sso
+    // indicators (a `/oauth` or `/sso` URL is a strong OAuth signal
+    // even when the visible text is generic like "Authorize access").
+    let subtype = pickSubtype(lowerText, LOGIN_SUBTYPE_HINTS, '');
+    if (!subtype) {
+        if (lowerUrl.includes('oauth') || lowerUrl.includes('sso')) {
+            subtype = 'oauth';
+        }
+        else {
+            subtype = 'password';
+        }
+    }
+    let confidence = 0.6;
+    const signals = (textHit ? 1 : 0) + (urlHit ? 1 : 0) + (domHit ? 1 : 0);
+    if (signals === 2)
+        confidence = 0.8;
+    if (signals === 3)
+        confidence = 0.9;
+    return {
+        kind: 'login',
+        subtype,
+        url,
+        confidence,
+        evidence,
+        message: `Sign-in required at ${hostnameOf(url)}. Authenticate in the browser tab and let me know when done.`,
+    };
+}
+function detectVerify(text, url) {
+    const lowerText = lowercase(text);
+    const lowerUrl = lowercase(url);
+    const textHit = matchesAny(lowerText, VERIFY_TEXT_PATTERNS);
+    const urlHit = matchesAny(lowerUrl, VERIFY_URL_PATTERNS);
+    if (!textHit && !urlHit)
+        return null;
+    const evidence = [];
+    if (textHit)
+        evidence.push(`text:${textHit}`);
+    if (urlHit)
+        evidence.push(`url:${urlHit}`);
+    const subtype = pickSubtype(lowerText, VERIFY_SUBTYPE_HINTS, 'unknown');
+    // Url-only is the weaker case here (lots of /verify URLs do other
+    // things), so URL-only matches need text-marker reinforcement to
+    // reach 0.6+ confidence.
+    let confidence = 0.5;
+    if (textHit && urlHit)
+        confidence = 0.85;
+    else if (textHit)
+        confidence = 0.7;
+    return {
+        kind: 'verification',
+        subtype,
+        url,
+        confidence,
+        evidence,
+        message: `Identity verification required at ${hostnameOf(url)}. Complete the verification in the browser tab and tell me when done.`,
+    };
+}
+function detectConsent(text, url) {
+    const lowerText = lowercase(text);
+    const lowerUrl = lowercase(url);
+    const textHit = matchesAny(lowerText, CONSENT_TEXT_PATTERNS);
+    const urlHit = matchesAny(lowerUrl, CONSENT_URL_PATTERNS);
+    if (!textHit && !urlHit)
+        return null;
+    const evidence = [];
+    if (textHit)
+        evidence.push(`text:${textHit}`);
+    if (urlHit)
+        evidence.push(`url:${urlHit}`);
+    let confidence = 0.5;
+    if (textHit && urlHit)
+        confidence = 0.8;
+    else if (textHit)
+        confidence = 0.65;
+    return {
+        kind: 'consent',
+        subtype: 'cookies',
+        url,
+        confidence,
+        evidence,
+        message: `Consent banner at ${hostnameOf(url)}. Dismiss the cookie/privacy banner in the browser tab — I can retry afterward.`,
+    };
+}
+// ── Orchestrator ───────────────────────────────────────────────────────────
+/**
+ * Detect the highest-priority manual blocker on a page. Priority
+ * order: captcha > 2fa > login > verification > consent. Returns
+ * null when no tier matches.
+ *
+ * Pure function — same inputs always produce the same output.
+ * Public for unit tests + the HOC's per-action detection call.
+ */
+function detectBlocker(input) {
+    const text = input.text ?? '';
+    const url = input.url ?? '';
+    // Priority pipeline — first non-null wins.
+    return (detectCaptcha(text, url) ??
+        detect2FA(text, url) ??
+        detectLogin(text, url) ??
+        detectVerify(text, url) ??
+        detectConsent(text, url));
+}

package/dist/tools/v4/browser/browserClick.js

@@ -17,7 +17,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserClickTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserClickTool = {
+const _observer_1 = require("./_observer");
+const _browserClickTool = {
     schema: {
         name: 'browser_click',
         description: 'Click an element by CSS selector or visible text. Use target="first_result" to click the first organic search result on supported engines.',
@@ -35,6 +36,18 @@ exports.browserClickTool = {
     category: 'browser',
     mutates: true,
     toolset: 'browser',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const target = String(args.target ?? args.selector ?? '');
+        return {
+            tool: 'browser_click',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'browser_action', action: 'click', target }],
+            detectedRisks: [],
+            summary: `Would click browser element: ${target}`,
+        };
+    },
     async execute(args) {
         const target = String(args.target ?? args.selector ?? '').trim();
         if (!target)
@@ -51,3 +64,7 @@ exports.browserClickTool = {
         return { success: false, error: r.error, target };
     },
 };
+// v4.3 Phase 1 — observer HOC captures pre/post page state when
+// browser depth is enabled (default ON; opt-out via
+// AIDEN_BROWSER_DEPTH=0) and embeds it as a `browserState` sidecar.
+exports.browserClickTool = (0, _observer_1.withBrowserState)(_browserClickTool);

package/dist/tools/v4/browser/browserClose.js

@@ -16,7 +16,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserCloseTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserCloseTool = {
+const _observer_1 = require("./_observer");
+const _browserCloseTool = {
     schema: {
         name: 'browser_close',
         description: 'Close the persistent browser session. The next browser tool will start a new one.',
@@ -25,6 +26,17 @@ exports.browserCloseTool = {
     category: 'browser',
     mutates: true,
     toolset: 'browser',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        return {
+            tool: 'browser_close',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'browser_action', action: 'close' }],
+            detectedRisks: [],
+            summary: 'Would close the browser session',
+        };
+    },
     async execute() {
         try {
             await (0, playwrightBridge_1.pwClose)();
@@ -36,3 +48,8 @@ exports.browserCloseTool = {
         }
     },
 };
+// v4.3 Phase 1 — observer HOC. After close the post-snapshot will
+// either spin up a fresh context (and return null on the first call
+// since the page is blank) or fail cleanly — either way the sidecar
+// just doesn't embed. Tiny overhead, uniform pattern.
+exports.browserCloseTool = (0, _observer_1.withBrowserState)(_browserCloseTool);

package/dist/tools/v4/browser/browserExtract.js

@@ -18,7 +18,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserExtractTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserExtractTool = {
+const _observer_1 = require("./_observer");
+const _browserExtractTool = {
     schema: {
         name: 'browser_extract',
         description: 'Extract the visible text content of the current browser page. Requires the browser to be on a page (navigate first using a Phase-8 navigation tool, or via the search-then-click flow).',
@@ -30,6 +31,7 @@ exports.browserExtractTool = {
     category: 'browser',
     mutates: false,
     toolset: 'browser',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute() {
         const r = await (0, playwrightBridge_1.pwSnapshot)();
         if (r.ok)
@@ -37,3 +39,5 @@ exports.browserExtractTool = {
         return { success: false, error: r.error };
     },
 };
+// v4.3 Phase 1 — observer HOC.
+exports.browserExtractTool = (0, _observer_1.withBrowserState)(_browserExtractTool);

package/dist/tools/v4/browser/browserFill.js

@@ -17,7 +17,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserFillTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserFillTool = {
+const _observer_1 = require("./_observer");
+const _browserFillTool = {
     schema: {
         name: 'browser_fill',
         description: 'Fill multiple form fields. Pass `fields` as an object mapping CSS selectors to text values.',
@@ -35,6 +36,19 @@ exports.browserFillTool = {
     category: 'browser',
     mutates: true,
     toolset: 'browser',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const fields = (args.fields ?? {});
+        const keys = fields && typeof fields === 'object' ? Object.keys(fields) : [];
+        return {
+            tool: 'browser_fill',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'browser_action', action: 'fill', target: keys.join(', ') }],
+            detectedRisks: [],
+            summary: `Would fill ${keys.length} form field${keys.length === 1 ? '' : 's'}: ${keys.join(', ')}`,
+        };
+    },
     async execute(args) {
         const fields = (args.fields ?? {});
         if (!fields || typeof fields !== 'object' || Array.isArray(fields)) {
@@ -57,3 +71,5 @@ exports.browserFillTool = {
         return { success: true, filled, count: filled.length };
     },
 };
+// v4.3 Phase 1 — observer HOC.
+exports.browserFillTool = (0, _observer_1.withBrowserState)(_browserFillTool);

package/dist/tools/v4/browser/browserGetUrl.js

@@ -16,7 +16,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserGetUrlTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserGetUrlTool = {
+const _observer_1 = require("./_observer");
+const _browserGetUrlTool = {
     schema: {
         name: 'browser_get_url',
         description: 'Return the URL of the page currently loaded in the browser. Useful for verifying navigation succeeded after a click.',
@@ -28,6 +29,7 @@ exports.browserGetUrlTool = {
     category: 'browser',
     mutates: false,
     toolset: 'browser',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute() {
         const r = await (0, playwrightBridge_1.pwGetUrl)();
         if (r.ok)
@@ -35,3 +37,5 @@ exports.browserGetUrlTool = {
         return { success: false, error: r.error };
     },
 };
+// v4.3 Phase 1 — observer HOC.
+exports.browserGetUrlTool = (0, _observer_1.withBrowserState)(_browserGetUrlTool);

package/dist/tools/v4/browser/browserNavigate.js

@@ -18,7 +18,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserNavigateTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
 const captchaCheck_1 = require("./captchaCheck");
-exports.browserNavigateTool = {
+const _observer_1 = require("./_observer");
+const _browserNavigateTool = {
     schema: {
         name: 'browser_navigate',
         description: 'Navigate the browser to a URL. Reuses the active tab; opens one if none exists. ' +
@@ -35,6 +36,18 @@ exports.browserNavigateTool = {
     category: 'browser',
     mutates: true,
     toolset: 'browser',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const url = String(args.url ?? '');
+        return {
+            tool: 'browser_navigate',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'browser_action', action: 'navigate', url }],
+            detectedRisks: [],
+            summary: `Would navigate browser to: ${url}`,
+        };
+    },
     async execute(args) {
         const url = String(args.url ?? '').trim();
         if (!url)
@@ -73,3 +86,5 @@ exports.browserNavigateTool = {
         return { success: true, url: r.url };
     },
 };
+// v4.3 Phase 1 — observer HOC.
+exports.browserNavigateTool = (0, _observer_1.withBrowserState)(_browserNavigateTool);

package/dist/tools/v4/browser/browserScreenshot.js

@@ -22,7 +22,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserScreenshotTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserScreenshotTool = {
+const _observer_1 = require("./_observer");
+const _browserScreenshotTool = {
     schema: {
         name: 'browser_screenshot',
         description: 'Take a screenshot of the current browser page (the page you previously navigated to). Saves to disk and returns the file path. Requires that the browser was opened earlier in this session.',
@@ -34,6 +35,7 @@ exports.browserScreenshotTool = {
     category: 'browser',
     mutates: false,
     toolset: 'browser',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute() {
         const r = await (0, playwrightBridge_1.pwScreenshot)();
         if (r.ok)
@@ -41,3 +43,5 @@ exports.browserScreenshotTool = {
         return { success: false, error: r.error };
     },
 };
+// v4.3 Phase 1 — observer HOC.
+exports.browserScreenshotTool = (0, _observer_1.withBrowserState)(_browserScreenshotTool);

package/dist/tools/v4/browser/browserScroll.js

@@ -17,7 +17,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserScrollTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserScrollTool = {
+const _observer_1 = require("./_observer");
+const _browserScrollTool = {
     schema: {
         name: 'browser_scroll',
         description: 'Scroll the browser page (or a specific element via `selector`). `direction` ∈ up|down|top|bottom; `amount` is pixels for up/down (default 500).',
@@ -43,6 +44,20 @@ exports.browserScrollTool = {
     category: 'browser',
     mutates: true,
     toolset: 'browser',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const direction = String(args.direction ?? 'down');
+        const amount = typeof args.amount === 'number' ? args.amount : 500;
+        const selector = typeof args.selector === 'string' ? args.selector : '';
+        return {
+            tool: 'browser_scroll',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'browser_action', action: `scroll:${direction}`, target: selector || 'window' }],
+            detectedRisks: [],
+            summary: `Would scroll browser ${direction}${direction === 'up' || direction === 'down' ? ` ${amount}px` : ''}${selector ? ` (${selector})` : ''}`,
+        };
+    },
     async execute(args) {
         const directionRaw = String(args.direction ?? 'down').toLowerCase();
         const direction = ['up', 'down', 'top', 'bottom'].includes(directionRaw)
@@ -56,3 +71,5 @@ exports.browserScrollTool = {
         return { success: false, error: r.error };
     },
 };
+// v4.3 Phase 1 — observer HOC.
+exports.browserScrollTool = (0, _observer_1.withBrowserState)(_browserScrollTool);

package/dist/tools/v4/browser/browserType.js

@@ -15,7 +15,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.browserTypeTool = void 0;
 const playwrightBridge_1 = require("../../../core/playwrightBridge");
-exports.browserTypeTool = {
+const _observer_1 = require("./_observer");
+const _browserTypeTool = {
     schema: {
         name: 'browser_type',
         description: 'Type text into a browser input identified by CSS selector. Replaces existing value.',
@@ -34,6 +35,19 @@ exports.browserTypeTool = {
     category: 'browser',
     mutates: true,
     toolset: 'browser',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const selector = String(args.selector ?? 'input');
+        const text = String(args.text ?? '');
+        return {
+            tool: 'browser_type',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'browser_action', action: 'type', target: selector }],
+            detectedRisks: [],
+            summary: `Would type ${text.length} chars into ${selector}`,
+        };
+    },
     async execute(args) {
         const selector = String(args.selector ?? 'input').trim();
         const text = String(args.text ?? '');
@@ -43,3 +57,5 @@ exports.browserTypeTool = {
         return { success: false, error: r.error, selector };
     },
 };
+// v4.3 Phase 1 — observer HOC captures pre/post page state.
+exports.browserTypeTool = (0, _observer_1.withBrowserState)(_browserTypeTool);