@deadragdoll/tellymcp 0.0.12 → 0.0.14

package/dist/services/features/telegram-mcp/src/features/browser/model/browserService.js

@@ -4,7 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BrowserService = void 0;
+const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
+const bodyLimits_1 = require("../../../shared/lib/bodyLimits");
+const localTimestamp_1 = require("../../../shared/lib/time/localTimestamp");
 const gatewayClientAccess_1 = require("../../distributed-client/model/gatewayClientAccess");
 function pushBounded(list, entry, max) {
     list.push(entry);
@@ -21,7 +24,7 @@ function trimList(list, limit) {
 function sanitizeScreenshotName(fileName) {
     const trimmed = fileName?.trim();
     if (!trimmed) {
-        const timestamp = new Date().toISOString().replace(/[:.]/gu, "-");
+        const timestamp = (0, localTimestamp_1.formatLocalTimestampForFileName)(new Date());
         return `browser-screenshot-${timestamp}.png`;
     }
     const parsed = node_path_1.default.parse(trimmed);
@@ -30,8 +33,8 @@ function sanitizeScreenshotName(fileName) {
     return `${base}${extension}`;
 }
 function buildDatedRelativePath(fileName, date = new Date()) {
-    const dateSegment = date.toISOString().slice(0, 10);
-    const timeSegment = date.toTimeString().slice(0, 8).replace(/:/gu, "-");
+    const dateSegment = (0, localTimestamp_1.formatLocalDateSegment)(date);
+    const timeSegment = (0, localTimestamp_1.formatLocalTimeSegment)(date);
     return `${dateSegment}/${timeSegment}/${fileName}`;
 }
 function isAbsoluteBrowserUrl(value) {
@@ -60,10 +63,11 @@ class BrowserService {
     logger;
     projectIdentityResolver;
     remoteConsoleInvoker;
+    firefoxAttachRegistry;
     playwrightModulePromise;
     browserPromise;
     sessionStates = new Map();
-    constructor(config, sessionStore, maintenanceStore, bindingStore, xchangeFileMetaStore, objectStore, telegramTransport, logger, projectIdentityResolver, remoteConsoleInvoker) {
+    constructor(config, sessionStore, maintenanceStore, bindingStore, xchangeFileMetaStore, objectStore, telegramTransport, logger, projectIdentityResolver, remoteConsoleInvoker, firefoxAttachRegistry) {
         this.config = config;
         this.sessionStore = sessionStore;
         this.maintenanceStore = maintenanceStore;
@@ -74,6 +78,304 @@ class BrowserService {
         this.logger = logger;
         this.projectIdentityResolver = projectIdentityResolver;
         this.remoteConsoleInvoker = remoteConsoleInvoker;
+        this.firefoxAttachRegistry = firefoxAttachRegistry;
+    }
+    async listAttachedInstances(input) {
+        const resolvedSessionId = await this.resolveOptionalSessionIdForRemote(input);
+        if (resolvedSessionId) {
+            const remote = await this.invokeRemote(resolvedSessionId, "telegramMcp.browser.listAttachedInstancesRemote", {
+                ...input,
+                session_id: resolvedSessionId,
+            });
+            if (remote) {
+                return remote;
+            }
+        }
+        const instances = this.listFirefoxAttachInstances();
+        return {
+            ...(resolvedSessionId ? { session_id: resolvedSessionId } : {}),
+            total: instances.length,
+            instances: instances.map((instance) => ({
+                instance_id: instance.instanceId,
+                browser: instance.browser,
+                extension_version: instance.extensionVersion,
+                ...(instance.profileName ? { profile_name: instance.profileName } : {}),
+                connected_at: instance.connectedAt,
+                last_seen_at: instance.lastSeenAt,
+                capabilities: [...instance.capabilities],
+                tab_count: instance.tabs.length,
+                ...(instance.activeTab
+                    ? {
+                        active_tab: {
+                            tab_id: instance.activeTab.tab_id,
+                            ...(typeof instance.activeTab.window_id === "number"
+                                ? { window_id: instance.activeTab.window_id }
+                                : {}),
+                            active: instance.activeTab.active,
+                            title: instance.activeTab.title,
+                            url: instance.activeTab.url,
+                            ...(instance.activeTab.status
+                                ? { status: instance.activeTab.status }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            })),
+        };
+    }
+    async listTabs(input) {
+        const resolvedSessionId = await this.resolveOptionalSessionIdForRemote(input);
+        if (resolvedSessionId) {
+            const remote = await this.invokeRemote(resolvedSessionId, "telegramMcp.browser.listTabsRemote", {
+                ...input,
+                session_id: resolvedSessionId,
+            });
+            if (remote) {
+                return remote;
+            }
+        }
+        const instances = this.listFirefoxAttachInstances();
+        const instance = input.instance_id?.trim()
+            ? instances.find((item) => item.instanceId === input.instance_id?.trim())
+            : instances.length === 1
+                ? instances[0]
+                : undefined;
+        if (!instance) {
+            if (input.instance_id?.trim()) {
+                throw new Error(`Attached browser instance '${input.instance_id.trim()}' was not found.`);
+            }
+            throw new Error("Attached browser instance is ambiguous. Pass instance_id or keep exactly one connected browser instance.");
+        }
+        const selectedAttachment = resolvedSessionId
+            ? await this.getAttachedBrowserAttachment(resolvedSessionId)
+            : null;
+        return {
+            ...(resolvedSessionId ? { session_id: resolvedSessionId } : {}),
+            instance_id: instance.instanceId,
+            total: instance.tabs.length,
+            tabs: instance.tabs.map((tab) => ({
+                tab_id: tab.tab_id,
+                ...(typeof tab.window_id === "number" ? { window_id: tab.window_id } : {}),
+                active: tab.active,
+                ...(selectedAttachment &&
+                    selectedAttachment.instanceId === instance.instanceId &&
+                    selectedAttachment.tabId === tab.tab_id
+                    ? { selected: true }
+                    : {}),
+                title: tab.title,
+                url: tab.url,
+                ...(tab.status ? { status: tab.status } : {}),
+            })),
+        };
+    }
+    async attachActiveTab(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.attachActiveTabRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        const instances = this.listFirefoxAttachInstances();
+        const instance = input.instance_id?.trim()
+            ? instances.find((item) => item.instanceId === input.instance_id?.trim())
+            : instances.length === 1
+                ? instances[0]
+                : undefined;
+        if (!instance) {
+            if (input.instance_id?.trim()) {
+                throw new Error(`Attached browser instance '${input.instance_id.trim()}' was not found.`);
+            }
+            throw new Error("Attached browser instance is ambiguous. Pass instance_id or keep exactly one connected browser instance.");
+        }
+        const activeTab = instance.activeTab;
+        if (!activeTab) {
+            throw new Error(`Attached browser instance '${instance.instanceId}' does not expose an active tab.`);
+        }
+        return await this.attachTab({
+            session_id: normalizedSessionId,
+            instance_id: instance.instanceId,
+            tab_id: activeTab.tab_id,
+        });
+    }
+    async attachTab(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.attachTabRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        if (!this.firefoxAttachRegistry) {
+            throw new Error("Attached browser backend is not available.");
+        }
+        const instances = this.listFirefoxAttachInstances();
+        const instance = input.instance_id?.trim()
+            ? instances.find((item) => item.instanceId === input.instance_id?.trim())
+            : instances.length === 1
+                ? instances[0]
+                : undefined;
+        if (!instance) {
+            if (input.instance_id?.trim()) {
+                throw new Error(`Attached browser instance '${input.instance_id.trim()}' was not found.`);
+            }
+            throw new Error("Attached browser instance is ambiguous. Pass instance_id or keep exactly one connected browser instance.");
+        }
+        const tab = instance.tabs.find((item) => item.tab_id === input.tab_id);
+        if (!tab) {
+            throw new Error(`Tab '${input.tab_id}' was not found in attached browser instance '${instance.instanceId}'.`);
+        }
+        const result = await this.firefoxAttachRegistry.invokeTabAction({
+            instanceId: instance.instanceId,
+            tabId: tab.tab_id,
+            action: "attach",
+        });
+        const attachedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
+        await this.maintenanceStore.setBrowserAttachment({
+            sessionId: normalizedSessionId,
+            backend: "firefox-attached",
+            instanceId: instance.instanceId,
+            tabId: tab.tab_id,
+            attachedAt,
+            ...(result?.title
+                ? { title: String(result.title) }
+                : tab.title
+                    ? { title: tab.title }
+                    : {}),
+            ...(result?.url
+                ? { url: String(result.url) }
+                : tab.url
+                    ? { url: tab.url }
+                    : {}),
+        });
+        return {
+            session_id: normalizedSessionId,
+            backend: "firefox-attached",
+            instance_id: instance.instanceId,
+            tab_id: tab.tab_id,
+            attached_at: attachedAt,
+            ...(result?.title
+                ? { title: String(result.title) }
+                : tab.title
+                    ? { title: tab.title }
+                    : {}),
+            ...(result?.url
+                ? { url: String(result.url) }
+                : tab.url
+                    ? { url: tab.url }
+                    : {}),
+        };
+    }
+    async detachTab(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.detachTabRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        const attachment = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attachment && this.firefoxAttachRegistry) {
+            try {
+                await this.firefoxAttachRegistry.invokeTabAction({
+                    instanceId: attachment.instanceId,
+                    tabId: attachment.tabId,
+                    action: "detach",
+                });
+            }
+            catch {
+                // Clearing local state is still the source of truth.
+            }
+        }
+        await this.maintenanceStore.clearBrowserAttachment(normalizedSessionId);
+        return {
+            session_id: normalizedSessionId,
+            detached: true,
+        };
+    }
+    async startRecording(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.startRecordingRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (!attached) {
+            throw new Error("No attached browser tab is selected for this session. Select a tab in the browser attach panel first.");
+        }
+        if (!this.firefoxAttachRegistry) {
+            throw new Error("Firefox attach backend is not available.");
+        }
+        const record = await this.firefoxAttachRegistry.startRecording({
+            sessionId: normalizedSessionId,
+            instanceId: input.instance_id?.trim() || attached.instanceId,
+            tabId: attached.tabId,
+            tabTitle: attached.title?.trim() || "attached-tab",
+            ...(attached.url ? { tabUrl: attached.url } : {}),
+        });
+        return this.mapRecordingRecord(normalizedSessionId, record);
+    }
+    async stopRecording(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.stopRecordingRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        if (!this.firefoxAttachRegistry) {
+            throw new Error("Firefox attach backend is not available.");
+        }
+        const record = await this.firefoxAttachRegistry.stopRecording({
+            sessionId: normalizedSessionId,
+        });
+        if (!record) {
+            return {
+                session_id: normalizedSessionId,
+                stopped: false,
+            };
+        }
+        return {
+            session_id: normalizedSessionId,
+            stopped: true,
+            recording_id: record.recordingId,
+            bundle_dir_name: record.bundleDirName,
+            bundle_relative_path: record.bundleRelativePath,
+            bundle_path: record.bundlePath,
+            ...(record.stoppedAt ? { stopped_at: record.stoppedAt } : {}),
+        };
+    }
+    async getRecordingStatus(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.getRecordingStatusRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        if (!this.firefoxAttachRegistry) {
+            throw new Error("Firefox attach backend is not available.");
+        }
+        const record = await this.firefoxAttachRegistry.getRecordingStatus(normalizedSessionId);
+        return {
+            session_id: normalizedSessionId,
+            active: record?.status === "recording",
+            ...(record ? { recording: this.mapRecordingStatusRecord(record) } : {}),
+        };
     }
     async open(input) {
         const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
@@ -115,7 +417,7 @@ class BrowserService {
         });
         state.currentUrl = state.page.url();
         state.title = await state.page.title();
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         this.logger.info("Browser page opened", {
             sessionId: resolved.sessionId,
             normalizedSessionId,
@@ -149,8 +451,40 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "get_logs",
+                payload: {
+                    limit: input.limit,
+                },
+            });
+            const consoleMessages = Array.isArray(result?.console_messages)
+                ? result.console_messages
+                : [];
+            return {
+                session_id: normalizedSessionId,
+                total: typeof result?.console_total === "number"
+                    ? result.console_total
+                    : consoleMessages.length,
+                messages: consoleMessages.map((message) => ({
+                    type: typeof message?.type === "string"
+                        ? message.type
+                        : "log",
+                    text: typeof message?.text === "string"
+                        ? message.text
+                        : "",
+                    ...(typeof message?.location === "string"
+                        ? { location: message.location }
+                        : {}),
+                    timestamp: typeof message?.timestamp === "string"
+                        ? message.timestamp
+                        : (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
+                })),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             total: state.consoleMessages.length,
@@ -173,6 +507,22 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "click",
+                payload: this.buildAttachedLocatorPayload(input),
+            });
+            return {
+                session_id: normalizedSessionId,
+                clicked: true,
+                ...(input.ai_tag ? { ai_tag: input.ai_tag } : {}),
+                ...(input.selector ? { selector: input.selector } : {}),
+                ...(input.text ? { text: input.text } : {}),
+                url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const locator = this.resolveLocator(state.page, input);
         await locator.click({
@@ -180,7 +530,7 @@ class BrowserService {
         });
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             clicked: true,
@@ -202,6 +552,26 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "fill",
+                payload: {
+                    ...this.buildAttachedLocatorPayload(input),
+                    value: input.value,
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                filled: true,
+                ...(input.ai_tag ? { ai_tag: input.ai_tag } : {}),
+                ...(input.selector ? { selector: input.selector } : {}),
+                ...(input.text ? { text: input.text } : {}),
+                value_length: input.value.length,
+                url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const locator = this.resolveLocator(state.page, input);
         await locator.fill(input.value, {
@@ -209,7 +579,7 @@ class BrowserService {
         });
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             filled: true,
@@ -232,6 +602,26 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "press",
+                payload: {
+                    ...this.buildAttachedLocatorPayload(input),
+                    key: input.key,
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                pressed: true,
+                key: input.key,
+                ...(input.ai_tag ? { ai_tag: input.ai_tag } : {}),
+                ...(input.selector ? { selector: input.selector } : {}),
+                ...(input.text ? { text: input.text } : {}),
+                url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         if (input.selector || input.text) {
             const locator = this.resolveLocator(state.page, input);
@@ -244,7 +634,7 @@ class BrowserService {
         }
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             pressed: true,
@@ -256,6 +646,72 @@ class BrowserService {
             ...(state.title ? { title: state.title } : {}),
         };
     }
+    async injectScript(input) {
+        const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
+        const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
+        const remote = await this.invokeRemote(normalizedSessionId, "telegramMcp.browser.injectScriptRemote", {
+            ...input,
+            session_id: normalizedSessionId,
+        });
+        if (remote) {
+            return remote;
+        }
+        this.ensureEnabled();
+        const namespace = input.namespace?.trim() || "TELLY";
+        const sourcePath = input.file_path?.trim()
+            ? node_path_1.default.resolve(input.file_path.trim())
+            : null;
+        if (!input.source?.trim().length && sourcePath) {
+            const sourceStats = await (0, promises_1.stat)(sourcePath);
+            (0, bodyLimits_1.assertBodySize)(sourceStats.size);
+        }
+        const source = input.source?.trim().length
+            ? input.source
+            : sourcePath
+                ? await (0, promises_1.readFile)(sourcePath, "utf8")
+                : null;
+        if (!source) {
+            throw new Error("Provide source or file_path.");
+        }
+        (0, bodyLimits_1.assertStringBodySize)(source);
+        const sourceType = input.source?.trim().length ? "inline" : "file";
+        const wrappedSource = this.wrapInjectedScript(source, namespace);
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "inject_script",
+                payload: {
+                    namespace,
+                    source,
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                injected: true,
+                namespace,
+                source_type: sourceType,
+                bytes: Buffer.byteLength(source, "utf8"),
+                url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
+        const { sessionId, state } = await this.requireSessionState(input);
+        await state.page.addScriptTag({
+            content: wrappedSource,
+        });
+        state.currentUrl = state.page.url();
+        state.title = await state.page.title().catch(() => state.title);
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
+        return {
+            session_id: sessionId,
+            injected: true,
+            namespace,
+            source_type: sourceType,
+            bytes: Buffer.byteLength(source, "utf8"),
+            url: state.currentUrl,
+            ...(state.title ? { title: state.title } : {}),
+        };
+    }
     async reload(input) {
         const resolved = this.projectIdentityResolver.resolveSessionDefaults(input);
         const normalizedSessionId = await this.normalizeSessionIdForAccess(resolved.sessionId);
@@ -267,6 +723,18 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "reload",
+            });
+            return {
+                session_id: normalizedSessionId,
+                reloaded: true,
+                url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const waitUntil = (input.wait_until ??
             this.config.browser.waitUntil);
@@ -276,7 +744,7 @@ class BrowserService {
         });
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         this.logger.info("Browser page reloaded", {
             sessionId,
             url: state.currentUrl,
@@ -301,6 +769,30 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const waitState = input.state ?? "visible";
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "wait_for",
+                payload: {
+                    ...this.buildAttachedLocatorPayload(input),
+                    state: waitState,
+                    ...(typeof input.timeout_ms === "number"
+                        ? { timeout_ms: input.timeout_ms }
+                        : {}),
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                waited: true,
+                state: waitState,
+                ...(input.ai_tag ? { ai_tag: input.ai_tag } : {}),
+                ...(input.selector ? { selector: input.selector } : {}),
+                ...(input.text ? { text: input.text } : {}),
+                url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const locator = this.resolveLocator(state.page, input);
         const waitState = input.state ?? "visible";
@@ -310,7 +802,7 @@ class BrowserService {
         });
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             waited: true,
@@ -333,6 +825,32 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "wait_for_url",
+                payload: {
+                    ...(input.url?.trim() ? { url: input.url.trim() } : {}),
+                    ...(input.url_contains?.trim()
+                        ? { url_contains: input.url_contains.trim() }
+                        : {}),
+                    ...(typeof input.timeout_ms === "number"
+                        ? { timeout_ms: input.timeout_ms }
+                        : {}),
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                waited: true,
+                matched: input.url?.trim() ? "url" : "url_contains",
+                ...(input.url?.trim() ? { url: input.url.trim() } : {}),
+                ...(input.url_contains?.trim()
+                    ? { url_contains: input.url_contains.trim() }
+                    : {}),
+                current_url: String(result?.url || attached.url || ""),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const timeout = this.resolveTimeoutMs(input.timeout_ms);
         if (input.url?.trim()) {
@@ -351,7 +869,7 @@ class BrowserService {
         }
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             waited: true,
@@ -375,8 +893,37 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "get_logs",
+                payload: {
+                    limit: input.limit,
+                },
+            });
+            const pageErrors = Array.isArray(result?.page_errors)
+                ? result.page_errors
+                : [];
+            return {
+                session_id: normalizedSessionId,
+                total: typeof result?.page_error_total === "number"
+                    ? result.page_error_total
+                    : pageErrors.length,
+                errors: pageErrors.map((error) => ({
+                    message: typeof error?.message === "string"
+                        ? error.message
+                        : "",
+                    ...(typeof error?.stack === "string"
+                        ? { stack: error.stack }
+                        : {}),
+                    timestamp: typeof error?.timestamp === "string"
+                        ? error.timestamp
+                        : (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
+                })),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             total: state.pageErrors.length,
@@ -398,8 +945,46 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "get_logs",
+                payload: {
+                    limit: input.limit,
+                },
+            });
+            const failures = Array.isArray(result?.network_failures)
+                ? result.network_failures
+                : [];
+            return {
+                session_id: normalizedSessionId,
+                total: typeof result?.network_failure_total === "number"
+                    ? result.network_failure_total
+                    : failures.length,
+                failures: failures.map((failure) => ({
+                    url: typeof failure?.url === "string"
+                        ? failure.url
+                        : "",
+                    method: typeof failure?.method === "string"
+                        ? failure.method
+                        : "GET",
+                    ...(typeof failure?.status === "number"
+                        ? { status: failure.status }
+                        : {}),
+                    ...(typeof failure?.error_text === "string"
+                        ? { error_text: failure.error_text }
+                        : {}),
+                    ...(typeof failure?.resource_type === "string"
+                        ? { resource_type: failure.resource_type }
+                        : {}),
+                    timestamp: typeof failure?.timestamp === "string"
+                        ? failure.timestamp
+                        : (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
+                })),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             total: state.networkFailures.length,
@@ -426,6 +1011,25 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "clear_logs",
+            });
+            return {
+                session_id: normalizedSessionId,
+                cleared: true,
+                console_messages_cleared: typeof result?.console_messages_cleared === "number"
+                    ? result.console_messages_cleared
+                    : 0,
+                page_errors_cleared: typeof result?.page_errors_cleared === "number"
+                    ? result.page_errors_cleared
+                    : 0,
+                network_failures_cleared: typeof result?.network_failures_cleared === "number"
+                    ? result.network_failures_cleared
+                    : 0,
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const consoleMessagesCleared = state.consoleMessages.length;
         const pageErrorsCleared = state.pageErrors.length;
@@ -433,7 +1037,7 @@ class BrowserService {
         state.consoleMessages = [];
         state.pageErrors = [];
         state.networkFailures = [];
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         return {
             session_id: sessionId,
             cleared: true,
@@ -453,6 +1057,37 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const selector = input.selector?.trim() || "body";
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "dom",
+                payload: {
+                    selector,
+                    include_html: input.include_html !== false,
+                    include_text: input.include_text !== false,
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                selector,
+                found: result?.found === true,
+                ...(result?.url ? { url: String(result.url) } : {}),
+                ...(result?.title ? { title: String(result.title) } : {}),
+                ...(typeof result?.outer_html === "string"
+                    ? { outer_html: result.outer_html }
+                    : {}),
+                ...(typeof result?.text_content === "string"
+                    ? { text_content: result.text_content }
+                    : {}),
+                ...(typeof result?.visible === "boolean"
+                    ? { visible: result.visible }
+                    : {}),
+                ...(result?.attributes && typeof result.attributes === "object"
+                    ? { attributes: result.attributes }
+                    : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const selector = input.selector?.trim() || "body";
         const snapshot = await state.page
@@ -487,7 +1122,7 @@ class BrowserService {
             includeText: input.include_text !== false,
         })
             .catch(() => ({ found: false }));
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
         return {
@@ -517,6 +1152,57 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const properties = input.properties?.length
+                ? input.properties
+                : [
+                    "display",
+                    "position",
+                    "visibility",
+                    "opacity",
+                    "color",
+                    "background-color",
+                    "font-size",
+                    "z-index",
+                    "overflow",
+                ];
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "computed_style",
+                payload: {
+                    selector: input.selector,
+                    properties,
+                },
+            });
+            return {
+                session_id: normalizedSessionId,
+                selector: input.selector,
+                found: result?.found === true,
+                ...(result?.url ? { url: String(result.url) } : {}),
+                ...(result?.title ? { title: String(result.title) } : {}),
+                ...(typeof result?.visible === "boolean"
+                    ? { visible: result.visible }
+                    : {}),
+                ...(result?.styles && typeof result.styles === "object"
+                    ? { styles: result.styles }
+                    : {}),
+                ...(result?.box &&
+                    typeof result.box === "object" &&
+                    typeof result.box.x === "number" &&
+                    typeof result.box.y === "number" &&
+                    typeof result.box.width === "number" &&
+                    typeof result.box.height === "number"
+                    ? {
+                        box: {
+                            x: Number(result.box.x),
+                            y: Number(result.box.y),
+                            width: Number(result.box.width),
+                            height: Number(result.box.height),
+                        },
+                    }
+                    : {}),
+            };
+        }
         const { sessionId, state } = await this.requireSessionState(input);
         const properties = input.properties?.length
             ? input.properties
@@ -556,7 +1242,7 @@ class BrowserService {
             };
         }, properties)
             .catch(() => ({ found: false }));
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
         return {
@@ -583,6 +1269,75 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            const session = await this.sessionStore.getSession(normalizedSessionId);
+            const fileName = sanitizeScreenshotName(input.file_name);
+            const result = await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "screenshot",
+            });
+            const pngBase64 = typeof result?.png_base64 === "string" ? result.png_base64 : "";
+            if (!pngBase64) {
+                throw new Error("Attached browser screenshot did not return PNG data.");
+            }
+            const pngBuffer = Buffer.from(pngBase64, "base64");
+            const workspaceDir = this.objectStore.resolveWorkspaceDir(session);
+            const exchangeDir = node_path_1.default.resolve(workspaceDir, this.config.exchange.dir);
+            const storedFile = await this.objectStore.storeFile({
+                session,
+                sessionId: normalizedSessionId,
+                source: "browser-screenshot",
+                relativePath: buildDatedRelativePath(fileName),
+                content: pngBuffer,
+                mimeType: "image/png",
+            });
+            await this.xchangeFileMetaStore.setXchangeFileMeta({
+                sessionId: normalizedSessionId,
+                filePath: storedFile.filePath,
+                relativePath: storedFile.relativePath,
+                source: "browser-screenshot",
+                uploadedAt: (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
+                storageRef: storedFile.storageRef,
+                bucketName: storedFile.bucketName,
+                objectName: storedFile.objectName,
+                vfsNodeId: storedFile.vfsNodeId,
+                vfsPublicUrl: storedFile.vfsPublicUrl,
+                vfsParentId: storedFile.vfsParentId,
+                mimeType: "image/png",
+                sizeBytes: storedFile.sizeBytes,
+                ...(input.caption ? { caption: input.caption } : {}),
+            });
+            let telegramMessageId;
+            if (input.send_to_telegram === true) {
+                if (this.config.distributed.mode === "client") {
+                    telegramMessageId = await this.sendScreenshotToGatewayTelegramRoute({
+                        sessionId: normalizedSessionId,
+                        fileName,
+                        pngBuffer,
+                        ...(input.caption ? { caption: input.caption } : {}),
+                    });
+                }
+                else {
+                    const binding = await this.bindingStore.getBinding(normalizedSessionId);
+                    if (!binding) {
+                        throw new Error("Session is not linked to Telegram, so screenshot cannot be sent there.");
+                    }
+                    const sent = await this.telegramTransport.sendDocumentToChat(binding.telegramChatId, storedFile.filePath, input.caption);
+                    telegramMessageId = sent.messageId;
+                }
+            }
+            return {
+                session_id: normalizedSessionId,
+                file_path: storedFile.filePath,
+                workspace_dir: workspaceDir,
+                exchange_dir: exchangeDir,
+                ...(typeof telegramMessageId === "number"
+                    ? { telegram_message_id: telegramMessageId }
+                    : {}),
+                ...(result?.url ? { url: String(result.url) } : {}),
+                ...(result?.title ? { title: String(result.title) } : {}),
+            };
+        }
         const { sessionId, state, session } = await this.requireSessionState(input);
         const fileName = sanitizeScreenshotName(input.file_name);
         const pngBuffer = input.selector?.trim()
@@ -609,7 +1364,7 @@ class BrowserService {
             mimeType: "image/png",
         });
         const filePath = storedFile.filePath;
-        state.lastUsedAt = new Date().toISOString();
+        state.lastUsedAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         state.currentUrl = state.page.url();
         state.title = await state.page.title().catch(() => state.title);
         this.logger.info("Browser screenshot captured", {
@@ -623,7 +1378,7 @@ class BrowserService {
             filePath,
             relativePath: storedFile.relativePath,
             source: "browser-screenshot",
-            uploadedAt: new Date().toISOString(),
+            uploadedAt: (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
             storageRef: storedFile.storageRef,
             bucketName: storedFile.bucketName,
             objectName: storedFile.objectName,
@@ -676,6 +1431,17 @@ class BrowserService {
             return remote;
         }
         this.ensureEnabled();
+        const attached = await this.getAttachedBrowserAttachment(normalizedSessionId);
+        if (attached) {
+            await this.runAttachedTabAction(normalizedSessionId, attached, {
+                action: "close",
+            });
+            await this.maintenanceStore.clearBrowserAttachment(normalizedSessionId);
+            return {
+                session_id: normalizedSessionId,
+                closed: true,
+            };
+        }
         const state = this.sessionStates.get(normalizedSessionId);
         if (state) {
             await this.closeState(normalizedSessionId, state);
@@ -749,7 +1515,7 @@ class BrowserService {
         const browser = await this.ensureBrowser();
         const context = await browser.newContext(this.buildContextOptions(openInput));
         const page = await context.newPage();
-        const createdAt = new Date().toISOString();
+        const createdAt = (0, localTimestamp_1.formatLocalTimestamp)(new Date());
         const state = {
             context,
             page,
@@ -766,14 +1532,14 @@ class BrowserService {
                 ...(formatConsoleLocation(message)
                     ? { location: formatConsoleLocation(message) }
                     : {}),
-                timestamp: new Date().toISOString(),
+                timestamp: (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
             }, this.config.browser.maxEvents);
         });
         page.on("pageerror", (error) => {
             pushBounded(state.pageErrors, {
                 message: error.message,
                 ...(error.stack ? { stack: error.stack } : {}),
-                timestamp: new Date().toISOString(),
+                timestamp: (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
             }, this.config.browser.maxEvents);
         });
         page.on("requestfailed", (request) => {
@@ -823,7 +1589,7 @@ class BrowserService {
                 : {}),
             ...(failure?.errorText ? { errorText: failure.errorText } : {}),
             resourceType: request.resourceType(),
-            timestamp: new Date().toISOString(),
+            timestamp: (0, localTimestamp_1.formatLocalTimestamp)(new Date()),
         }, this.config.browser.maxEvents);
     }
     async requireSessionState(input) {
@@ -875,6 +1641,107 @@ class BrowserService {
         const localSession = await this.sessionStore.getSession(localSessionId);
         return localSession ? localSessionId : trimmed;
     }
+    async resolveOptionalSessionIdForRemote(input) {
+        const trimmed = input.session_id?.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        return await this.normalizeSessionIdForAccess(trimmed);
+    }
+    listFirefoxAttachInstances() {
+        if (!this.firefoxAttachRegistry) {
+            return [];
+        }
+        return this.firefoxAttachRegistry.listInstances();
+    }
+    buildAttachedLocatorPayload(input) {
+        return {
+            ...(input.ai_tag?.trim() ? { ai_tag: input.ai_tag.trim() } : {}),
+            ...(input.selector?.trim() ? { selector: input.selector.trim() } : {}),
+            ...(input.text?.trim() ? { text: input.text.trim() } : {}),
+            ...(typeof input.exact === "boolean" ? { exact: input.exact } : {}),
+        };
+    }
+    async getAttachedBrowserAttachment(sessionId) {
+        return await this.maintenanceStore.getBrowserAttachment(sessionId);
+    }
+    mapRecordingRecord(sessionId, record) {
+        return {
+            session_id: sessionId,
+            started: true,
+            backend: "firefox-attached",
+            recording_id: record.recordingId,
+            instance_id: record.instanceId,
+            tab_id: record.tabId,
+            ...(record.tabTitle ? { tab_title: record.tabTitle } : {}),
+            ...(record.tabUrl ? { tab_url: record.tabUrl } : {}),
+            bundle_dir_name: record.bundleDirName,
+            bundle_relative_path: record.bundleRelativePath,
+            bundle_path: record.bundlePath,
+            started_at: record.startedAt,
+        };
+    }
+    mapRecordingStatusRecord(record) {
+        return {
+            backend: "firefox-attached",
+            recording_id: record.recordingId,
+            instance_id: record.instanceId,
+            tab_id: record.tabId,
+            ...(record.tabTitle ? { tab_title: record.tabTitle } : {}),
+            ...(record.tabUrl ? { tab_url: record.tabUrl } : {}),
+            bundle_dir_name: record.bundleDirName,
+            bundle_relative_path: record.bundleRelativePath,
+            bundle_path: record.bundlePath,
+            started_at: record.startedAt,
+            ...(record.stoppedAt ? { stopped_at: record.stoppedAt } : {}),
+            status: record.status,
+            event_count: record.eventCount,
+            ...(record.lastEventAt ? { last_event_at: record.lastEventAt } : {}),
+        };
+    }
+    async runAttachedTabAction(sessionId, attachment, input) {
+        if (!this.firefoxAttachRegistry) {
+            throw new Error("Attached browser backend is not available.");
+        }
+        const result = await this.firefoxAttachRegistry.invokeTabAction({
+            instanceId: attachment.instanceId,
+            tabId: attachment.tabId,
+            action: input.action,
+            payload: input.payload,
+        });
+        await this.maintenanceStore.setBrowserAttachment({
+            ...attachment,
+            ...(result?.title ? { title: String(result.title) } : {}),
+            ...(result?.url ? { url: String(result.url) } : {}),
+        });
+        this.logger.info("Attached browser tab action executed", {
+            sessionId,
+            instanceId: attachment.instanceId,
+            tabId: attachment.tabId,
+            action: input.action,
+        });
+        return result;
+    }
+    wrapInjectedScript(source, namespace) {
+        return `const __tellyNamespace = ${JSON.stringify(namespace)};
+window[__tellyNamespace] = window[__tellyNamespace] || {};
+var TELLY = window[__tellyNamespace];
+const __tellyBeforeKeys = new Set(Object.getOwnPropertyNames(window));
+${source}
+for (const __tellyKey of Object.getOwnPropertyNames(window)) {
+  if (__tellyBeforeKeys.has(__tellyKey)) {
+    continue;
+  }
+  if (__tellyKey === __tellyNamespace) {
+    continue;
+  }
+  try {
+    window[__tellyNamespace][__tellyKey] = window[__tellyKey];
+  } catch {
+    // ignore unassignable globals
+  }
+}`;
+    }
     async sendScreenshotToGatewayTelegramRoute(input) {
         if (!this.config.distributed.gatewayPublicUrl) {
             throw new Error("send_to_telegram on client nodes requires GATEWAY_PUBLIC_URL.");