@thinkrun/mcp 0.3.5

package/dist/src/local-client.js

@@ -0,0 +1,947 @@
+/**
+ * Local client — communicates with the ThinkRun native messaging host.
+ * Chrome auto-launches the native host binary when the extension loads.
+ *
+ * Port discovery: the native host writes its HTTP port to ~/.thinkbrowse/port
+ * on startup. This client reads that file to find the port, falling back to
+ * DEFAULT_PORT (3012) if the file doesn't exist.
+ *
+ * Use LocalClient.create() for automatic detection (health check with timeout),
+ * or pass an explicit port via new LocalClient({ port }).
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { fetchPageCacheJson, PageCacheRequestError } from './page-cache-http.js';
+import { unwrapEvaluatePayload } from './unwrap-evaluate-payload.js';
+import { acquireTabLock, getLastReclaimAudit, getTabLock, isTabLockHeldByCurrentAgent, isTabLockStale, releaseTabLock, resolveAgentId, } from './local-locks.js';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Default port for the native messaging host. */
+export const DEFAULT_PORT = 3012;
+/** @deprecated Use DEFAULT_PORT instead. */
+export const DEFAULT_NATIVE_HOST_PORT = DEFAULT_PORT;
+/** @deprecated Bridge server has been removed. */
+export const DEFAULT_BRIDGE_PORT = DEFAULT_PORT;
+/** Port discovery file written by the native host on startup. */
+const PORT_DISCOVERY_FILE = join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.thinkbrowse', 'port');
+/**
+ * Read the native host port from the discovery file (~/.thinkbrowse/port).
+ * Returns null if the file doesn't exist or is invalid.
+ */
+function readDiscoveredPort() {
+    try {
+        if (existsSync(PORT_DISCOVERY_FILE)) {
+            const content = readFileSync(PORT_DISCOVERY_FILE, 'utf-8').trim();
+            const port = parseInt(content, 10);
+            if (!isNaN(port) && port > 0 && port <= 65535)
+                return port;
+        }
+    }
+    catch {
+        // File doesn't exist or unreadable — fall through
+    }
+    return null;
+}
+/**
+ * Resolve the native host port. Priority:
+ *   1. Explicit config (port or bridgePort)
+ *   2. Port discovery file (~/.thinkbrowse/port)
+ *   3. DEFAULT_PORT (3012)
+ */
+function resolvePort(config) {
+    const explicit = config.port ?? config.bridgePort;
+    if (explicit)
+        return explicit;
+    return readDiscoveredPort() ?? DEFAULT_PORT;
+}
+/**
+ * Check if the native host is reachable. Tries the discovery-file port first,
+ * then falls back to DEFAULT_PORT if the discovery port fails.
+ *
+ * @throws {LocalEndpointNotFoundError} when the native host is not reachable.
+ */
+async function detectLocalEndpoint(config) {
+    const timeoutMs = config.healthCheckTimeoutMs ?? 1000;
+    const explicit = config.port ?? config.bridgePort;
+    // Build list of ports to try (deduplicated)
+    const portsToTry = [];
+    if (explicit) {
+        portsToTry.push(explicit);
+    }
+    else {
+        const discovered = readDiscoveredPort();
+        if (discovered)
+            portsToTry.push(discovered);
+        if (!portsToTry.includes(DEFAULT_PORT))
+            portsToTry.push(DEFAULT_PORT);
+    }
+    for (const port of portsToTry) {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const resp = await fetch(`http://localhost:${port}/health`, { signal: controller.signal });
+            clearTimeout(timer);
+            if (resp.ok) {
+                return `http://localhost:${port}`;
+            }
+        }
+        catch {
+            // not reachable on this port
+        }
+    }
+    throw new LocalEndpointNotFoundError(portsToTry[0] ?? DEFAULT_PORT);
+}
+export class LocalClient {
+    baseUrl;
+    tabId = null;
+    /** Agent session ID from the extension's session registry. */
+    agentSessionId = null;
+    windowId = null;
+    /** mech-browser-service base URL for `/api/cache/*` only (native host does not serve these routes). */
+    serviceBaseUrl;
+    serviceApiKey;
+    constructor(config) {
+        if (config._resolvedBaseUrl) {
+            // Created via LocalClient.create() — baseUrl already resolved via health check
+            this.baseUrl = config._resolvedBaseUrl;
+        }
+        else {
+            // Direct instantiation: resolve port from config → discovery file → default.
+            // Intentionally silent (no throw) — falls back to the discovery file so that
+            // new LocalClient({}) "just works" when the native host is running.
+            // Use LocalClient.create() if you want a reachability check before connecting.
+            const port = resolvePort(config);
+            this.baseUrl = `http://localhost:${port}`;
+        }
+        this.serviceBaseUrl = config.serviceBaseUrl?.replace(/\/$/, '');
+        this.serviceApiKey = config.serviceApiKey;
+    }
+    /**
+     * Create a LocalClient after verifying the native host is reachable.
+     *
+     * @throws {LocalEndpointNotFoundError} when the native host is not reachable.
+     */
+    static async create(config = {}) {
+        const baseUrl = await detectLocalEndpoint(config);
+        return new LocalClient({
+            ...config,
+            _resolvedBaseUrl: baseUrl,
+        });
+    }
+    async request(method, path, body, opts) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {};
+        const tabId = opts && 'tabId' in opts ? opts.tabId : this.tabId;
+        const sessionId = opts && 'sessionId' in opts ? opts.sessionId : this.agentSessionId;
+        if (tabId) {
+            headers['x-tab-id'] = tabId;
+        }
+        if (sessionId) {
+            headers['x-session-id'] = sessionId;
+        }
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // not JSON
+            }
+            throw new BridgeError(parsed?.error || `HTTP ${response.status}: ${text}`, response.status, parsed?.code, parsed?.retryable);
+        }
+        return response.json();
+    }
+    async requestWithoutSessionHeaders(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = body ? { 'Content-Type': 'application/json' } : {};
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // not JSON
+            }
+            throw new BridgeError(parsed?.error || `HTTP ${response.status}: ${text}`, response.status, parsed?.code, parsed?.retryable);
+        }
+        return response.json();
+    }
+    async getBridgeHealth(timeoutMs = 2500) {
+        try {
+            const response = await fetch(`${this.baseUrl}/health`, {
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!response.ok) {
+                return { ok: false, message: `HTTP ${response.status}` };
+            }
+            const body = await response.json();
+            const inner = isObject(body.data) ? body.data : body;
+            const isEmptyObject = isObject(inner) && Object.keys(inner).length === 0;
+            const hasRecognizedShape = body.success === true
+                || body.status === 'ok'
+                || isEmptyObject
+                || typeof inner.service === 'string'
+                || typeof inner.extensionConnected === 'boolean'
+                || typeof inner.recoveryState === 'string';
+            if (!hasRecognizedShape) {
+                return { ok: false, message: 'Malformed /health response' };
+            }
+            const extensionConnected = typeof inner?.extensionConnected === 'boolean'
+                ? inner.extensionConnected
+                : typeof body.extensionConnected === 'boolean'
+                    ? body.extensionConnected
+                    : undefined;
+            const lastDisconnectReason = inner?.lastExtensionDisconnectReason ?? body.lastExtensionDisconnectReason;
+            const recoveryState = inner?.recoveryState ?? body.recoveryState;
+            const recentDisconnectCount = typeof inner?.recentDisconnectCount === 'number'
+                ? inner.recentDisconnectCount
+                : typeof body.recentDisconnectCount === 'number'
+                    ? body.recentDisconnectCount
+                    : undefined;
+            const lastRecoveredAt = inner?.lastRecoveredAt ?? body.lastRecoveredAt;
+            const service = typeof inner?.service === 'string'
+                ? inner.service
+                : typeof body.service === 'string'
+                    ? body.service
+                    : isEmptyObject
+                        ? 'health (empty response)'
+                        : body.status === 'ok'
+                            ? 'ok'
+                            : 'health';
+            const isCircuitBreakerTrip = typeof inner?.isCircuitBreakerTrip === 'boolean'
+                ? inner.isCircuitBreakerTrip
+                : typeof body.isCircuitBreakerTrip === 'boolean'
+                    ? body.isCircuitBreakerTrip
+                    : extensionConnected === false && typeof lastDisconnectReason === 'string'
+                        // Fallback to the current bridge wording until /health exposes a structured flag everywhere.
+                        ? lastDisconnectReason.startsWith('Circuit breaker:')
+                        : undefined;
+            let message = service;
+            if (typeof extensionConnected === 'boolean') {
+                message += ` (extensionConnected=${extensionConnected})`;
+            }
+            if (typeof recoveryState === 'string' && recoveryState !== 'healthy') {
+                message += `, recoveryState=${recoveryState}`;
+            }
+            if (typeof recentDisconnectCount === 'number' && recentDisconnectCount > 0) {
+                message += `, recentDisconnects=${recentDisconnectCount}`;
+            }
+            if (typeof lastRecoveredAt === 'string' && lastRecoveredAt.length > 0) {
+                message += `, lastRecoveredAt=${lastRecoveredAt}`;
+            }
+            if (typeof lastDisconnectReason === 'string' && lastDisconnectReason.length > 0 && extensionConnected === false) {
+                message += `, lastDisconnect=${lastDisconnectReason}`;
+            }
+            return {
+                ok: true,
+                ...(extensionConnected !== undefined ? { extensionConnected } : {}),
+                ...(typeof lastDisconnectReason === 'string' ? { lastDisconnectReason } : {}),
+                ...(typeof recoveryState === 'string' ? { recoveryState } : {}),
+                ...(typeof recentDisconnectCount === 'number' ? { recentDisconnectCount } : {}),
+                ...(typeof lastRecoveredAt === 'string' ? { lastRecoveredAt } : {}),
+                ...(typeof isCircuitBreakerTrip === 'boolean' ? { isCircuitBreakerTrip } : {}),
+                message,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: error instanceof Error ? error.message : 'unreachable',
+            };
+        }
+    }
+    buildSessionResult(tabId, extras) {
+        return {
+            sessionId: `local-${tabId}`,
+            status: 'active',
+            tabId,
+            ...(extras?.windowId !== undefined ? { windowId: extras.windowId } : {}),
+            ...(extras?.url !== undefined ? { url: extras.url } : {}),
+            ...(extras?.title !== undefined ? { title: extras.title } : {}),
+        };
+    }
+    async unregisterCurrentAgentSession() {
+        if (!this.agentSessionId)
+            return;
+        try {
+            await this.request('DELETE', '/sessions/unregister');
+        }
+        catch {
+            // best effort
+        }
+        finally {
+            this.agentSessionId = null;
+        }
+    }
+    async registerTabSession(tabId, sessionId) {
+        const result = await this.requestWithoutSessionHeaders('POST', '/sessions/register', sessionId ? { tabId, sessionId } : { tabId });
+        return {
+            sessionId: result.data?.sessionId,
+            windowId: result.data?.windowId,
+        };
+    }
+    // --- Session lifecycle ---
+    // In local mode, "sessions" map to browser tabs
+    async createSession(_options) {
+        // Pre-flight: check that the Chrome extension is connected before trying to
+        // open a tab. Without this, the error leaks as "X-Tab-Id header required"
+        // (an internal routing detail) rather than an actionable message.
+        // Uses === false so a missing field (future bridge compat) stays truthy.
+        // Note: request() has no explicit timeout beyond the OS default. If the
+        // bridge is hung this call can block for ~75-120s — acceptable given the
+        // alternative is waiting for a tab creation to hang instead.
+        // Note: TOCTOU — the extension can disconnect after the health check passes.
+        // The health check reduces but does not eliminate that race; the original
+        // error from /api/tabs/new would surface in that case.
+        const health = await this.request('GET', '/health');
+        if (health.extensionConnected === false) {
+            throw new Error('ThinkRun extension is not connected. Open a Chromium-based browser (e.g. Chrome or Helium) with the extension active, then try again.');
+        }
+        // Create a new tab via the native host.
+        // Uses /api/tabs/new — NOT /api/tabs (GET-only list endpoint).
+        // The bridge wraps all responses as { success: true, data: { ... } }.
+        const result = await this.request('POST', '/api/tabs/new');
+        const tab = result.data;
+        if (!tab)
+            throw new Error('Tab creation failed: bridge returned no data');
+        this.tabId = tab.tabId;
+        // Register an agent session so the extension tracks this tab
+        // and is immune to the user manually switching Chrome tabs.
+        try {
+            const numericTabId = Number(tab.tabId);
+            if (Number.isFinite(numericTabId) && numericTabId > 0) {
+                const regResult = await this.request('POST', '/sessions/register', { tabId: numericTabId });
+                if (regResult.data?.sessionId) {
+                    this.agentSessionId = regResult.data.sessionId;
+                }
+            }
+        }
+        catch {
+            // Session registry is optional — commands still work via _tabId
+        }
+        return this.buildSessionResult(Number(tab.tabId), { url: tab.url, title: tab.title });
+    }
+    async getSession(sessionId) {
+        const tabId = this.extractTabId(sessionId);
+        const result = await this.request('GET', `/api/tabs/${tabId}`);
+        return {
+            sessionId,
+            status: 'active',
+            url: result.url,
+            title: result.title,
+        };
+    }
+    async deleteSession(sessionId) {
+        const tabId = this.extractTabId(sessionId);
+        await this.request('DELETE', `/api/tabs/${tabId}`);
+        if (this.tabId === tabId) {
+            this.tabId = null;
+        }
+        // Clean up agent session registry — X-Session-Id header carries the UUID
+        if (this.agentSessionId) {
+            try {
+                await this.request('DELETE', '/sessions/unregister');
+            }
+            catch { /* best-effort */ }
+            this.agentSessionId = null;
+        }
+        return { success: true };
+    }
+    async listSessions() {
+        const result = await this.request('GET', '/api/tabs');
+        return (result.tabs || []).map(tab => ({
+            sessionId: `local-${tab.tabId}`,
+            status: 'active',
+            url: tab.url,
+            title: tab.title,
+        }));
+    }
+    async attachToTab(tabId) {
+        const previousTabId = this.tabId ? parseInt(this.tabId, 10) : undefined;
+        const previousSessionId = this.agentSessionId;
+        await this.switchToTab(tabId);
+        if (previousTabId === tabId && previousSessionId) {
+            // Idempotent re-attach refreshes extension-side session state only.
+            // We preserve the existing lock when we still hold it, but recreate it if it was removed.
+            const rebound = await this.registerTabSession(tabId, previousSessionId);
+            if (!isTabLockHeldByCurrentAgent(tabId)) {
+                acquireTabLock(tabId);
+            }
+            this.tabId = String(tabId);
+            this.agentSessionId = rebound.sessionId ?? previousSessionId;
+            this.windowId = rebound.windowId ?? this.windowId;
+            return this.buildSessionResult(tabId, this.windowId !== null ? { windowId: this.windowId } : undefined);
+        }
+        acquireTabLock(tabId);
+        try {
+            const rebound = await this.registerTabSession(tabId);
+            await this.unregisterCurrentAgentSession();
+            if (previousTabId !== undefined && previousTabId !== tabId) {
+                releaseTabLock(previousTabId);
+            }
+            this.tabId = String(tabId);
+            this.agentSessionId = rebound.sessionId ?? null;
+            this.windowId = rebound.windowId ?? null;
+            return this.buildSessionResult(tabId, this.windowId !== null ? { windowId: this.windowId } : undefined);
+        }
+        catch (err) {
+            releaseTabLock(tabId);
+            throw err;
+        }
+    }
+    async switchToTab(tabId) {
+        await this.request('POST', '/api/tabs/switch', { tabId }, {
+            tabId: String(tabId),
+            sessionId: this.tabId === String(tabId) ? this.agentSessionId : null,
+        });
+        return { success: true };
+    }
+    async openNewWindow(url = 'about:blank') {
+        const previousTabId = this.tabId ? parseInt(this.tabId, 10) : undefined;
+        const result = await this.requestWithoutSessionHeaders('POST', '/api/sessions/new-window', { url, focused: true });
+        const tabId = result.data?.tabId;
+        if (!tabId) {
+            throw new Error('Native host returned no tabId for new window');
+        }
+        acquireTabLock(tabId);
+        try {
+            const rebound = await this.registerTabSession(tabId);
+            await this.unregisterCurrentAgentSession();
+            if (previousTabId !== undefined && previousTabId !== tabId) {
+                releaseTabLock(previousTabId);
+            }
+            this.tabId = String(tabId);
+            this.agentSessionId = rebound.sessionId ?? null;
+            this.windowId = result.data?.windowId ?? null;
+            return this.buildSessionResult(tabId, {
+                windowId: result.data?.windowId,
+                url: result.data?.url,
+                title: result.data?.title,
+            });
+        }
+        catch (err) {
+            releaseTabLock(tabId);
+            throw err;
+        }
+    }
+    async releaseSession(sessionId) {
+        let tabId = this.tabId ? parseInt(this.tabId, 10) : NaN;
+        if (sessionId) {
+            tabId = parseInt(this.extractTabId(sessionId), 10);
+        }
+        if (!Number.isFinite(tabId) || tabId <= 0) {
+            if (!sessionId) {
+                return { success: true };
+            }
+            return {
+                success: false,
+                error: `Invalid local session ID: ${sessionId}`,
+                code: 'INVALID_SESSION_ID',
+                hint: 'Expected a local session ID like "local-42".',
+            };
+        }
+        await this.unregisterCurrentAgentSession();
+        releaseTabLock(tabId);
+        if (this.tabId === String(tabId)) {
+            this.tabId = null;
+            this.windowId = null;
+        }
+        return { success: true };
+    }
+    async listArtifacts(_sessionId) {
+        return { success: false, error: 'Artifacts listing is only available in cloud mode' };
+    }
+    // --- Navigation ---
+    async navigate(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/navigate', params);
+    }
+    async wait(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/wait', params);
+    }
+    // --- Interaction ---
+    async click(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/click', params);
+    }
+    async type(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/type', params);
+    }
+    async fill(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/fill', params);
+    }
+    async press(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/press', params);
+    }
+    async scroll(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/scroll', params);
+    }
+    async hover(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/hover', params);
+    }
+    async select(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/select', params);
+    }
+    // --- Observation ---
+    async snapshot(sessionId) {
+        this.ensureTab(sessionId);
+        // Native host returns { success, data: <snapshot> } — map to { success, snapshot }
+        const raw = await this.request('POST', '/api/snapshot');
+        const snapshot = typeof raw.data === 'string' ? raw.data
+            : raw.data != null ? JSON.stringify(raw.data, null, 2) : undefined;
+        return { success: raw.success, snapshot, error: raw.error };
+    }
+    async screenshot(sessionId, params) {
+        this.ensureTab(sessionId);
+        // Native host returns { success, data: { screenshot: "base64..." } } — map to { success, screenshot }
+        const raw = await this.request('POST', '/api/screenshot', params || {});
+        return { success: raw.success, screenshot: raw.data?.screenshot, error: raw.error };
+    }
+    async extract(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/extract', params);
+    }
+    async evaluate(sessionId, params) {
+        this.ensureTab(sessionId);
+        // Native host returns { success, data: <value> } but EvaluateResult expects { success, result }.
+        // Unwrap sole-key { result } wrappers to match CLI LocalAdapter / thinkrun evaluate.
+        const raw = await this.request('POST', '/api/evaluate', params);
+        return { success: raw.success, result: unwrapEvaluatePayload(raw.data), error: raw.error };
+    }
+    // --- Wait for text ---
+    async waitForText(sessionId, params) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/wait-for-text', params);
+    }
+    // --- Dialog handling ---
+    async getDialog(sessionId) {
+        this.ensureTab(sessionId);
+        const result = await this.request('POST', '/api/dialog');
+        return {
+            success: true,
+            hasDialog: false, // Local mode auto-handles dialogs via interception
+            dialog: null,
+            history: result.history || [],
+        };
+    }
+    async handleDialog(sessionId, params) {
+        // Local mode auto-handles dialogs — return history for visibility
+        this.ensureTab(sessionId);
+        const result = await this.request('POST', '/api/dialog');
+        return {
+            success: true,
+            data: result,
+        };
+    }
+    // --- Navigation history ---
+    async goBack(sessionId) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/go-back');
+    }
+    async goForward(sessionId) {
+        this.ensureTab(sessionId);
+        return this.request('POST', '/api/go-forward');
+    }
+    // --- Tab management ---
+    async listTabs(_sessionId) {
+        const result = await this.request('GET', '/api/tabs');
+        return {
+            success: true,
+            tabs: result.tabs || [],
+        };
+    }
+    async newTab(_sessionId, url) {
+        const result = await this.request('POST', '/api/tabs/new', url ? { url } : undefined);
+        return result.data;
+    }
+    async closeTab(sessionId, tabId) {
+        const id = tabId ?? parseInt(this.extractTabId(sessionId), 10);
+        await this.request('POST', '/api/tabs/close', { tabId: id }, {
+            tabId: String(id),
+            sessionId: this.tabId === String(id) ? this.agentSessionId : null,
+        });
+        return { success: true };
+    }
+    // --- Monitoring ---
+    async getConsoleMessages(sessionId) {
+        this.ensureTab(sessionId);
+        const result = await this.request('POST', '/api/console');
+        return {
+            success: true,
+            logs: result.logs || [],
+            count: result.count || (result.logs?.length ?? 0),
+        };
+    }
+    async getNetworkRequests(sessionId) {
+        this.ensureTab(sessionId);
+        const result = await this.request('POST', '/api/network');
+        return {
+            success: true,
+            requests: result.requests || [],
+            count: result.count || (result.requests?.length ?? 0),
+        };
+    }
+    async clearLogs(sessionId) {
+        this.ensureTab(sessionId);
+        const result = await this.request('POST', '/api/clear-logs');
+        return { success: result.success !== false };
+    }
+    // --- Task planning (not available in local mode) ---
+    async createTask(_params) {
+        return { success: false, error: 'Task planning is only available in cloud mode' };
+    }
+    async executeTask(_planId) {
+        return { success: false, error: 'Task execution is only available in cloud mode' };
+    }
+    async getTaskStatus(_planId) {
+        return { success: false, error: 'Task status is only available in cloud mode' };
+    }
+    async runLocalAction(params) {
+        const tabId = this.requireBoundLocalActionTabId();
+        const result = await this.requestWithoutSessionHeaders('POST', '/tasks', {
+            task: params.instruction,
+            tabId,
+            ...(params.maxIterations !== undefined ? { maxIterations: params.maxIterations } : {}),
+        });
+        return {
+            success: result.success !== false,
+            actionId: result.data?.taskId,
+            status: result.data?.status,
+            error: result.error,
+            code: result.code,
+        };
+    }
+    async getLocalActionStatus(actionId) {
+        const result = await this.requestWithoutSessionHeaders('GET', `/tasks/${encodeURIComponent(actionId)}/status`);
+        return {
+            success: result.success !== false,
+            actionId: result.data?.id,
+            status: result.data?.status,
+            instruction: result.data?.task,
+            startedAt: result.data?.startedAt,
+            completedAt: result.data?.completedAt,
+            result: result.data?.result,
+            error: result.data?.error ?? result.error,
+            iteration: result.data?.iteration,
+            maxIterations: result.data?.maxIterations,
+            code: result.code,
+        };
+    }
+    async cancelLocalAction(actionId) {
+        const result = await this.requestWithoutSessionHeaders('POST', `/tasks/${encodeURIComponent(actionId)}/cancel`, {});
+        return {
+            success: result.success !== false,
+            actionId: result.data?.taskId,
+            status: result.data?.status,
+            error: result.error,
+            code: result.code,
+        };
+    }
+    async getLocalDiagnostics(options) {
+        const boundTabId = this.tabId && /^\d+$/.test(this.tabId)
+            ? Number(this.tabId)
+            : null;
+        const effectiveTabId = boundTabId !== null ? String(boundTabId) : null;
+        const lockOwner = boundTabId !== null ? getTabLock(boundTabId) : null;
+        const staleLock = boundTabId !== null ? isTabLockStale(boundTabId) : false;
+        const currentAgentId = resolveAgentId();
+        const runtimeSessionPresent = typeof this.agentSessionId === 'string' && this.agentSessionId.length > 0;
+        const sameControllerLock = !!lockOwner?.agentId && lockOwner.agentId === currentAgentId;
+        const continuity = (() => {
+            if (boundTabId === null && !lockOwner) {
+                return {
+                    state: 'unbound',
+                    effectiveTabId: null,
+                    hint: 'No local tab is currently attached. Use tab_attach or window_new first.',
+                    runtimeSessionPresent: false,
+                    controlSessionPresent: false,
+                    controlLeaseHeld: false,
+                    staleLock: false,
+                    lockOwner: null,
+                };
+            }
+            if (lockOwner?.agentId && lockOwner.agentId !== currentAgentId) {
+                return {
+                    state: staleLock ? 'stale_reclaimable' : 'foreign_controller_live',
+                    effectiveTabId,
+                    hint: staleLock
+                        ? `Tab ${effectiveTabId} still has a stale foreign lock. Re-attach to reclaim it safely if the other controller is really gone.`
+                        : `Tab ${effectiveTabId} is actively controlled by another local agent.`,
+                    runtimeSessionPresent,
+                    controlSessionPresent: false,
+                    controlLeaseHeld: false,
+                    staleLock,
+                    lockOwner,
+                };
+            }
+            if (boundTabId !== null && runtimeSessionPresent) {
+                return {
+                    state: 'same_controller_read_resumable',
+                    effectiveTabId,
+                    hint: `Same-controller continuity is intact for tab ${effectiveTabId}.`,
+                    runtimeSessionPresent: true,
+                    controlSessionPresent: false,
+                    controlLeaseHeld: false,
+                    staleLock,
+                    lockOwner,
+                };
+            }
+            if (boundTabId !== null && sameControllerLock) {
+                return {
+                    state: 'same_controller_missing_runtime_registration',
+                    effectiveTabId,
+                    hint: `Same-controller continuity is proven for tab ${effectiveTabId}, but the runtime session registration is missing.`,
+                    runtimeSessionPresent: false,
+                    controlSessionPresent: false,
+                    controlLeaseHeld: false,
+                    staleLock,
+                    lockOwner,
+                };
+            }
+            return {
+                state: 'ambiguous_blocked',
+                effectiveTabId,
+                hint: effectiveTabId
+                    ? `Local continuity for tab ${effectiveTabId} could not be proven from the current MCP binding and lock state.`
+                    : 'Local continuity could not be proven from the current MCP binding state.',
+                runtimeSessionPresent,
+                controlSessionPresent: false,
+                controlLeaseHeld: false,
+                staleLock,
+                lockOwner,
+            };
+        })();
+        const bridge = await this.getBridgeHealth(options?.bridgeTimeoutMs);
+        const lastReclaimAudit = (() => {
+            const audit = getLastReclaimAudit();
+            if (!audit || boundTabId === null || audit.tabId !== boundTabId)
+                return null;
+            return audit;
+        })();
+        return {
+            success: true,
+            mode: 'local',
+            boundSession: boundTabId !== null
+                ? {
+                    sessionId: `local-${boundTabId}`,
+                    tabId: boundTabId,
+                    ...(this.agentSessionId ? { agentSessionId: this.agentSessionId } : {}),
+                    ...(this.windowId !== null ? { windowId: this.windowId } : {}),
+                }
+                : null,
+            continuity,
+            bridge: {
+                healthy: bridge.ok,
+                ...(bridge.extensionConnected !== undefined ? { extensionConnected: bridge.extensionConnected } : {}),
+                ...(bridge.recoveryState ? { recoveryState: bridge.recoveryState } : {}),
+                ...(bridge.recentDisconnectCount !== undefined ? { recentDisconnectCount: bridge.recentDisconnectCount } : {}),
+                ...(bridge.lastRecoveredAt ? { lastRecoveredAt: bridge.lastRecoveredAt } : {}),
+                ...(bridge.lastDisconnectReason ? { lastDisconnectReason: bridge.lastDisconnectReason } : {}),
+                ...(bridge.isCircuitBreakerTrip !== undefined ? { isCircuitBreakerTrip: bridge.isCircuitBreakerTrip } : {}),
+                message: bridge.message,
+            },
+            lastReclaimAudit,
+        };
+    }
+    async resetLocalConnection() {
+        const getString = (value) => typeof value === 'string' ? value : undefined;
+        const getBoolean = (value) => typeof value === 'boolean' ? value : undefined;
+        let response;
+        try {
+            response = await fetch(`${this.baseUrl}/reset-connection`, {
+                method: 'POST',
+                signal: AbortSignal.timeout(5000),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'fetch failed';
+            const errorCode = typeof error === 'object' && error !== null && 'code' in error
+                ? error.code
+                : undefined;
+            const causeCode = error instanceof Error
+                && typeof error.cause === 'object'
+                && error.cause !== null
+                && 'code' in error.cause
+                ? error.cause.code
+                : undefined;
+            const errorName = error instanceof Error ? error.name : undefined;
+            return {
+                success: false,
+                code: errorCode === 'ECONNREFUSED' || causeCode === 'ECONNREFUSED'
+                    ? 'NATIVE_HOST_UNREACHABLE'
+                    : errorName === 'TimeoutError'
+                        ? 'BRIDGE_TIMEOUT'
+                        : 'API_ERROR',
+                error: message,
+            };
+        }
+        let body = {};
+        let bodyParsed = false;
+        try {
+            const parsed = await response.json();
+            if (isObject(parsed)) {
+                body = parsed;
+                bodyParsed = true;
+            }
+        }
+        catch {
+            // non-JSON body falls through to status/error handling
+        }
+        if (response.status === 409) {
+            const data = isObject(body.data) ? body.data : null;
+            const lastDisconnectReason = getString(data?.lastDisconnectReason)
+                ?? getString(body.lastDisconnectReason)
+                ?? 'unknown';
+            return {
+                success: false,
+                code: 'TRANSPORT_DISCONNECTED',
+                error: lastDisconnectReason,
+                lastDisconnectReason,
+                hint: 'Reload the ThinkRun extension in your Chromium-based browser, then retry.',
+            };
+        }
+        if (!response.ok || body?.success === false) {
+            return {
+                success: false,
+                code: 'API_ERROR',
+                error: getString(body.error) ?? `HTTP ${response.status}`,
+            };
+        }
+        const data = isObject(body.data) ? body.data : null;
+        const wasConnected = getBoolean(data?.wasConnected);
+        const connected = getBoolean(data?.connected);
+        if (!bodyParsed || !data || typeof wasConnected !== 'boolean' || typeof connected !== 'boolean') {
+            const malformedSuccessMessage = 'Malformed success response: missing wasConnected/connected in data';
+            return {
+                success: false,
+                code: 'API_ERROR',
+                error: getString(body.error) ?? malformedSuccessMessage,
+            };
+        }
+        return {
+            success: true,
+            ok: true,
+            wasConnected,
+            connected,
+        };
+    }
+    // --- Stateless page cache (HTTP → mech-browser-service; not the native host) ---
+    resolvePageCacheAuth() {
+        const baseUrl = (this.serviceBaseUrl || process.env.THINKRUN_BASE_URL || '').replace(/\/$/, '');
+        const apiKey = this.serviceApiKey || process.env.THINKRUN_API_KEY || '';
+        if (!baseUrl || !apiKey)
+            return null;
+        return { baseUrl, apiKey };
+    }
+    pageCacheUnavailableError() {
+        return new Error('Page cache requires the ThinkRun API (native host has no /api/cache). ' +
+            'Set THINKRUN_API_KEY and THINKRUN_BASE_URL, or run thinkrun-mcp with --api-key and --base-url so LocalClient receives service credentials.');
+    }
+    pageCacheRetryable(status) {
+        return status === 429 || status >= 500;
+    }
+    async pageCacheHtml(params) {
+        const auth = this.resolvePageCacheAuth();
+        if (!auth)
+            throw this.pageCacheUnavailableError();
+        try {
+            return await fetchPageCacheJson(auth.baseUrl, auth.apiKey, '/api/cache/html', params);
+        }
+        catch (e) {
+            if (e instanceof PageCacheRequestError) {
+                throw new BridgeError(e.message, e.status, e.code, this.pageCacheRetryable(e.status));
+            }
+            throw e;
+        }
+    }
+    async pageCacheText(params) {
+        const auth = this.resolvePageCacheAuth();
+        if (!auth)
+            throw this.pageCacheUnavailableError();
+        try {
+            return await fetchPageCacheJson(auth.baseUrl, auth.apiKey, '/api/cache/text', params);
+        }
+        catch (e) {
+            if (e instanceof PageCacheRequestError) {
+                throw new BridgeError(e.message, e.status, e.code, this.pageCacheRetryable(e.status));
+            }
+            throw e;
+        }
+    }
+    async pageCacheScreenshot(params) {
+        const auth = this.resolvePageCacheAuth();
+        if (!auth)
+            throw this.pageCacheUnavailableError();
+        try {
+            return await fetchPageCacheJson(auth.baseUrl, auth.apiKey, '/api/cache/screenshot', params);
+        }
+        catch (e) {
+            if (e instanceof PageCacheRequestError) {
+                throw new BridgeError(e.message, e.status, e.code, this.pageCacheRetryable(e.status));
+            }
+            throw e;
+        }
+    }
+    // --- Helpers ---
+    extractTabId(sessionId) {
+        return sessionId.replace(/^local-/, '');
+    }
+    ensureTab(sessionId) {
+        const tabId = this.extractTabId(sessionId);
+        this.tabId = tabId;
+    }
+    requireBoundLocalActionTabId() {
+        const tabId = this.tabId ? parseInt(this.tabId, 10) : NaN;
+        if (!Number.isFinite(tabId) || tabId <= 0) {
+            throw new Error('No local tab is currently attached. Use tab_attach or window_new first.');
+        }
+        if (!isTabLockHeldByCurrentAgent(tabId)) {
+            throw new Error(`Current agent does not own local tab ${tabId}. Re-attach before running local_action_run.`);
+        }
+        return tabId;
+    }
+}
+export class BridgeError extends Error {
+    status;
+    code;
+    retryable;
+    constructor(message, status, code, retryable) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'BridgeError';
+    }
+}
+export class LocalEndpointNotFoundError extends Error {
+    constructor(port) {
+        super(`Native host not reachable on port ${port}. ` +
+            `Make sure a Chromium-based browser (e.g. Chrome or Helium) is open with the ThinkRun extension installed and the native host set up. ` +
+            `See: https://thinkbrowse.io/docs#local-mode`);
+        this.name = 'LocalEndpointNotFoundError';
+    }
+}
+//# sourceMappingURL=local-client.js.map