@deadragdoll/tellymcp 0.0.11 → 0.0.13

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

@@ -4,6 +4,7 @@ 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 gatewayClientAccess_1 = require("../../distributed-client/model/gatewayClientAccess");
 function pushBounded(list, entry, max) {
@@ -47,6 +48,8 @@ function formatConsoleLocation(message) {
 function escapeCssAttributeValue(value) {
     return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
 }
+const DEFAULT_BROWSER_VIEWPORT_WIDTH = 1720;
+const DEFAULT_BROWSER_VIEWPORT_HEIGHT = 980;
 class BrowserService {
     config;
     sessionStore;
@@ -58,10 +61,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;
@@ -72,6 +76,173 @@ 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 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 Firefox tab is selected for this session. Select a tab in the extension popup 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);
@@ -85,12 +256,26 @@ class BrowserService {
         }
         this.ensureEnabled();
         const existingState = this.sessionStates.get(normalizedSessionId);
-        const shouldReset = input.reset_context === true;
+        const requestedViewport = this.resolveRequestedViewport(input);
+        const shouldUpgradeLegacyViewport = this.config.browser.headless === false &&
+            input.reset_context !== true &&
+            !requestedViewport &&
+            Boolean(existingState?.page.viewportSize());
+        const shouldReset = input.reset_context === true || shouldUpgradeLegacyViewport;
         const targetUrl = this.resolveBrowserUrl(input.url);
         if (shouldReset && existingState) {
             await this.closeState(normalizedSessionId, existingState);
         }
-        const { state, createdContext } = await this.ensureSessionState(normalizedSessionId, shouldReset);
+        const { state, createdContext } = await this.ensureSessionState(normalizedSessionId, shouldReset, input);
+        if (requestedViewport) {
+            await state.page.setViewportSize(requestedViewport);
+        }
+        else if (this.config.browser.headless !== false) {
+            await state.page.setViewportSize({
+                width: DEFAULT_BROWSER_VIEWPORT_WIDTH,
+                height: DEFAULT_BROWSER_VIEWPORT_HEIGHT,
+            });
+        }
         const waitUntil = (input.wait_until ??
             this.config.browser.waitUntil);
         await state.page.goto(targetUrl, {
@@ -108,13 +293,18 @@ class BrowserService {
             createdContext,
             waitUntil,
             headless: this.config.browser.headless,
+            viewportWidth: state.page.viewportSize()?.width ?? requestedViewport?.width,
+            viewportHeight: state.page.viewportSize()?.height ?? requestedViewport?.height,
         });
+        const viewport = state.page.viewportSize();
         return {
             session_id: normalizedSessionId,
             opened: true,
             created_context: createdContext,
             url: state.currentUrl,
             ...(state.title ? { title: state.title } : {}),
+            ...(viewport?.width ? { viewport_width: viewport.width } : {}),
+            ...(viewport?.height ? { viewport_height: viewport.height } : {}),
         };
     }
     async getConsole(input) {
@@ -152,6 +342,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({
@@ -181,6 +387,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, {
@@ -211,6 +437,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);
@@ -235,6 +481,64 @@ 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 source = input.source?.trim().length
+            ? input.source
+            : input.file_path?.trim()
+                ? await (0, promises_1.readFile)(node_path_1.default.resolve(input.file_path.trim()), "utf8")
+                : null;
+        if (!source) {
+            throw new Error("Provide source or file_path.");
+        }
+        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 = new Date().toISOString();
+        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);
@@ -432,6 +736,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
@@ -562,6 +897,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: new Date().toISOString(),
+                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()
@@ -690,10 +1094,13 @@ class BrowserService {
     async ensureBrowser() {
         this.browserPromise ??= (async () => {
             const playwright = await this.ensurePlaywright();
-            const launchArgs = this.config.browser.headless === false &&
-                this.config.browser.devtools === true
-                ? ["--auto-open-devtools-for-tabs"]
-                : [];
+            const launchArgs = [];
+            if (this.config.browser.headless === false) {
+                launchArgs.push("--start-maximized");
+                if (this.config.browser.devtools === true) {
+                    launchArgs.push("--auto-open-devtools-for-tabs");
+                }
+            }
             const browser = await playwright.chromium.launch({
                 headless: this.config.browser.headless,
                 slowMo: this.config.browser.slowMoMs,
@@ -717,13 +1124,13 @@ class BrowserService {
         })();
         return this.browserPromise;
     }
-    async ensureSessionState(sessionId, forceNewContext) {
+    async ensureSessionState(sessionId, forceNewContext, openInput) {
         const existing = this.sessionStates.get(sessionId);
         if (existing && !forceNewContext) {
             return { state: existing, createdContext: false };
         }
         const browser = await this.ensureBrowser();
-        const context = await browser.newContext();
+        const context = await browser.newContext(this.buildContextOptions(openInput));
         const page = await context.newPage();
         const createdAt = new Date().toISOString();
         const state = {
@@ -763,6 +1170,32 @@ class BrowserService {
         this.sessionStates.set(sessionId, state);
         return { state, createdContext: true };
     }
+    resolveRequestedViewport(input) {
+        const width = input?.width;
+        const height = input?.height;
+        if (!width && !height) {
+            return null;
+        }
+        if (!width || !height) {
+            throw new Error("Browser viewport requires both width and height together.");
+        }
+        return { width, height };
+    }
+    buildContextOptions(input) {
+        const requestedViewport = this.resolveRequestedViewport(input);
+        if (requestedViewport) {
+            return {
+                viewport: requestedViewport,
+                screen: requestedViewport,
+            };
+        }
+        if (this.config.browser.headless === false) {
+            return {
+                viewport: null,
+            };
+        }
+        return {};
+    }
     recordNetworkFailure(state, request, response) {
         const failure = request.failure();
         pushBounded(state.networkFailures, {
@@ -825,6 +1258,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.");