aiden-runtime 4.1.4 → 4.5.0

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

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/browser/_observer.ts — v4.3 Phase 1 + 2: shared BrowserState
+ * observer + stale-ref retry HOC for browser ToolHandlers.
+ *
+ * One BrowserState lives per server process (lifecycle matches the
+ * persistent playwrightBridge context). Every browser tool wraps its
+ * ToolHandler in `withBrowserState(...)` so the observer's pre/post
+ * snapshot capture happens automatically.
+ *
+ * Phase 1 — observer captures pre/post snapshots and embeds them as
+ * a `browserState` sidecar on the tool result when
+ * browser depth is enabled (default ON; opt-out via
+ * AIDEN_BROWSER_DEPTH=0). No-op when disabled.
+ *
+ * Phase 2 — stale-ref recovery. When an interactive browser tool
+ * (browser_click / browser_type / browser_fill) returns a
+ * resolution-class failure (`element not found`, `not visible`,
+ * `not attached`, `timeout`, `target closed`), the HOC resnapshots
+ * and retries the inner execute ONCE with the same args. The retry
+ * logic is reactive only — no preflight tax on success paths. The
+ * retry attempt + outcome lands on `ActionResult.staleRefRetry`
+ * for Phase 5's classifier to consume.
+ *
+ * The one-retry hard cap is the consult-derived non-negotiable: a
+ * second retry doesn't help (the cause isn't transient) and starts
+ * looking like agent thrashing. If the retry fails, the original
+ * failure result is preserved — same error message, but with the
+ * `staleRefRetry: { attempted: true, succeeded: false, ... }`
+ * sidecar so the classifier can recognise the pattern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STALE_REF_PATTERNS = exports.STALE_REF_RETRYABLE = exports.browserState = void 0;
+exports.detectStaleRefError = detectStaleRefError;
+exports.withBrowserState = withBrowserState;
+const browserState_1 = require("../../../core/v4/browserState");
+const browserBlocker_1 = require("./browserBlocker");
+const playwrightBridge_1 = require("../../../core/playwrightBridge");
+/**
+ * Shared observer — one instance per server process. The HOC closes
+ * over this reference so all 9 browser tools share the same snapshot
+ * counter and gating decision.
+ *
+ * Tests can construct their own BrowserState with a stubbed bridge
+ * loader and call `withBrowserState(handler, customState)` directly.
+ */
+exports.browserState = (0, browserState_1.createBrowserState)();
+// ── Phase 2 — stale-ref retry primitives ─────────────────────────────
+/**
+ * Interactive browser tools that operate on a selector. Stale-ref
+ * retry only fires for these — other tools either don't take a
+ * selector (browser_navigate, browser_close, browser_get_url) or
+ * are read-only (browser_extract, browser_screenshot, browser_scroll).
+ */
+exports.STALE_REF_RETRYABLE = new Set([
+    'browser_click',
+    'browser_type',
+    'browser_fill',
+]);
+/**
+ * Error-message patterns that indicate a resolution-class failure
+ * (DOM lookup failed BEFORE any side-effect-producing action fired).
+ * Phase 2 retries only on these — never on action-failure messages
+ * (network errors, permission denials, etc.).
+ *
+ * The patterns are case-insensitive substrings; one match is enough.
+ * False positives are tolerable — retry-once costs ~200ms and produces
+ * the same result on the second attempt. False negatives miss the
+ * common transient-race case, so bias toward sensitivity.
+ */
+exports.STALE_REF_PATTERNS = [
+    /element not found/i,
+    /not visible/i,
+    /not attached/i,
+    /detached from the DOM/i,
+    /target closed/i,
+    /timeout \d+ms exceeded/i,
+];
+/**
+ * Check if a tool result represents a resolution-class failure.
+ * Returns the matched pattern (as a short string) when stale, null
+ * otherwise. Pure helper, exported for tests.
+ */
+function detectStaleRefError(result) {
+    if (result === null || result === undefined || typeof result !== 'object')
+        return null;
+    const r = result;
+    if (r.success !== false)
+        return null;
+    if (typeof r.error !== 'string' || r.error.length === 0)
+        return null;
+    for (const pattern of exports.STALE_REF_PATTERNS) {
+        if (pattern.test(r.error)) {
+            return pattern.source;
+        }
+    }
+    return null;
+}
+/**
+ * Test whether a tool result represents success. Used by the HOC to
+ * decide whether the retry "succeeded" and should become canonical.
+ */
+function isSuccessResult(result) {
+    if (result === null || result === undefined || typeof result !== 'object')
+        return false;
+    return result.success === true;
+}
+const defaultPageTextFetcher = () => (0, playwrightBridge_1.pwSnapshot)();
+function withBrowserState(handler, state = exports.browserState, 
+/**
+ * Optional page-text fetcher. Production code uses pwSnapshot;
+ * tests inject a stub returning canned text for the blocker
+ * detection tier. The fetcher is called ONCE per action when
+ * browser depth is enabled — disabled path skips entirely.
+ */
+pageTextFetcher = defaultPageTextFetcher) {
+    return {
+        ...handler,
+        async execute(args, ctx) {
+            if (!state.isEnabled()) {
+                return handler.execute(args, ctx);
+            }
+            const pre = await state.captureState();
+            let result = await handler.execute(args, ctx);
+            // v4.3 Phase 3 — manual-blocker detection. Runs on every
+            // browser-tool result when enabled. Uses the configured
+            // page-text fetcher (pwSnapshot in production). Detection
+            // never breaks the inner tool — pwSnapshot is wrapped in
+            // try/catch via the fetcher itself; failures produce no
+            // blocker and no observer sidecar field.
+            //
+            // The detected blocker is BOTH embedded on the result sidecar
+            // (Phase 5 + chat layer consumers) AND used to suppress
+            // Phase 2's stale-ref retry below. Pause-and-surface contract
+            // (Q-CDP5) — never auto-action a blocker.
+            let blocker;
+            try {
+                const snap = await pageTextFetcher();
+                if (snap.ok && snap.text) {
+                    const url = result?.url ?? '';
+                    const detected = (0, browserBlocker_1.detectBlocker)({ text: snap.text, url });
+                    if (detected)
+                        blocker = detected;
+                }
+            }
+            catch { /* detection never breaks the inner tool */ }
+            // v4.3 Phase 4 — propagate blocker (or its absence) to the
+            // active tab's metadata in BrowserState. Cross-tab queries can
+            // then ask "is there a pending blocker on any tab" without
+            // re-running detection. No-op when state is disabled or when
+            // the tabs map has no active entry (the reconciliation in
+            // captureState above sets activeTabId).
+            try {
+                state.updateActiveTabBlocker(blocker
+                    ? {
+                        kind: blocker.kind,
+                        subtype: blocker.subtype,
+                        url: blocker.url,
+                        confidence: blocker.confidence,
+                    }
+                    : null);
+            }
+            catch { /* defensive — tab updates never break the inner tool */ }
+            // v4.3 Phase 2 — stale-ref retry. Reactive: fires only after a
+            // resolution-class failure on an interactive tool. One retry
+            // hard cap. Safe because the resolution-class errors fire
+            // BEFORE any DOM event is dispatched, so retry can't double-act.
+            //
+            // v4.3 Phase 3 suppression: skip the retry when a manual
+            // blocker is present (`!blocker` gate). A blocker means the
+            // page is asking for human action — retrying the same tool
+            // call against a sign-in wall or 2FA prompt won't help and
+            // looks like agent thrashing.
+            let staleRefRetry;
+            if (pre && !blocker &&
+                exports.STALE_REF_RETRYABLE.has(handler.schema.name)) {
+                const staleReason = detectStaleRefError(result);
+                if (staleReason !== null) {
+                    // Resnapshot — the "between" state. We use it for the
+                    // diagnostic state_delta. The retry fires unconditionally
+                    // (per Q-P2-3 single-signal rule): even when DOM hash
+                    // hasn't changed, a transient race condition (element
+                    // attached one tick after the original timeout) is the
+                    // common case the retry catches.
+                    const between = await state.captureState();
+                    const state_delta = state.computeStateDelta(pre, between);
+                    const retryResult = await handler.execute(args, ctx);
+                    const retryOk = isSuccessResult(retryResult);
+                    staleRefRetry = {
+                        attempted: true,
+                        succeeded: retryOk,
+                        reason: staleReason,
+                        state_delta,
+                    };
+                    // If retry succeeded, the retry result becomes canonical.
+                    // If retry failed, keep the original failure — its error
+                    // context is what the model needs to see, and a same-error
+                    // retry would just look like duplicated chrome.
+                    if (retryOk)
+                        result = retryResult;
+                }
+            }
+            const post = await state.captureState();
+            const observerMeta = state.buildActionResult({ pre, post });
+            if (observerMeta &&
+                result !== null && result !== undefined &&
+                typeof result === 'object' && !Array.isArray(result)) {
+                const sidecar = {
+                    ...observerMeta,
+                    ...(staleRefRetry && { staleRefRetry }),
+                    ...(blocker && { blocker }),
+                };
+                return { ...result, browserState: sidecar };
+            }
+            return result;
+        },
+    };
+}

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);