@deadragdoll/tellymcp 0.0.11 → 0.0.13

package/README-ru.md

@@ -29,6 +29,9 @@
 - позволяет одной консоли агента ставить задачу другой консоли
 - хранит structured xchange records в `.mcp-xchange`
 - поддерживает browser automation через Playwright
+- умеет attach к уже открытому Firefox или Chrome через bundled local extensions
+- умеет писать structured browser bundles в `.mcp-xchange/web/...` с HTML, network и console артефактами
+- умеет инжектить helper scripts в attached tabs или Playwright pages через `browser_inject_script`
 - отдаёт Telegram Mini App / Live View с gateway
 - поддерживает polling и webhook на gateway
 - поставляет встроенный Codex plugin со skills под типовые workflow
@@ -76,9 +79,13 @@ Gateway
 - `browser_open`
 - `browser_click`
 - `browser_fill`
+- `browser_inject_script`
 - `browser_press`
 - `browser_wait_for`
 - `browser_screenshot`
+- `browser_recording_start`
+- `browser_recording_stop`
+- `browser_recording_status`
 
 Синхронизация инструкций:
 
@@ -105,6 +112,18 @@ npm install -g @deadragdoll/tellymcp
 tellymcp browser install
 ```
 
+Если нужны attach extensions для существующего Firefox/Chrome:
+
+```bash
+tellymcp extension firefox
+tellymcp extension chrome
+```
+
+Команда выгружает готовые unpacked bundles в текущий каталог:
+
+- `./tellymcp-firefox-attach`
+- `./tellymcp-chrome-attach`
+
 Если используешь Codex:
 
 ```bash
@@ -272,6 +291,35 @@ tellymcp browser install
 
 Не подменяй browser workflow ad hoc shell-командами с Playwright, кроме случаев, когда ты отлаживаешь сам browser runtime.
 
+## Terminal Blockers
+
+Gateway prompt scanner теперь живёт от live-client lifecycle:
+
+- на старте gateway scanner только armed, но не крутится вхолостую
+- реальная работа начинается после подключения live client
+- relay console materialization идёт из `hello` и owner-route hydration, а не из `/menu`
+- детект работает по хвосту захваченного terminal buffer
+
+Основная эвристика blocker-а:
+
+- подряд идущие numbered choices: `1.`, `2.`, `3.`
+- рядом есть action hints вроде `press`, `input`, `choose`, `enter`, `esc`, `yes`, `no`
+- в Telegram notice попадают и 1-2 строки контекста выше menu block
+
+Когда blocker найден, gateway может отправить inline-кнопки:
+
+- `1..N`
+- `Enter`
+- `Esc`
+
+Эти кнопки отправляют в консоль ровно цифру или terminal action. Навигация маркером не используется.
+
+Операционные заметки:
+
+- одинаковый blocker fingerprint не перевысылается повторно
+- relay capture miss для offline agent считается debug-only шумом
+- `Storage` и `Screenshots` на gateway теперь relay-aware и читают metadata через gateway routes, а не через filesystem самого gateway
+
 ## Collaboration
 
 Проекты:

package/README.md

@@ -29,6 +29,9 @@ The current model is gateway-first:
 - lets one agent ask another agent to do work and return files or notes
 - stores structured xchange records in `.mcp-xchange`
 - supports browser automation with Playwright
+- can attach to an already running Firefox or Chrome tab through bundled local extensions
+- records browser sessions into structured `.mcp-xchange/web/...` bundles with HTML, network and console artifacts
+- can inject helper scripts into attached tabs or Playwright pages through `browser_inject_script`
 - serves the Telegram Mini App / Live View from the gateway
 - supports Telegram polling or webhook mode on the gateway
 - ships a bundled Codex workflow plugin for better agent behavior
@@ -76,9 +79,13 @@ Browser:
 - `browser_open`
 - `browser_click`
 - `browser_fill`
+- `browser_inject_script`
 - `browser_press`
 - `browser_wait_for`
 - `browser_screenshot`
+- `browser_recording_start`
+- `browser_recording_stop`
+- `browser_recording_status`
 
 Tools sync:
 
