@thinkrun/cli 0.1.27

package/dist/src/adapters/local.js

@@ -0,0 +1,1273 @@
+/**
+ * Local adapter — routes browser actions to the native host HTTP API
+ * (localhost:PORT/sessions/:tabId/*). No API key required; uses the
+ * active tabId stored by `thinkrun attach`.
+ */
+import { writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { ApiError, SessionError } from '../errors.js';
+import { config } from '../config/store.js';
+import { readBridgePort, DEFAULT_BRIDGE_PORT, BRIDGE_HEALTH_PROBE_TIMEOUT_MS, BRIDGE_REQUEST_TIMEOUT_MS, unwrapEvaluatePayload, } from '../utils.js';
+import { clearLocalSessionContext, getLocalSessionContext, setLocalSessionContext } from '../session/context.js';
+import { initCliSession, syncBrowserAction, syncScreenshotAction, closeCliSession, readCliSessionId } from '../session/cli-session-sync.js';
+import { acquireLock, getLockedBy, getWorkingLocation, releaseWorkingLocation, setWorkingLocation, updateWorkingLocationControlSession } from '../working-location.js';
+import { resolveAgentId } from '../session/agent-identity.js';
+import { localCommandRequiresTabError } from '../session/errors.js';
+import { assessLocalContinuity } from '../session/local-continuity.js';
+import { classifyFromBridgeResult, classifyFromStateCheck } from '../protected-flow/detector.js';
+import { captureFingerprint, compareFingerprints } from '../obstacle-recovery/state-fingerprint.js';
+import { classifyElementFailure } from '../obstacle-recovery/obstacle-classifier.js';
+import { getLocalCommandRetryProfileFromPath, } from './local-command-retry.js';
+import { LOCAL_BRIDGE_TYPED_TRANSPORT_RECOVERY_ATTEMPTS, LOCAL_BRIDGE_TYPED_EXTENSION_REVALIDATION_DELAYS_MS, LOCAL_BRIDGE_TYPED_RECENT_DISCONNECT_GRACE_MS, } from '../local-bridge-timing.js';
+/** Tunable post-action settle delay (ms). React batches setState updates
+ *  (~16ms); 50ms gives margin for async DOM mutations to settle. */
+const POST_ACTION_SETTLE_MS = 50;
+/**
+ * Actionable hints keyed by native host error codes.
+ * These are surfaced in structured error output (--json mode) and TTY tips.
+ */
+const NATIVE_CODE_HINTS = {
+    EXTENSION_NOT_CONNECTED: 'Open a Chromium-based browser (e.g. Chrome or Helium) with the ThinkRun extension active',
+    TAB_NOT_FOUND: 'Tab was closed. Run: thinkrun tabs, then: thinkrun attach <tabId>',
+    ELEMENT_NOT_FOUND: 'Check selector. Run: thinkrun snapshot to inspect page structure',
+    NAVIGATION_FAILED: 'Check the URL and network connectivity',
+    REQUEST_TIMEOUT: 'Tab is taking a long time to respond — it may be a background tab throttled by the browser. Try bringing the tab into focus in the browser window, then retry.',
+    COMMAND_TIMEOUT: 'Extension command timed out; the tab may be frozen',
+    SCRIPT_ERROR: 'JavaScript error in evaluate script. Check the syntax',
+    TAB_NOT_OWNED: 'Tab not owned by this session. Run: thinkrun attach <tabId>',
+    TAB_OWNED_BY_OTHER_SESSION: 'Stay in local ThinkRun and run: thinkrun session debug --json. ' +
+        'Use thinkrun tabs --json to inspect ownerSessionId for the tab. ' +
+        'If the tab is truly owned by another live session, open a new tab/window instead of trying to take it over. ' +
+        'If the tab should still belong to your current workflow, re-attach or follow the continuity guidance from session debug before retrying a mutating command. ' +
+        'Do not use cloud start without an API key. Do not invent flags; see thinkrun attach --help. ' +
+        'Human docs: https://thinkbrowse.io/docs — LLM-oriented summary: https://thinkbrowse.io/llms.txt (repo: docs/ERROR_CODES.md).',
+    TAB_LOCKED: 'Another local controller currently holds the tab lock or an exclusive stale-lock reclaim claim. ' +
+        'Run: thinkrun session debug --json to inspect the current continuity state before retrying. ' +
+        'If this is your own stale state, wait for the reclaim attempt to finish or re-run the command once the competing claim is gone.',
+    SESSION_NOT_FOUND: 'The attached local tab lost its bridge registration. Run: thinkrun session debug --json to confirm the persisted local tab binding, then re-register it with: thinkrun attach <tabId>.',
+};
+/** Actionable hint for native host error codes (TTY tips and JSON `hint` field). */
+export function getNativeCodeHint(code) {
+    if (!code)
+        return undefined;
+    return NATIVE_CODE_HINTS[code];
+}
+export class LocalAdapter {
+    baseUrl;
+    defaultTimeout = 60000;
+    validatedTabCache = new Map();
+    TAB_CACHE_TTL_MS = 60_000;
+    /** Injected fetch function — allows unit tests to intercept all HTTP calls. */
+    fetchFn;
+    /**
+     * When set (via --tab flag or THINKRUN_TAB_ID env), bypasses the global
+     * working-location.json entirely. Each command targets this tab directly.
+     */
+    tabOverride;
+    readBridgePortFn;
+    diagnosticsEnabled;
+    constructor(port, fetchFn, tabOverride, readBridgePortFn = readBridgePort) {
+        this.readBridgePortFn = readBridgePortFn;
+        const resolvedPort = port ?? this.readBridgePortFn() ?? DEFAULT_BRIDGE_PORT;
+        this.baseUrl = `http://127.0.0.1:${resolvedPort}`;
+        this.fetchFn = fetchFn ?? globalThis.fetch;
+        this.tabOverride = tabOverride;
+        this.diagnosticsEnabled = process.env['THINKRUN_LOCAL_DIAGNOSTICS'] === '1';
+    }
+    /** Read the agent session ID from config (set by `thinkrun attach`). */
+    getAgentSessionId() {
+        return getLocalSessionContext()?.agentSessionId;
+    }
+    rethrowTabLock(error) {
+        if (error instanceof ApiError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith('TAB_LOCKED')) {
+            throw new ApiError(message, undefined, getNativeCodeHint('TAB_LOCKED'), 'TAB_LOCKED', false);
+        }
+        throw error;
+    }
+    /**
+     * Fire-and-forget: sync a browser action to the cloud session activity feed.
+     * No-op if no cloud sessionId is persisted for the tab (e.g. no API key configured).
+     * Never throws, never blocks the caller.
+     */
+    syncAction(tabId, type, details) {
+        const sessionId = readCliSessionId(tabId);
+        if (!sessionId)
+            return;
+        syncBrowserAction(sessionId, type, details, this.fetchFn);
+    }
+    refreshBaseUrl() {
+        const nextPort = this.readBridgePortFn() ?? DEFAULT_BRIDGE_PORT;
+        this.baseUrl = `http://127.0.0.1:${nextPort}`;
+    }
+    isTransientBridgeError(error) {
+        if (!(error instanceof Error))
+            return false;
+        if (error.name === 'TimeoutError')
+            return true;
+        if (error.message === 'fetch failed')
+            return true;
+        const code = error.code;
+        return code === 'ECONNREFUSED';
+    }
+    isPreDispatchBridgeDisconnect(error) {
+        if (!(error instanceof Error))
+            return false;
+        if (error.name === 'TimeoutError')
+            return false;
+        if (error.message === 'fetch failed')
+            return true;
+        const code = error.code;
+        return code === 'ECONNREFUSED';
+    }
+    logDiagnostics(message, fields = {}) {
+        if (!this.diagnosticsEnabled)
+            return;
+        const suffix = Object.keys(fields).length > 0 ? ` ${JSON.stringify(fields)}` : '';
+        process.stderr.write(`[thinkrun-local] ${message}${suffix}\n`);
+    }
+    async probeBridgeHealth(baseUrl = this.baseUrl) {
+        try {
+            const response = await this.fetchFn(`${baseUrl}/health`, {
+                signal: AbortSignal.timeout(BRIDGE_HEALTH_PROBE_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                return { reachable: false };
+            const json = await response.json();
+            const inner = json?.data;
+            const extensionConnected = typeof inner?.extensionConnected === 'boolean'
+                ? inner.extensionConnected
+                : typeof json?.extensionConnected === 'boolean'
+                    ? json.extensionConnected
+                    : undefined;
+            const lastDisconnectReason = typeof inner?.lastExtensionDisconnectReason === 'string'
+                ? inner.lastExtensionDisconnectReason
+                : typeof json?.lastExtensionDisconnectReason === 'string'
+                    ? json.lastExtensionDisconnectReason
+                    : undefined;
+            const lastDisconnectAtRaw = typeof inner?.lastExtensionDisconnectAt === 'string'
+                ? inner.lastExtensionDisconnectAt
+                : typeof json?.lastExtensionDisconnectAt === 'string'
+                    ? json.lastExtensionDisconnectAt
+                    : undefined;
+            const recoveryState = typeof inner?.recoveryState === 'string'
+                ? inner.recoveryState
+                : typeof json?.recoveryState === 'string'
+                    ? json.recoveryState
+                    : undefined;
+            const parsedLastDisconnectAt = typeof lastDisconnectAtRaw === 'string'
+                ? Date.parse(lastDisconnectAtRaw)
+                : Number.NaN;
+            const lastDisconnectAt = Number.isNaN(parsedLastDisconnectAt)
+                ? undefined
+                : parsedLastDisconnectAt;
+            return {
+                reachable: true,
+                extensionConnected,
+                lastDisconnectReason,
+                lastDisconnectAt,
+                recoveryState,
+            };
+        }
+        catch {
+            return { reachable: false };
+        }
+    }
+    getLiveExtensionDisconnectHint(lastDisconnectReason, recoveryState) {
+        if (recoveryState === 'flapping') {
+            return 'A live bridge health probe confirms the local bridge is flapping from repeated disconnects. Avoid patient retry loops; reload the ThinkRun extension or stabilize the page/browser before retrying.';
+        }
+        if (typeof lastDisconnectReason === 'string' && lastDisconnectReason.startsWith('Circuit breaker:')) {
+            return 'A live bridge health probe confirms extensionConnected=false because the circuit breaker is open. Run: thinkrun reset-connection';
+        }
+        return 'A live bridge health probe confirms extensionConnected=false right now. Reload the ThinkRun extension in your Chromium-based browser, then retry.';
+    }
+    isRecentDisconnectedState(health) {
+        return health.extensionConnected === false
+            && health.recoveryState === 'disconnected'
+            && typeof health.lastDisconnectAt === 'number'
+            && Date.now() - health.lastDisconnectAt <= LOCAL_BRIDGE_TYPED_RECENT_DISCONNECT_GRACE_MS;
+    }
+    async revalidateExtensionConnection() {
+        const probeCurrentBridge = async () => this.probeBridgeHealth(this.baseUrl);
+        const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+        let latest = await probeCurrentBridge();
+        if (latest.extensionConnected === true) {
+            return { recovered: true };
+        }
+        const previousBase = this.baseUrl;
+        this.refreshBaseUrl();
+        if (this.baseUrl !== previousBase) {
+            latest = await probeCurrentBridge();
+            if (latest.extensionConnected === true) {
+                return { recovered: true };
+            }
+        }
+        const shouldWaitForRecovery = latest.reachable === false
+            || latest.extensionConnected === undefined
+            || latest.recoveryState === 'recovering'
+            || latest.recoveryState === 'recently_recovered'
+            || this.isRecentDisconnectedState(latest);
+        if (shouldWaitForRecovery) {
+            for (const delayMs of LOCAL_BRIDGE_TYPED_EXTENSION_REVALIDATION_DELAYS_MS) {
+                await sleep(delayMs);
+                latest = await probeCurrentBridge();
+                if (latest.extensionConnected === true) {
+                    return { recovered: true };
+                }
+                if (latest.reachable !== false
+                    && latest.extensionConnected !== undefined
+                    && latest.recoveryState !== 'recovering'
+                    && latest.recoveryState !== 'recently_recovered'
+                    && !this.isRecentDisconnectedState(latest)) {
+                    break;
+                }
+            }
+        }
+        if (latest.extensionConnected === false) {
+            return { recovered: false, hint: this.getLiveExtensionDisconnectHint(latest.lastDisconnectReason, latest.recoveryState) };
+        }
+        return { recovered: false };
+    }
+    extractTabIdFromSessionPath(path) {
+        const match = path.match(/^\/sessions\/(\d+)\//);
+        return match?.[1];
+    }
+    async tryRecoverMissingSession(path) {
+        if (this.tabOverride)
+            return false;
+        const localContext = getLocalSessionContext();
+        const agentSessionId = localContext?.agentSessionId;
+        const tabId = localContext?.tabId;
+        const pathTabId = this.extractTabIdFromSessionPath(path);
+        if (!agentSessionId || !tabId || !pathTabId || pathTabId !== tabId) {
+            return false;
+        }
+        try {
+            const response = await this.fetchFn(`${this.baseUrl}/sessions/register`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ tabId: Number(tabId), sessionId: agentSessionId }),
+                signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                return false;
+            const json = await response.json();
+            const reboundSessionId = typeof json?.data?.sessionId === 'string' && json.data.sessionId.length > 0
+                ? json.data.sessionId
+                : agentSessionId;
+            setLocalSessionContext(tabId, reboundSessionId, localContext.windowId);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    tryRepairMissingMutatingAuthority() {
+        if (this.tabOverride)
+            return false;
+        const localContext = getLocalSessionContext();
+        if (!localContext?.tabId)
+            return false;
+        const workingLocation = getWorkingLocation();
+        const continuity = assessLocalContinuity(localContext, workingLocation);
+        if (continuity.state !== 'same_controller_missing_mutating_authority_state'
+            && continuity.state !== 'same_controller_read_resumable') {
+            return false;
+        }
+        try {
+            if (workingLocation && localContext.controlSessionId) {
+                updateWorkingLocationControlSession(localContext.controlSessionId);
+                return true;
+            }
+            if (workingLocation && !localContext.controlSessionId) {
+                setLocalSessionContext(localContext.tabId, localContext.agentSessionId, localContext.windowId);
+                return true;
+            }
+            if (!workingLocation) {
+                setWorkingLocation({
+                    tabId: Number(localContext.tabId),
+                    ...(typeof localContext.windowId === 'number' ? { windowId: localContext.windowId } : {}),
+                    ...(localContext.controlSessionId ? { controlSessionId: localContext.controlSessionId } : {}),
+                });
+                if (!localContext.controlSessionId) {
+                    setLocalSessionContext(localContext.tabId, localContext.agentSessionId, localContext.windowId);
+                }
+                return true;
+            }
+        }
+        catch {
+            return false;
+        }
+        return false;
+    }
+    /**
+     * Pre-action check: if this process has a working location set (via `attach`
+     * or `new-window`) and the configured active tab has drifted away from it,
+     * silently re-switch the bridge to the working-location tab.
+     *
+     * This prevents "tab stolen by another agent" where a second agent's `attach`
+     * changes the bridge's active tab mid-session.
+     */
+    async ensureWorkingLocationTab() {
+        const loc = getWorkingLocation();
+        if (!loc)
+            return; // no lock set — nothing to enforce
+        const ctx = getLocalSessionContext();
+        const workingTabId = String(loc.tabId);
+        if (ctx && workingTabId === ctx.tabId)
+            return; // already on the right tab
+        // The context points to a different tab than our lock. Re-switch silently.
+        // Regardless of whether the bridge switch succeeds or fails, always update the
+        // local context to the working-location tab so subsequent getActiveTabId() calls
+        // reference the right tab. If the tab is truly gone, getActiveTabId's validation
+        // will surface the error.
+        let reboundAgentSessionId;
+        try {
+            const res = await this.fetchFn(`${this.baseUrl}/api/tabs/switch`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ tabId: loc.tabId }),
+                signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+            });
+            // Non-2xx from the bridge (tab not found, internal error, etc.) is treated
+            // the same as a network failure — let finally handle context update.
+            if (!res.ok)
+                throw new Error(`tab-switch HTTP ${res.status}`);
+            // Important: do NOT preserve ctx.agentSessionId here. On a handoff or
+            // stale shared-config race, that session id may still belong to the old
+            // tab. Refresh the binding for the working-location tab instead.
+            const registerRes = await this.fetchFn(`${this.baseUrl}/sessions/register`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ tabId: loc.tabId }),
+                signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+            });
+            if (registerRes.ok) {
+                const registerJson = await registerRes.json();
+                reboundAgentSessionId = registerJson?.data?.sessionId;
+            }
+        }
+        catch {
+            // Best-effort — finally will update context regardless.
+        }
+        finally {
+            try {
+                const { setLocalSessionContext } = await import('../session/context.js');
+                setLocalSessionContext(workingTabId, reboundAgentSessionId, loc.windowId);
+            }
+            catch { /* ignore */ }
+        }
+        // Re-confirm lock ownership after drift correction. If another process has
+        // taken the lock (TAB_LOCKED), this throws and surfaces as an explicit error
+        // rather than silent commands targeting the wrong tab.
+        // Pass loc.group so the re-acquire does not strip group membership from the lock file.
+        const { acquireLock } = await import('../working-location.js');
+        try {
+            acquireLock(loc.tabId, loc.group);
+        }
+        catch (error) {
+            this.rethrowTabLock(error);
+        }
+    }
+    assertOwnedTab(tabId) {
+        const lock = getLockedBy(Number(tabId));
+        if (!lock)
+            return;
+        const currentAgentId = resolveAgentId();
+        const ownedByAgent = !!lock.agentId && lock.agentId === currentAgentId;
+        const ownedByPid = !lock.agentId && lock.pid === process.pid;
+        if (ownedByAgent || ownedByPid)
+            return;
+        const continuity = assessLocalContinuity(getLocalSessionContext(), getWorkingLocation());
+        if (continuity.state === 'stale_reclaimable' && continuity.effectiveTabId === tabId) {
+            try {
+                acquireLock(Number(tabId), getWorkingLocation()?.group);
+            }
+            catch (error) {
+                this.rethrowTabLock(error);
+            }
+            return;
+        }
+        const owner = lock.agentId
+            ? `agent ${lock.agentId}`
+            : `PID ${lock.ownerShellPid ?? lock.pid}`;
+        throw new ApiError(`Tab ${tabId} is owned by another local session (${owner})`, undefined, getNativeCodeHint('TAB_OWNED_BY_OTHER_SESSION'), 'TAB_OWNED_BY_OTHER_SESSION', false);
+    }
+    /**
+     * Returns the active tab ID, validating it still exists against the native
+     * host's /tabs list. Results are cached within this adapter instance's lifetime
+     * (a single CLI command invocation). The cache does NOT persist between commands —
+     * the CLI starts a new process for each invocation so `validatedTabCache` is always
+     * empty at command start. Clears the stored local session if the tab is gone.
+     */
+    async getActiveTabId() {
+        // --tab override: bypass working-location.json entirely
+        if (this.tabOverride) {
+            this.assertOwnedTab(this.tabOverride);
+            return this.tabOverride;
+        }
+        await this.ensureWorkingLocationTab();
+        const tabId = getLocalSessionContext()?.tabId;
+        if (!tabId) {
+            throw localCommandRequiresTabError();
+        }
+        this.assertOwnedTab(tabId);
+        const lastValidated = this.validatedTabCache.get(tabId);
+        if (lastValidated && Date.now() - lastValidated < this.TAB_CACHE_TTL_MS) {
+            return tabId;
+        }
+        try {
+            const fetchTabs = async () => {
+                const response = await this.fetchFn(`${this.baseUrl}/tabs`, {
+                    signal: AbortSignal.timeout(BRIDGE_HEALTH_PROBE_TIMEOUT_MS),
+                });
+                if (!response.ok)
+                    return [];
+                const json = (await response.json());
+                return json?.data?.tabs ?? [];
+            };
+            const localContext = getLocalSessionContext();
+            const workingLocation = getWorkingLocation();
+            const expectedTabId = Number(tabId);
+            const expectedWindowId = localContext?.windowId;
+            const updatedAtMs = typeof localContext?.updatedAt === 'string'
+                ? Date.parse(localContext.updatedAt)
+                : Number.NaN;
+            const freshBinding = Number.isFinite(updatedAtMs)
+                && Date.now() - updatedAtMs < 5_000;
+            let tabs = await fetchTabs();
+            let found = tabs.find((t) => String(t.id) === tabId);
+            const fingerprintMismatch = () => typeof expectedWindowId === 'number'
+                && typeof found?.windowId === 'number'
+                && found.windowId !== expectedWindowId;
+            const sameRuntimeOwner = typeof localContext?.agentSessionId === 'string'
+                && localContext.agentSessionId.length > 0
+                && typeof found?.id === 'number'
+                && found.id === expectedTabId
+                && typeof found?.ownerSessionId === 'string'
+                && found.ownerSessionId === localContext.agentSessionId;
+            if (freshBinding && (!found || fingerprintMismatch())) {
+                await new Promise((resolve) => setTimeout(resolve, 500));
+                tabs = await fetchTabs();
+                found = tabs.find((t) => String(t.id) === tabId);
+            }
+            if (tabs.length > 0) {
+                let healedWindowMismatch = false;
+                if (!found) {
+                    clearLocalSessionContext();
+                    releaseWorkingLocation(workingLocation?.group);
+                    throw new SessionError(`Tab ${tabId} is no longer open`, 'Run: thinkrun tabs\nThen: thinkrun attach <tabId>');
+                }
+                if (fingerprintMismatch()) {
+                    if (sameRuntimeOwner) {
+                        const healedAgentSessionId = localContext.agentSessionId;
+                        // Extension reconnects can legitimately re-home the same owned tab into a
+                        // different window record. Heal that drift only when the /tabs entry still
+                        // proves both the expected tab id and the same runtime owner session.
+                        setWorkingLocation({
+                            tabId: expectedTabId,
+                            windowId: found.windowId,
+                            ...(workingLocation?.group ? { group: workingLocation.group } : {}),
+                            ...(localContext?.controlSessionId ? { controlSessionId: localContext.controlSessionId } : {}),
+                        });
+                        setLocalSessionContext(String(expectedTabId), healedAgentSessionId, found.windowId);
+                        healedWindowMismatch = true;
+                    }
+                    else {
+                        clearLocalSessionContext();
+                        releaseWorkingLocation(workingLocation?.group);
+                        throw new SessionError(`Tab ${tabId} no longer matches the persisted local binding`, `Persisted continuity expected tab ${tabId} in window ${expectedWindowId}, but the live browser now reports window ${found.windowId}. This usually means the original tab was closed and the browser reused the tab ID. Run: thinkrun tabs\nThen: thinkrun attach <tabId>`);
+                    }
+                }
+                if (!healedWindowMismatch && typeof found.windowId === 'number' && localContext?.windowId !== found.windowId) {
+                    setLocalSessionContext(tabId, localContext?.agentSessionId, found.windowId);
+                }
+                this.validatedTabCache.set(tabId, Date.now());
+            }
+            // If validation fetch returns non-200, skip caching and let command fail naturally
+        }
+        catch (error) {
+            if (error instanceof SessionError)
+                throw error;
+            // Swallow network errors during validation — the actual command will give a better error
+        }
+        return tabId;
+    }
+    async request(path, options = {}) {
+        const httpMs = options.timeoutMs ?? this.defaultTimeout;
+        const method = (options.method ?? 'GET').toUpperCase();
+        const requestId = `local-${randomUUID().slice(0, 8)}`;
+        const retryProfile = getLocalCommandRetryProfileFromPath(path, method);
+        if (retryProfile.outcomeRisk === 'unknown_if_request_left_process') {
+            this.tryRepairMissingMutatingAuthority();
+        }
+        for (let attempt = 0; attempt < LOCAL_BRIDGE_TYPED_TRANSPORT_RECOVERY_ATTEMPTS; attempt += 1) {
+            try {
+                const headers = {
+                    'Content-Type': 'application/json',
+                    'x-thinkrun-request-id': requestId,
+                };
+                // When tabOverride is set (--tab flag), don't send x-session-id — the session
+                // belongs to whoever attached, not to us. The tabId in the URL path is sufficient.
+                const sessionId = this.tabOverride ? undefined : this.getAgentSessionId();
+                if (sessionId) {
+                    headers['x-session-id'] = sessionId;
+                }
+                this.logDiagnostics('bridge_request_start', {
+                    requestId,
+                    method,
+                    path,
+                    attempt: attempt + 1,
+                    sessionId: sessionId ?? null,
+                    tabOverride: this.tabOverride ?? null,
+                    timeoutMs: httpMs,
+                });
+                const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+                    method: options.method ?? 'GET',
+                    headers,
+                    body: options.body,
+                    signal: AbortSignal.timeout(httpMs),
+                });
+                const json = (await response.json());
+                this.logDiagnostics('bridge_request_end', {
+                    requestId,
+                    method,
+                    path,
+                    attempt: attempt + 1,
+                    status: response.status,
+                    ok: response.ok,
+                    success: json?.success ?? null,
+                    code: json?.code ?? null,
+                });
+                // Blocked-flow contract: bridge may signal blocked with success: true, data.blocked (preferred)
+                // or with success: false, data.blocked. In either case we return the response so callers
+                // can run classifyFromBridgeResult(response.data) and surface a handoff instead of ApiError.
+                const isBlockedFlow = json?.data && typeof json.data === 'object' && json.data.blocked === true;
+                if (!response.ok || (json.success === false && !isBlockedFlow)) {
+                    const code = json.code ?? 'API_ERROR';
+                    let hint = NATIVE_CODE_HINTS[code];
+                    if (code === 'SESSION_NOT_FOUND' && attempt === 0) {
+                        const recovered = await this.tryRecoverMissingSession(path);
+                        if (recovered) {
+                            continue;
+                        }
+                        const continuity = assessLocalContinuity(getLocalSessionContext(), getWorkingLocation());
+                        if (continuity.state === 'same_controller_missing_runtime_registration'
+                            || continuity.state === 'same_controller_read_resumable') {
+                            hint =
+                                `${continuity.hint} ` +
+                                    'Run: thinkrun session debug --json to confirm the local continuity state, then retry the mutating command or re-attach if the runtime session cannot be repaired automatically.';
+                        }
+                    }
+                    if (code === 'TAB_OWNED_BY_OTHER_SESSION') {
+                        const localContext = getLocalSessionContext();
+                        const workingLocation = getWorkingLocation();
+                        const continuity = assessLocalContinuity(localContext, workingLocation);
+                        const directSameControllerLeaseMismatch = localContext?.tabId
+                            && workingLocation
+                            && localContext.tabId === String(workingLocation.tabId)
+                            && workingLocation.agentId === resolveAgentId()
+                            && !!localContext.controlSessionId
+                            && !!workingLocation.controlSessionId
+                            && localContext.controlSessionId !== workingLocation.controlSessionId;
+                        if (directSameControllerLeaseMismatch) {
+                            hint =
+                                `Targeting continuity still exists for tab ${localContext?.tabId ?? workingLocation?.tabId ?? 'this tab'}, ` +
+                                    'but the mutating-authority lease is missing or inconsistent between the persisted local context and the working-location lock. ' +
+                                    'Run: thinkrun session debug --json before retrying. If continuity is still proven, re-attach only to rebuild authority state, not to take over a foreign tab.';
+                        }
+                        else if (continuity.state.startsWith('same_controller_') && !continuity.controlLeaseHeld) {
+                            hint =
+                                `${continuity.hint} ` +
+                                    'Run: thinkrun session debug --json before retrying. If continuity is still proven, re-attach only to rebuild authority state, not to take over a foreign tab.';
+                        }
+                        else if (continuity.state === 'stale_reclaimable') {
+                            hint =
+                                `${continuity.hint} ` +
+                                    'Use thinkrun session debug --json to inspect the stale owner evidence before reclaiming the tab.';
+                        }
+                        else if (continuity.state === 'foreign_controller_live') {
+                            hint =
+                                `${continuity.hint} ` +
+                                    'Use thinkrun tabs --json to inspect ownerSessionId. Cross-agent takeover is not supported safely in v1.';
+                        }
+                    }
+                    if (code === 'EXTENSION_NOT_CONNECTED') {
+                        const revalidated = await this.revalidateExtensionConnection();
+                        // EXTENSION_NOT_CONNECTED is raised before the native host can
+                        // dispatch the request to the extension when the bridge already
+                        // knows the extension is disconnected. If live health confirms
+                        // the extension has recovered immediately after that rejection,
+                        // the original command never reached the page and is safe to
+                        // replay once even when its generic transport profile is not.
+                        if (attempt === 0 && revalidated.recovered) {
+                            await this.tryRecoverMissingSession(path);
+                            continue;
+                        }
+                        if (revalidated.hint) {
+                            hint = revalidated.hint;
+                        }
+                        else if (revalidated.recovered && retryProfile.outcomeRisk === 'unknown_if_request_left_process') {
+                            hint = `The "${retryProfile.description}" command may already have completed before the extension disconnected. Verify the page state before retrying. If the bridge remains unstable, run thinkrun session debug or thinkrun doctor.`;
+                        }
+                    }
+                    const apiErr = new ApiError(json.error || 'Native host request failed', response.status, hint, code, json.retryable);
+                    // PRD 0086 6.2b — preserve the daemon's policy-driven recovery signal
+                    // across the HTTP boundary so it reaches typed CLI callers (FU-4 wires
+                    // the actual replay decision to these fields).
+                    if (typeof json.outcome === 'string')
+                        apiErr.deliveryOutcome = json.outcome;
+                    if (typeof json.replay === 'string')
+                        apiErr.replayPolicy = json.replay;
+                    if (typeof json.retryHint === 'string')
+                        apiErr.retryHint = json.retryHint;
+                    throw apiErr;
+                }
+                return json;
+            }
+            catch (error) {
+                this.logDiagnostics('bridge_request_error', {
+                    requestId,
+                    method,
+                    path,
+                    attempt: attempt + 1,
+                    error: error?.message ?? String(error),
+                    code: error?.code ?? null,
+                    transient: this.isTransientBridgeError(error),
+                    retryProfile: retryProfile.key,
+                });
+                if (error instanceof ApiError)
+                    throw error;
+                if (attempt === 0 && this.isTransientBridgeError(error)) {
+                    const prevBase = this.baseUrl;
+                    this.refreshBaseUrl();
+                    const baseChanged = this.baseUrl !== prevBase;
+                    if (this.isPreDispatchBridgeDisconnect(error)) {
+                        const revalidated = await this.revalidateExtensionConnection();
+                        if (revalidated.recovered) {
+                            await this.tryRecoverMissingSession(path);
+                            continue;
+                        }
+                    }
+                    const canReplay = retryProfile.transportReplay === 'safe_same_bridge'
+                        || (retryProfile.transportReplay === 'only_after_route_change' && baseChanged);
+                    if (canReplay) {
+                        continue;
+                    }
+                    const suggestion = retryProfile.outcomeRisk === 'unknown_if_request_left_process'
+                        ? `The "${retryProfile.description}" command may already have completed before the bridge disconnected. Verify the page state before retrying. If the bridge remains unstable, run thinkrun session debug or thinkrun doctor.`
+                        : `Start the native host by opening a Chromium-based browser (e.g. Chrome or Helium) with the ThinkRun extension, or check if it is running at ${this.baseUrl}`;
+                    throw new ApiError('Native host not reachable', undefined, suggestion, 'NATIVE_HOST_UNREACHABLE', false);
+                }
+                if (this.isTransientBridgeError(error)) {
+                    throw new ApiError('Native host not reachable', undefined, `Start the native host by opening a Chromium-based browser (e.g. Chrome or Helium) with the ThinkRun extension, or check if it is running at ${this.baseUrl}`, 'NATIVE_HOST_UNREACHABLE', true);
+                }
+                throw new ApiError(error.message || 'Local request failed');
+            }
+        }
+        throw new ApiError('LocalAdapter.request: unreachable (internal)', undefined, undefined, 'INTERNAL_ERROR');
+    }
+    // --- Session Management ---
+    /**
+     * In local mode this does not start a cloud browser.  However, if an API
+     * key is configured the session is registered in the cloud activity feed
+     * so screenshots and actions appear alongside cloud/extension sessions.
+     * Without an API key this is a silent no-op (no error).
+     */
+    async startSession(_options = {}) {
+        let tabId;
+        try {
+            tabId = getLocalSessionContext()?.tabId;
+        }
+        catch { /* mixed session state — treat as no tab */ }
+        if (tabId) {
+            // Best-effort — result written to disk by initCliSession; ignore here.
+            await initCliSession(tabId, this.fetchFn);
+        }
+        return {
+            sessionId: tabId ?? 'local',
+            status: 'running',
+            createdAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * In local mode this does not stop a cloud browser.  If a session was
+     * registered via startSession(), a fire-and-forget local-close request
+     * is sent to mark it completed in the activity feed.
+     */
+    async stopSession(_sessionId) {
+        let tabId;
+        try {
+            tabId = getLocalSessionContext()?.tabId;
+        }
+        catch { /* mixed session state — treat as no tab */ }
+        if (tabId) {
+            closeCliSession(tabId, 'completed', this.fetchFn);
+        }
+    }
+    async getSession(sessionId) {
+        const response = await this.request(`/sessions/${sessionId}`);
+        const d = response.data ?? {};
+        return {
+            sessionId,
+            status: 'running',
+            currentUrl: d.url,
+            title: d.title,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    async listSessions() {
+        const response = await this.request('/tabs');
+        const tabs = response.data?.tabs ?? [];
+        return tabs.map((t) => ({
+            sessionId: String(t.id),
+            status: 'running',
+            currentUrl: t.url,
+            title: t.title,
+            createdAt: new Date().toISOString(),
+        }));
+    }
+    async waitForSessionReady(sessionId, _timeout) {
+        return this.getSession(sessionId);
+    }
+    // --- Navigation ---
+    async navigate(url, options = {}) {
+        const tabId = await this.getActiveTabId();
+        try {
+            const response = await this.request(`/sessions/${tabId}/navigate`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    url,
+                    waitUntil: options.waitUntil ?? 'load',
+                    timeout: options.timeout,
+                }),
+            });
+            if (response.success) {
+                // Prefer the post-navigation URL from the response (handles redirects/canonicalization).
+                const syncedUrl = typeof response.data?.url === 'string' && response.data.url.length > 0
+                    ? response.data.url
+                    : url;
+                this.syncAction(tabId, 'navigate', { url: syncedUrl });
+            }
+            return { success: response.success, data: response.data };
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.nativeCode === 'REQUEST_TIMEOUT') {
+                // Background tabs are throttled by the browser — bring the tab into focus
+                // so the page can load at full speed, then the user can retry.
+                this.fetchFn(`${this.baseUrl}/api/tabs/switch`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ tabId }),
+                    signal: AbortSignal.timeout(3000),
+                }).catch((focusErr) => {
+                    process.stderr.write(`[local] tab focus after navigate timeout failed: ${focusErr}\n`);
+                });
+                err.suggestion = `Loading ${url} is taking a long time — the tab may be throttled because it was in the background. Bringing it into focus now. Retry the command once the page has loaded.`;
+            }
+            throw err;
+        }
+    }
+    async goBack() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/go-back`, { method: 'POST' });
+        if (response.success)
+            this.syncAction(tabId, 'go-back', {});
+        return { success: response.success, data: response.data };
+    }
+    async goForward() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/go-forward`, { method: 'POST' });
+        if (response.success)
+            this.syncAction(tabId, 'go-forward', {});
+        return { success: response.success, data: response.data };
+    }
+    // --- Fingerprint + obstacle helpers ─────────────────────────────────────
+    /** Evaluate function suitable for captureFingerprint / classifyElementFailure. */
+    evaluateForFingerprint = (script) => this.evaluate(script).then((r) => unwrapEvaluatePayload(r.data));
+    /** Capture fingerprint with a 3s timeout to avoid blocking the primary action. */
+    async tryCaptureFP() {
+        let timerId;
+        try {
+            const timeoutPromise = new Promise(r => { timerId = setTimeout(() => r(null), 3000); });
+            return await Promise.race([
+                captureFingerprint(this.evaluateForFingerprint),
+                timeoutPromise,
+            ]);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timerId)
+                clearTimeout(timerId);
+        }
+    }
+    /** A fingerprint with empty url means capture failed — skip comparison. */
+    static isFingerprintValid(fp) {
+        return fp.url !== '';
+    }
+    /**
+     * Enrich an ELEMENT_NOT_FOUND ApiError with obstacle classification.
+     * Runs classifyElementFailure to determine WHY the selector failed,
+     * then attaches the result as `obstacleType` on the error object.
+     * If classification itself fails, returns the original error unchanged.
+     */
+    async enrichElementNotFound(err, selector) {
+        try {
+            const obstacleType = await classifyElementFailure(selector, this.evaluateForFingerprint);
+            err.obstacleType = obstacleType;
+        }
+        catch {
+            // Classification failed — return original error unchanged
+        }
+        return err;
+    }
+    // --- Interaction ---
+    async click(selector, options = {}) {
+        const tabId = await this.getActiveTabId();
+        // Capture pre-action fingerprint (best-effort)
+        const pre = await this.tryCaptureFP();
+        let response;
+        try {
+            response = await this.request(`/sessions/${tabId}/click`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    selector,
+                    button: options.button ?? 'left',
+                    clickCount: options.count ?? 1,
+                    delay: options.delay,
+                    timeout: options.timeout ?? 15000,
+                }),
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'ELEMENT_NOT_FOUND') {
+                throw await this.enrichElementNotFound(err, selector);
+            }
+            throw err;
+        }
+        // Bridge blocked hint takes precedence — it is more specific
+        const blocked = classifyFromBridgeResult(response.data);
+        if (blocked)
+            return { success: false, data: blocked };
+        // State fingerprint comparison (best-effort; skip if capture returned empty)
+        if (pre && LocalAdapter.isFingerprintValid(pre)) {
+            try {
+                if (POST_ACTION_SETTLE_MS > 0)
+                    await new Promise(resolve => setTimeout(resolve, POST_ACTION_SETTLE_MS));
+                const post = await this.tryCaptureFP();
+                if (!post)
+                    throw new Error('post fingerprint unavailable');
+                const comparison = compareFingerprints(pre, post);
+                if (comparison === 'unchanged') {
+                    const stateBlocked = classifyFromStateCheck('click', pre, post);
+                    if (stateBlocked)
+                        return { success: false, data: stateBlocked };
+                }
+            }
+            catch { /* fingerprint failure — do not break normal flow */ }
+        }
+        if (response.success)
+            this.syncAction(tabId, 'click', { selector });
+        return { success: response.success };
+    }
+    async type(selector, text, options = {}) {
+        const tabId = await this.getActiveTabId();
+        const pre = await this.tryCaptureFP();
+        let response;
+        try {
+            response = await this.request(`/sessions/${tabId}/type`, {
+                method: 'POST',
+                body: JSON.stringify({ selector, text, delay: options.delay }),
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'ELEMENT_NOT_FOUND') {
+                throw await this.enrichElementNotFound(err, selector);
+            }
+            throw err;
+        }
+        const blocked = classifyFromBridgeResult(response.data);
+        if (blocked)
+            return { success: false, data: blocked };
+        if (pre && LocalAdapter.isFingerprintValid(pre)) {
+            try {
+                if (POST_ACTION_SETTLE_MS > 0)
+                    await new Promise(resolve => setTimeout(resolve, POST_ACTION_SETTLE_MS));
+                const post = await this.tryCaptureFP();
+                if (!post)
+                    throw new Error('post fingerprint unavailable');
+                const comparison = compareFingerprints(pre, post);
+                if (comparison === 'unchanged') {
+                    const stateBlocked = classifyFromStateCheck('type', pre, post);
+                    if (stateBlocked)
+                        return { success: false, data: stateBlocked };
+                }
+            }
+            catch { /* fingerprint failure — do not break normal flow */ }
+        }
+        if (response.success)
+            this.syncAction(tabId, 'type', { selector });
+        return { success: response.success };
+    }
+    async fill(selector, value) {
+        const tabId = await this.getActiveTabId();
+        const pre = await this.tryCaptureFP();
+        let response;
+        try {
+            response = await this.request(`/sessions/${tabId}/fill`, {
+                method: 'POST',
+                body: JSON.stringify({ selector, value }),
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'ELEMENT_NOT_FOUND') {
+                throw await this.enrichElementNotFound(err, selector);
+            }
+            throw err;
+        }
+        const blocked = classifyFromBridgeResult(response.data);
+        if (blocked)
+            return { success: false, data: blocked };
+        if (pre && LocalAdapter.isFingerprintValid(pre)) {
+            try {
+                if (POST_ACTION_SETTLE_MS > 0)
+                    await new Promise(resolve => setTimeout(resolve, POST_ACTION_SETTLE_MS));
+                const post = await this.tryCaptureFP();
+                if (!post)
+                    throw new Error('post fingerprint unavailable');
+                const comparison = compareFingerprints(pre, post);
+                if (comparison === 'unchanged') {
+                    const stateBlocked = classifyFromStateCheck('fill', pre, post);
+                    if (stateBlocked)
+                        return { success: false, data: stateBlocked };
+                }
+            }
+            catch { /* fingerprint failure — do not break normal flow */ }
+        }
+        if (response.success)
+            this.syncAction(tabId, 'fill', { selector });
+        return { success: response.success };
+    }
+    async press(key) {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/press`, {
+            method: 'POST',
+            body: JSON.stringify({ key }),
+        });
+        if (response.success)
+            this.syncAction(tabId, 'press', { key });
+        return { success: response.success };
+    }
+    async scroll(options) {
+        const tabId = await this.getActiveTabId();
+        // Selector-based: scroll element into view via evaluate, but sync as 'scroll'
+        // (not 'evaluate') so the activity feed shows the user-facing action type.
+        if (options.selector) {
+            const resp = await this.request(`/sessions/${tabId}/evaluate`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    script: `document.querySelector(${JSON.stringify(options.selector)})?.scrollIntoView({behavior:'smooth',block:'center'})`,
+                    args: [],
+                }),
+            });
+            if (resp.success)
+                this.syncAction(tabId, 'scroll', { selector: options.selector });
+            return { success: resp.success, data: resp.data };
+        }
+        // Horizontal scroll is not supported by the native host's handleScroll (which only
+        // accepts {direction: 'up'|'down', amount}). Throw rather than silently scrolling
+        // vertically when the caller explicitly requests horizontal scrolling.
+        if (options.x !== undefined && options.y === undefined) {
+            throw new ApiError('Horizontal scrolling (x-only) is not supported in local mode', 400, 'Use --down or --up for vertical scrolling, or --to <selector> to scroll an element into view', 'UNSUPPORTED_OPERATION', false);
+        }
+        // Translate y offset → {direction, amount} as expected by native host handleScroll
+        const direction = (options.y !== undefined && options.y < 0) ? 'up' : 'down';
+        const amount = options.y !== undefined ? Math.abs(options.y) : 500;
+        const response = await this.request(`/sessions/${tabId}/scroll`, {
+            method: 'POST',
+            body: JSON.stringify({ direction, amount }),
+        });
+        if (response.success)
+            this.syncAction(tabId, 'scroll', { direction, amount });
+        return { success: response.success };
+    }
+    async hover(selector) {
+        const tabId = await this.getActiveTabId();
+        try {
+            const response = await this.request(`/sessions/${tabId}/hover`, {
+                method: 'POST',
+                body: JSON.stringify({ selector }),
+            });
+            if (response.success)
+                this.syncAction(tabId, 'hover', { selector });
+            return { success: response.success };
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'ELEMENT_NOT_FOUND') {
+                throw await this.enrichElementNotFound(err, selector);
+            }
+            throw err;
+        }
+    }
+    async select(selector, value) {
+        const tabId = await this.getActiveTabId();
+        // Capture pre-action fingerprint (best-effort)
+        const pre = await this.tryCaptureFP();
+        let response;
+        try {
+            response = await this.request(`/sessions/${tabId}/select`, {
+                method: 'POST',
+                body: JSON.stringify({ selector, value }),
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'ELEMENT_NOT_FOUND') {
+                throw await this.enrichElementNotFound(err, selector);
+            }
+            throw err;
+        }
+        // Bridge blocked hint takes precedence — it is more specific
+        const blocked = classifyFromBridgeResult(response.data);
+        if (blocked)
+            return { success: false, data: blocked };
+        // State fingerprint comparison (best-effort; skip if capture returned empty)
+        if (pre && LocalAdapter.isFingerprintValid(pre)) {
+            try {
+                if (POST_ACTION_SETTLE_MS > 0)
+                    await new Promise(resolve => setTimeout(resolve, POST_ACTION_SETTLE_MS));
+                const post = await this.tryCaptureFP();
+                if (!post)
+                    throw new Error('post fingerprint unavailable');
+                const comparison = compareFingerprints(pre, post);
+                if (comparison === 'unchanged') {
+                    const stateBlocked = classifyFromStateCheck('select', pre, post);
+                    if (stateBlocked)
+                        return { success: false, data: stateBlocked };
+                }
+            }
+            catch { /* fingerprint failure — do not break normal flow */ }
+        }
+        if (response.success)
+            this.syncAction(tabId, 'select', { selector });
+        return { success: response.success };
+    }
+    // --- Waiting ---
+    async wait(condition, options = {}) {
+        if (typeof condition === 'number') {
+            // Numeric-timeout path: local setTimeout only — never contacts the bridge,
+            // so there is no bridge action to sync and syncAction is intentionally absent.
+            await new Promise(resolve => setTimeout(resolve, condition));
+            return { success: true };
+        }
+        const tabId = await this.getActiveTabId();
+        const state = options.hidden ? 'hidden' : 'visible';
+        const response = await this.request(`/sessions/${tabId}/wait`, {
+            method: 'POST',
+            body: JSON.stringify({
+                selector: condition,
+                state,
+                timeout: options.timeout ?? 30000,
+            }),
+        });
+        if (response.success)
+            this.syncAction(tabId, 'wait', {});
+        return { success: response.success };
+    }
+    async waitForText(text, options = {}) {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/wait-for-text`, {
+            method: 'POST',
+            body: JSON.stringify({ text, timeout: options.timeout ?? 30000 }),
+        });
+        return { success: response.success };
+    }
+    // --- Observation ---
+    async snapshot() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/snapshot`, { method: 'POST' });
+        // Native host may return snapshot in data.snapshot or data directly
+        const snapshot = response.data?.snapshot ?? response.data;
+        return { success: response.success, data: snapshot };
+    }
+    async screenshot(options = {}) {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/screenshot`, {
+            method: 'POST',
+            body: JSON.stringify({
+                fullPage: options.fullPage,
+                selector: options.selector,
+                type: options.format ?? 'png',
+                quality: options.quality,
+                maxDimension: options.maxDimension,
+            }),
+        });
+        // Native host returns base64 screenshot — try cloud upload first, fall back to temp file
+        const b64 = response.data?.screenshot ?? response.data;
+        if (b64 && typeof b64 === 'string') {
+            // Filename: human-readable timestamp prefix + UUID suffix.
+            // Timestamp makes recent screenshots easy to identify (ls -t); UUID prevents
+            // collisions from rapid successive calls within the same millisecond.
+            const ts = new Date().toISOString().replace(/[:.]/g, '-').replace('Z', '');
+            const tempPath = join(tmpdir(), `thinkrun-${ts}-${randomUUID().slice(0, 8)}.png`);
+            writeFileSync(tempPath, Buffer.from(b64, 'base64'));
+            // Derive MIME type once — used for both the artifact upload and the sync action.
+            const mimeType = options.format === 'jpeg' ? 'image/jpeg'
+                : options.format === 'webp' ? 'image/webp'
+                    : 'image/png';
+            // If this local tab has a registered cloud session (from startSession()), sync
+            // the screenshot as an action in the activity feed.  Fire-and-forget — never
+            // blocks the caller.
+            let syncTabId;
+            try {
+                syncTabId = getLocalSessionContext()?.tabId;
+            }
+            catch { /* mixed session state */ }
+            if (syncTabId) {
+                const persistedSessionId = readCliSessionId(syncTabId);
+                if (persistedSessionId) {
+                    const caption = options.caption?.trim();
+                    if (!caption) {
+                        throw new Error('Local screenshots synced to ThinkRun require --caption <text>');
+                    }
+                    syncScreenshotAction(persistedSessionId, b64, mimeType, caption, this.fetchFn);
+                }
+            }
+            // If API key is configured, upload to cloud artifact storage so the screenshot
+            // has a downloadable URL (same as cloud mode). Uses a client-generated UUID as
+            // the sessionId — the server allows authenticated uploads without a session doc.
+            const apiKey = config.get('apiKey');
+            if (apiKey) {
+                const rawApiUrl = config.get('apiUrl') || 'https://api.thinkbrowse.io';
+                try {
+                    let apiBase;
+                    try {
+                        apiBase = new URL(rawApiUrl);
+                    }
+                    catch {
+                        return { success: true, data: { path: tempPath, local: true } };
+                    }
+                    // Local HTTP apiUrls are valid for bridge/dev workflows, but skip
+                    // credentialed uploads to avoid sending the API key over plaintext.
+                    if (apiBase.protocol !== 'https:')
+                        return { success: true, data: { path: tempPath, local: true } };
+                    const apiUrl = apiBase.href.replace(/\/$/, '');
+                    const artifactSessionId = randomUUID();
+                    const uploadRes = await this.fetchFn(`${apiUrl}/api/sessions/${artifactSessionId}/artifact-upload`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
+                        body: JSON.stringify({ screenshot: b64, label: options.selector ?? 'local-screenshot', mimeType }),
+                        signal: AbortSignal.timeout(15000),
+                    });
+                    if (uploadRes.ok) {
+                        const data = (await uploadRes.json());
+                        const objectId = data?.objectId;
+                        if (!objectId) {
+                            throw new Error('Missing objectId in upload response');
+                        }
+                        const url = `${apiUrl}/api/storage/artifacts/${objectId}/download`;
+                        return { success: true, data: { url, objectId, path: tempPath, local: true } };
+                    }
+                }
+                catch (uploadErr) {
+                    // Cloud upload failed — fall through to temp-file-only result.
+                    // Log to stderr so users/agents can debug without it polluting stdout.
+                    process.stderr.write(`[thinkrun] Cloud upload failed: ${uploadErr?.message ?? uploadErr}\n`);
+                }
+            }
+            return { success: true, data: { path: tempPath, local: true } };
+        }
+        return { success: response.success, data: response.data };
+    }
+    async extract(selector, options = {}) {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/extract`, {
+            method: 'POST',
+            body: JSON.stringify({
+                selector,
+                type: options.attr ? 'attribute' : options.format ?? 'text',
+                attribute: options.attr,
+                multiple: options.all,
+            }),
+        });
+        if (response.success)
+            this.syncAction(tabId, 'extract', { selector: selector || 'page' });
+        return { success: response.success, data: response.data };
+    }
+    async evaluate(script, args = [], evalOpts) {
+        const tabId = await this.getActiveTabId();
+        const timeoutMs = evalOpts?.timeout ?? 30_000;
+        const response = await this.request(`/sessions/${tabId}/evaluate`, {
+            method: 'POST',
+            body: JSON.stringify({ script, args, timeout: timeoutMs }),
+            timeoutMs: Math.min(timeoutMs + 15_000, 615_000),
+        });
+        if (response.success)
+            this.syncAction(tabId, 'evaluate', {});
+        return { success: response.success, data: response.data };
+    }
+    async getUrl() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/url`, { method: 'POST' });
+        const url = typeof response.data === 'string' ? response.data : (response.data?.url ?? response.data);
+        return { success: response.success, data: url };
+    }
+    async getTitle() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/title`, { method: 'POST' });
+        const title = typeof response.data === 'string' ? response.data : (response.data?.title ?? response.data);
+        return { success: response.success, data: title };
+    }
+    async getHtml() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/html`, { method: 'POST' });
+        const html = typeof response.data === 'string' ? response.data : (response.data?.html ?? response.data);
+        return { success: response.success, data: html };
+    }
+    // --- Dialog Handling ---
+    async getDialog() {
+        const tabId = await this.getActiveTabId();
+        return this.request(`/sessions/${tabId}/dialog`);
+    }
+    async handleDialog(action, promptText) {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/dialog`, {
+            method: 'POST',
+            body: JSON.stringify({ accept: action === 'accept', promptText }),
+        });
+        return { success: response.success };
+    }
+    // --- Monitoring ---
+    async getConsoleMessages() {
+        const tabId = await this.getActiveTabId();
+        const result = await this.request(`/sessions/${tabId}/console`);
+        const logs = result.data?.logs ?? result.data ?? [];
+        return {
+            success: result.success,
+            logs: Array.isArray(logs) ? logs : [],
+            count: Array.isArray(logs) ? logs.length : 0,
+        };
+    }
+    async getNetworkRequests() {
+        const tabId = await this.getActiveTabId();
+        const result = await this.request(`/sessions/${tabId}/network`);
+        const requests = result.data?.requests ?? result.data ?? [];
+        return {
+            success: result.success,
+            requests: Array.isArray(requests) ? requests : [],
+            count: Array.isArray(requests) ? requests.length : 0,
+        };
+    }
+    async clearLogs() {
+        const tabId = await this.getActiveTabId();
+        const response = await this.request(`/sessions/${tabId}/clear-logs`, { method: 'POST' });
+        return { success: response.success };
+    }
+}
+//# sourceMappingURL=local.js.map