@@ -105,6 +112,18 @@ Optional browser runtime:
 tellymcp browser install
 ```
 
+Optional attached-browser extensions:
+
+```bash
+tellymcp extension firefox
+tellymcp extension chrome
+```
+
+This exports unpacked extension bundles into the current directory:
+
+- `./tellymcp-firefox-attach`
+- `./tellymcp-chrome-attach`
+
 Optional Codex workflow plugin:
 
 ```bash
@@ -272,6 +291,34 @@ tellymcp browser install
 
 Do not replace browser workflows with ad hoc shell Playwright commands unless you are debugging the runtime itself.
 
+## Terminal Blockers
+
+Gateway prompt scanning is now live-client driven:
+
+- the scanner is armed on gateway startup but starts working only after a live client connects
+- relay console materialization happens from gateway hello/owner-route hydration, not from `/menu`
+- prompt detection works on the tail of the captured terminal buffer
+
+Primary blocker heuristic:
+
+- contiguous numbered choices like `1.`, `2.`, `3.`
+- nearby action hints such as `press`, `input`, `choose`, `enter`, `esc`, `yes`, `no`
+- optional context lines above the menu block are included in the Telegram notice
+
+When a blocker is detected, the gateway can send inline Telegram buttons for:
+
+- `1..N`
+- `Enter`
+- `Esc`
+
+Those buttons send exactly the digit or terminal action to the target console. No marker navigation is used.
+
+Operational notes:
+
+- repeated scans of the same blocker fingerprint do not resend the notice
+- relay capture misses for offline agents are treated as debug-only noise
+- `Storage` and `Screenshots` on the gateway are relay-aware and read console metadata through gateway routes instead of the gateway filesystem
+
 ## Collaboration Model
 
 Projects:

package/TOOLS.md

@@ -1,6 +1,6 @@
 # Tools
 
-Version: `2026-05-22.1`
+Version: `2026-06-06.1`
 
 Gateway/client runtime compatibility:
 
@@ -16,10 +16,16 @@ This MCP server currently exposes the following tools.
 
 Browser tools:
 
+- `browser_list_attached_instances`
+- `browser_list_tabs`
+- `browser_recording_start`
+- `browser_recording_stop`
+- `browser_recording_status`
 - `browser_open`
 - `browser_reload`
 - `browser_click`
 - `browser_fill`
+- `browser_inject_script`
 - `browser_press`
 - `browser_wait_for`
 - `browser_wait_for_url`
@@ -34,10 +40,35 @@ Browser tools:
 
 Browser runtime rule:
 
-- Browser tools use Playwright Chromium.
+- Browser tools now have two backends:
+  - attached browser tab backend for a real user Firefox or Chrome session
+  - isolated Playwright Chromium backend
+- `browser_open` is only for the isolated Playwright backend.
+- `browser_list_attached_instances` and `browser_list_tabs` are for the attached browser backend.
+- if the local attach extension is connected and a tab was selected from the browser control panel, `browser_click`, `browser_fill`, `browser_inject_script`, `browser_press`, `browser_dom`, and `browser_screenshot` use that attached browser tab for the current session without requiring `browser_open`
+- `browser_recording_start`, `browser_recording_stop`, and `browser_recording_status` are also for the attached browser backend
+- browser recordings are written under `.mcp-xchange/web/{tab-title-slug}-{timestamp}/`
+- each recording bundle contains `session.json`, `timeline.ndjson`, `pages/`, `network/`, and `console/`
+- inside `network/`, use `index.ndjson` as the thin search index and `requests/{seq}-{request_id}/` as the per-request artifact bundle
+- otherwise those tools use the Playwright backend after `browser_open`
 - If browser tools fail because the Playwright browser runtime is missing, install it with `tellymcp browser install`.
 - Do not stop at the installation error itself. Install the browser runtime first, then retry the browser tool.
 
+Terminal prompt scan rules:
+
+- gateway prompt scan is driven by live client lifecycle, not by manual menu entry
+- the scanner works on the tail of the captured terminal buffer
+- the main blocker signal is:
+  - a contiguous numbered choice block like `1.`, `2.`, `3.`
+  - nearby action-hint language such as `press`, `input`, `choose`, `enter`, `esc`, `yes`, `no`
+- exact footer text is helpful but not required
+- when a blocker notice contains inline buttons, those buttons intentionally send only:
+  - a digit `1..N`
+  - `Enter`
+  - `Esc`
+- do not assume marker navigation
+- do not reinterpret those buttons as alternate hotkeys like `(y)` or `(p)`
+
 Collaboration tools:
 
 - `list_gateway_sessions`
@@ -725,6 +756,8 @@ Input:
 
 - `session_id?`
 - `url`
+- `width?`
+- `height?`
 - `wait_until?`
 - `reset_context?`
 
@@ -735,12 +768,162 @@ Output:
 - `created_context`
 - `url`
 - `title?`
+- `viewport_width?`
+- `viewport_height?`
 
 Notes:
 
 - each session gets its own isolated browser context and page
-- call this first before reading console, DOM, styles, or screenshots
+- call this first only when you want the isolated Playwright backend
+- do not call this just to work with an already selected Firefox attached tab
 - `url` may be an absolute URL, or a relative path when `BROWSER_ADDRESS` is configured
+- in headed mode the browser window is started maximized by default
+- in headed mode a fresh browser context is created without a fixed viewport unless you explicitly pass `width` and `height`
+- if you want page content to grow and shrink together with the outer browser window, do not pass `width` and `height`
+- if you pass viewport size, pass both `width` and `height` together
+- use explicit `width` and `height` when the task depends on a specific responsive breakpoint or working area
+
+## `browser_list_attached_instances`
+
+Purpose:
+
+- list browser instances currently connected through the local attach extension bridge
+
+Input:
+
+- `session_id?`
+
+Output:
+
+- `session_id?`
+- `total`
+- `instances[]`
+  - `instance_id`
+  - `browser`
+  - `extension_version`
+  - `profile_name?`
+  - `connected_at`
+  - `last_seen_at`
+  - `capabilities[]`
+  - `tab_count`
+  - `active_tab?`
+
+## `browser_list_tabs`
+
+Purpose:
+
+- list tabs from an attached browser instance
+
+Input:
+
+- `session_id?`
+- `instance_id?`
+
+Output:
+
+- `session_id?`
+- `instance_id`
+- `total`
+- `tabs[]`
+  - `tab_id`
+  - `window_id?`
+  - `active`
+  - `selected?`
+  - `title`
+  - `url`
+  - `status?`
+
+Notes:
+
+- if only one attached browser instance is connected, `instance_id` can be omitted
+- current tab selection for the attach backend is done from the browser extension control panel
+- `active=true` means the tab is active in its browser window; there may be more than one such tab across multiple windows
+- for the tab currently selected for this MCP session, prefer `selected=true`
+
+## `browser_recording_start`
+
+Purpose:
+
+- start a structured browser recording bundle for the attached browser tab currently selected for this MCP session
+
+Input:
+
+- `session_id?`
+- `instance_id?`
+
+Output:
+
+- `session_id`
+- `backend`
+- `started`
+- `recording_id`
+- `instance_id`
+- `tab_id`
+- `tab_title?`
+- `tab_url?`
+- `bundle_dir_name`
+- `bundle_relative_path`
+- `bundle_path`
+- `started_at`
+
+Notes:
+
+- this works only with the attached browser backend, not Playwright
+- select the target tab first from the browser extension control panel
+- the bundle is created under `.mcp-xchange/web/{tab-title-slug}-{timestamp}/`
+- the recording captures page snapshots, console events, request metadata, headers, cookies snapshots, and available request/response bodies
+- for network analysis, read `network/index.ndjson` first, then open the matching `network/requests/{seq}-{request_id}/meta.json`
+- use `request.json`, `response.json`, and optional body files only when deeper detail is needed
+
+## `browser_recording_stop`
+
+Purpose:
+
+- stop the active structured browser recording for this MCP session
+
+Input:
+
+- `session_id?`
+
+Output:
+
+- `session_id`
+- `stopped`
+- `recording_id?`
+- `bundle_dir_name?`
+- `bundle_relative_path?`
+- `bundle_path?`
+- `stopped_at?`
+
+## `browser_recording_status`
+
+Purpose:
+
+- inspect whether a structured browser recording is active and where its bundle is being written
+
+Input:
+
+- `session_id?`
+
+Output:
+
+- `session_id`
+- `active`
+- `recording?`
+  - `backend`
+  - `recording_id`
+  - `instance_id`
+  - `tab_id`
+  - `tab_title?`
+  - `tab_url?`
+  - `bundle_dir_name`
+  - `bundle_relative_path`
+  - `bundle_path`
+  - `started_at`
+  - `stopped_at?`
+  - `status`
+  - `event_count`
+  - `last_event_at?`
 
 ## `browser_console`
 
@@ -782,6 +965,8 @@ Output:
 Purpose:
 
 - click an element in the current session page
+- if the session has a selected attached browser tab, click there
+- otherwise click in the isolated Playwright page
 
 Input:
 
@@ -807,6 +992,8 @@ Output:
 Purpose:
 
 - fill an input or textarea in the current session page
+- if the session has a selected attached browser tab, fill there
+- otherwise fill in the isolated Playwright page
 
 Input:
 
@@ -834,6 +1021,8 @@ Output:
 Purpose:
 
 - send a key press to the page or a targeted element
+- if the session has a selected attached browser tab, press there
+- otherwise press in the isolated Playwright page
 
 Input:
 
@@ -856,6 +1045,38 @@ Output:
 - `url`
 - `title?`
 
+## `browser_inject_script`
+
+Purpose:
+
+- inject JavaScript into the current session browser target
+- if the session has a selected attached browser tab, inject into that real browser tab
+- otherwise inject into the isolated Playwright page
+- the script is wrapped so `window[namespace]` exists; default namespace is `TELLY`
+
+Input:
+
+- `session_id?`
+- `source?`
+- `file_path?`
+- `namespace?`
+
+Rules:
+
+- provide either `source` or `file_path`
+- prefer `file_path` for local reusable scripts and larger payloads
+- injected scripts can use both `window.TELLY` and local `TELLY` when `namespace` is left at the default
+
+Output:
+
+- `session_id`
+- `injected`
+- `namespace`
+- `source_type`
+- `bytes`
+- `url`
+- `title?`
+
 ## `browser_wait_for`
 
 Purpose:
@@ -897,6 +1118,7 @@ Browser target rules for `browser_click`, `browser_fill`, `browser_press`, `brow
   - `div[data-testid="save"]`
 - use `text` only when there is no reliable selector
 - do not mix ambiguous hashed CSS classes with fuzzy text guessing when a stable selector exists
+- for the attached browser backend, prefer `selector` first; `ai_tag` and `text` still work, but the attach executor is intentionally lighter than full Playwright
 
 ## `browser_wait_for_url`
 
@@ -978,6 +1200,8 @@ Output:
 Purpose:
 
 - inspect a DOM element in the session browser tab
+- if the session has a selected attached browser tab, inspect that real browser tab
+- otherwise inspect the isolated Playwright page
 
 Input:
 
@@ -1026,6 +1250,8 @@ Output:
 Purpose:
 
 - capture a screenshot from the session browser tab
+- if the session has a selected attached browser tab, capture from that real browser tab
+- otherwise capture from the isolated Playwright page
 
 Input:
 
@@ -1052,6 +1278,7 @@ Notes:
 - they are tracked separately from Telegram-uploaded files
 - they appear under Telegram `Browser -> Screenshots`
 - if `send_to_telegram=true`, the saved screenshot is also sent into the bound Telegram chat for that session
+- for the attached browser backend, the screenshot comes from the selected tab in the user browser session
 
 ## `browser_close`
 
@@ -1083,6 +1310,8 @@ Telegram UI summary:
 - default logical console identity comes from `.mcpsession.json` in the workspace or explicit `-s`
 - terminal runtime metadata does not change `session_id`
 - `Browser -> Screenshots` lists screenshots created by `browser_screenshot`
+- `Storage` and `Screenshots` are relay-aware on the gateway
+- for relay consoles they read file metadata through gateway routes, not through the gateway filesystem
 - `Storage` browses `.mcp-xchange` for the active console and can send stored notes/files back into Telegram
 - `Settings` contains `Info`, `Rename`, `Unpair`, `Back`
 - project/collab work is the only supported user-facing collaboration path in Telegram UI

package/VERSION.md

@@ -100,8 +100,8 @@ For detailed engineering history, refactors, and internal development notes, see
   - `tellymcp doctor`
   - `tellymcp mcp --help`
 - Standalone and public installation guides:
-  - [STANDALONE.md](STANDALONE.md)
-  - [STANDALONE-ru.md](STANDALONE-ru.md)
+  - [STANDALONE.md](docs/STANDALONE.md)
+  - [STANDALONE-ru.md](docs/STANDALONE-ru.md)
 - Browser runtime helper:
   - `tellymcp browser install`
 - Public README set for GitHub and npm:

package/dist/cli.js

@@ -72,6 +72,8 @@ function printHelp() {
         "  tellymcp doctor [--env <file>]",
         "  tellymcp system-prune [--env <file>] --yes",
         "  tellymcp browser install",
+        "  tellymcp extension firefox",
+        "  tellymcp extension chrome",
         "  tellymcp codex-plugin install",
         "  tellymcp codex-plugin status",
         "  tellymcp mcp [--url <url>] [--bearer <token>] [--format claude|legacy]",
@@ -87,6 +89,8 @@ function printHelp() {
         "  tellymcp doctor --env .env.client",
         "  tellymcp system-prune --env .env.gateway --yes",
         "  tellymcp browser install",
+        "  tellymcp extension firefox",
+        "  tellymcp extension chrome ./tellymcp-chrome-attach",
         "  tellymcp codex-plugin install",
         "  tellymcp codex-plugin status",
         "  tellymcp mcp --help",
@@ -245,6 +249,27 @@ function printBrowserHelp() {
         "  Avoids generic npx warnings about missing local project dependencies.",
     ]);
 }
+function printExtensionHelp() {
+    printBanner("extension helper", "Export bundled browser attach extensions into a local directory");
+    printSection("Usage", [
+        "  tellymcp extension firefox [output-directory]",
+        "  tellymcp extension ff [output-directory]",
+        "  tellymcp extension chrome [output-directory]",
+        "  tellymcp extension <firefox|ff|chrome> --out-dir <directory>",
+        "  tellymcp extension <firefox|ff|chrome> --force",
+    ]);
+    printSection("What this command does", [
+        "  Copies the packaged unpacked extension bundle out of the installed tellymcp package.",
+        "  By default exports into the current directory.",
+        "  Creates a browser-specific folder you can load into Firefox or Chrome.",
+    ]);
+    printSection("Examples", [
+        "  tellymcp extension firefox",
+        "  tellymcp extension chrome",
+        "  tellymcp extension firefox ./tellymcp-firefox-attach",
+        "  tellymcp extension chrome --out-dir ./browser-addon",
+    ]);
+}
 function printCodexPluginHelp() {
     printBanner("codex plugin", "Install or inspect the bundled Codex workflow plugin");
     printSection("Usage", [
@@ -684,6 +709,39 @@ async function runDoctor(args) {
 function hasFlag(args, flagName) {
     return args.includes(flagName);
 }
+function normalizeExtensionFlavor(rawValue) {
+    if (rawValue === "firefox" || rawValue === "ff") {
+        return "firefox";
+    }
+    if (rawValue === "chrome") {
+        return "chrome";
+    }
+    return null;
+}
+function getBundledExtensionDir(flavor) {
+    return node_path_1.default.join(packageRoot, "packages", flavor === "firefox" ? "firefox-attach-extension" : "chrome-attach-extension", "dist");
+}
+function getDefaultExtensionTargetDir(flavor) {
+    return node_path_1.default.resolve(process.cwd(), flavor === "firefox" ? "tellymcp-firefox-attach" : "tellymcp-chrome-attach");
+}
+function resolveExtensionTargetDir(args, flavor) {
+    const explicitOutDir = readFlagValue(args, "--out-dir");
+    if (explicitOutDir) {
+        return node_path_1.default.resolve(process.cwd(), explicitOutDir);
+    }
+    const positionalOutDir = args.find((value, index) => {
+        if (index === 0 || !value) {
+            return false;
+        }
+        if (value === "--force") {
+            return false;
+        }
+        return !value.startsWith("--out-dir=");
+    });
+    return positionalOutDir
+        ? node_path_1.default.resolve(process.cwd(), positionalOutDir)
+        : getDefaultExtensionTargetDir(flavor);
+}
 async function runSystemPrune(args) {
     const confirmed = hasFlag(args, "--yes");
     if (!confirmed) {
@@ -821,6 +879,52 @@ function runBrowserCommand(args) {
         process.exit(code ?? 0);
     });
 }
+function runExtensionCommand(args) {
+    const [rawFlavor] = args;
+    if (!rawFlavor || rawFlavor === "--help" || rawFlavor === "-h") {
+        printExtensionHelp();
+        return;
+    }
+    const flavor = normalizeExtensionFlavor(rawFlavor);
+    if (!flavor) {
+        fail("Supported extension targets: firefox, ff, chrome");
+    }
+    const sourceDir = getBundledExtensionDir(flavor);
+    const sourceManifestPath = node_path_1.default.join(sourceDir, "manifest.json");
+    if (!(0, node_fs_1.existsSync)(sourceManifestPath)) {
+        fail(`Missing bundled ${flavor} extension. Reinstall or republish tellymcp with packaged extension bundles.`);
+    }
+    const targetDir = resolveExtensionTargetDir(args, flavor);
+    const force = hasFlag(args, "--force");
+    if ((0, node_fs_1.existsSync)(targetDir)) {
+        if (!force) {
+            fail(`Refusing to overwrite existing directory: ${targetDir}. Re-run with --force.`);
+        }
+        (0, node_fs_1.rmSync)(targetDir, { recursive: true, force: true });
+    }
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(targetDir), { recursive: true });
+    (0, node_fs_1.cpSync)(sourceDir, targetDir, { recursive: true });
+    printBanner(`extension ${flavor}`, "Bundled attach extension exported");
+    printSection("result", [
+        `  source: ${sourceDir}`,
+        `  target: ${targetDir}`,
+        `  manifest: ${node_path_1.default.join(targetDir, "manifest.json")}`,
+    ]);
+    if (flavor === "firefox") {
+        printSection("next", [
+            "  1. Open about:debugging#/runtime/this-firefox",
+            "  2. Click 'Load Temporary Add-on'",
+            `  3. Choose ${node_path_1.default.join(targetDir, "manifest.json")}`,
+        ]);
+        return;
+    }
+    printSection("next", [
+        "  1. Open chrome://extensions",
+        "  2. Enable Developer mode",
+        "  3. Click 'Load unpacked'",
+        `  4. Choose ${targetDir}`,
+    ]);
+}
 function runCodexPluginCommand(args) {
     const [subcommand] = args;
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
@@ -942,7 +1046,7 @@ async function runRuntime(args) {
 async function main(argv) {
     const [rawCommand, firstArg, secondArg] = argv;
     const command = rawCommand === "init" || rawCommand === "run" || rawCommand === "help" || rawCommand === "mcp" || rawCommand === "doctor" || rawCommand === "browser" || rawCommand === "system-prune"
-        || rawCommand === "codex-plugin"
+        || rawCommand === "codex-plugin" || rawCommand === "extension"
         ? rawCommand
         : "help";
     if (command === "help" || !rawCommand || rawCommand === "--help" || rawCommand === "-h") {
@@ -965,6 +1069,10 @@ async function main(argv) {
         runBrowserCommand(argv.slice(1));
         return;
     }
+    if (command === "extension") {
+        runExtensionCommand(argv.slice(1));
+        return;
+    }
     if (command === "codex-plugin") {
         runCodexPluginCommand(argv.slice(1));
         return;