@deadragdoll/tellymcp 0.0.12 → 0.0.14

package/dist/services/features/telegram-mcp/src/shared/integrations/terminal/ptyRegistry.js

@@ -54,6 +54,8 @@ exports.resizePtyTarget = resizePtyTarget;
 exports.subscribePtyTarget = subscribePtyTarget;
 exports.stopPtyTarget = stopPtyTarget;
 exports.stopAllPtyTargets = stopAllPtyTargets;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_pty_1 = require("node-pty");
 const XtermHeadless = __importStar(require("@xterm/headless"));
@@ -73,6 +75,97 @@ function buildExitLine(record) {
     }
     return `${parts.join(" ")}]`;
 }
+function sanitizeFileNameSegment(value) {
+    const sanitized = value.trim().replace(/[^a-zA-Z0-9._-]+/gu, "-");
+    return sanitized || "session";
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function buildContextPromptPrefix(record) {
+    return `[TELLY ${record.sessionId}]`;
+}
+function buildContextEnv(record) {
+    return {
+        ...process.env,
+        TELLYMCP_TERMINAL_CONTEXT: "1",
+        TELLYMCP_SESSION_ID: record.sessionId,
+        TELLYMCP_TERMINAL_TARGET: record.target,
+        TELLYMCP_TERMINAL_CWD: record.cwd,
+    };
+}
+function prepareBashLaunch(record) {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "tellymcp-pty-bash-"));
+    const rcPath = node_path_1.default.join(tempDir, `${sanitizeFileNameSegment(record.sessionId)}.bashrc`);
+    const promptPrefix = buildContextPromptPrefix(record);
+    const script = [
+        'if [ -r "$HOME/.profile" ]; then . "$HOME/.profile"; fi',
+        'if [ -r "$HOME/.bashrc" ]; then . "$HOME/.bashrc"; fi',
+        `export TELLYMCP_TERMINAL_CONTEXT=${shellSingleQuote("1")}`,
+        `export TELLYMCP_SESSION_ID=${shellSingleQuote(record.sessionId)}`,
+        `export TELLYMCP_TERMINAL_TARGET=${shellSingleQuote(record.target)}`,
+        `export TELLYMCP_TERMINAL_CWD=${shellSingleQuote(record.cwd)}`,
+        `PS1=${shellSingleQuote(`${promptPrefix} \\u@\\h:\\w\\$ `)}`,
+    ].join("\n");
+    node_fs_1.default.writeFileSync(rcPath, `${script}\n`, "utf8");
+    return {
+        args: ["--rcfile", rcPath, "-i"],
+        env: buildContextEnv(record),
+        tempPaths: [tempDir],
+    };
+}
+function prepareZshLaunch(record) {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "tellymcp-pty-zsh-"));
+    const promptPrefix = buildContextPromptPrefix(record);
+    node_fs_1.default.writeFileSync(node_path_1.default.join(tempDir, ".zshenv"), [
+        'if [[ -r "$HOME/.zshenv" ]]; then source "$HOME/.zshenv"; fi',
+        `export TELLYMCP_TERMINAL_CONTEXT=${shellSingleQuote("1")}`,
+        `export TELLYMCP_SESSION_ID=${shellSingleQuote(record.sessionId)}`,
+        `export TELLYMCP_TERMINAL_TARGET=${shellSingleQuote(record.target)}`,
+        `export TELLYMCP_TERMINAL_CWD=${shellSingleQuote(record.cwd)}`,
+        "",
+    ].join("\n"), "utf8");
+    node_fs_1.default.writeFileSync(node_path_1.default.join(tempDir, ".zshrc"), [
+        'if [[ -r "$HOME/.zprofile" ]]; then source "$HOME/.zprofile"; fi',
+        'if [[ -r "$HOME/.zshrc" ]]; then source "$HOME/.zshrc"; fi',
+        `PROMPT=${shellSingleQuote(`${promptPrefix} %n@%m:%~%# `)}`,
+        "RPROMPT=''",
+        "",
+    ].join("\n"), "utf8");
+    return {
+        args: ["-i"],
+        env: {
+            ...buildContextEnv(record),
+            ZDOTDIR: tempDir,
+        },
+        tempPaths: [tempDir],
+    };
+}
+function prepareShellLaunch(record) {
+    const shellName = getShellDisplayName(record.shell).toLowerCase();
+    if (shellName === "bash") {
+        return prepareBashLaunch(record);
+    }
+    if (shellName === "zsh") {
+        return prepareZshLaunch(record);
+    }
+    return {
+        args: [],
+        env: buildContextEnv(record),
+        tempPaths: [],
+    };
+}
+function cleanupRecordTempPaths(record) {
+    for (const tempPath of record.tempPaths) {
+        try {
+            node_fs_1.default.rmSync(tempPath, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup failures
+        }
+    }
+    record.tempPaths = [];
+}
 function createHeadlessTerminal(config) {
     return new XtermHeadless.Terminal({
         cols: config.cols,
@@ -97,13 +190,16 @@ function createSessionRecord(config, input) {
         pendingWrite: Promise.resolve(),
         pty: null,
         exited: false,
+        tempPaths: [],
     };
-    const pty = (0, node_pty_1.spawn)(record.shell, [], {
+    const launch = prepareShellLaunch(record);
+    record.tempPaths = [...launch.tempPaths];
+    const pty = (0, node_pty_1.spawn)(record.shell, launch.args, {
         name: "xterm-color",
         cols: record.cols,
         rows: record.rows,
         cwd: record.cwd,
-        env: process.env,
+        env: launch.env,
     });
     pty.onData((data) => {
         record.pendingWrite = record.pendingWrite.then(() => new Promise((resolve) => {
@@ -115,6 +211,7 @@ function createSessionRecord(config, input) {
         record.exited = true;
         record.exitCode = exitCode;
         record.signal = signal;
+        cleanupRecordTempPaths(record);
         record.pendingWrite = record.pendingWrite.then(() => new Promise((resolve) => {
             record.terminal.writeln(buildExitLine(record), resolve);
         }));
@@ -533,6 +630,7 @@ function stopPtyTarget(target) {
     record.pty?.kill();
     record.pty = null;
     record.exited = true;
+    cleanupRecordTempPaths(record);
     record.terminal.dispose();
     return true;
 }

package/dist/services/features/telegram-mcp/src/shared/lib/bodyLimits.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLimitedJsonBody = exports.assertSerializedBodySize = exports.assertStringBodySize = exports.assertBodySize = exports.isBodySizeLimitError = exports.BodySizeLimitError = exports.MAX_BASE64_SOURCE_SIZE_BYTES = exports.MAX_BODY_SIZE_BYTES = exports.MAX_BODY_SIZE = void 0;
+exports.MAX_BODY_SIZE = 16;
+exports.MAX_BODY_SIZE_BYTES = exports.MAX_BODY_SIZE * 1024 * 1024;
+exports.MAX_BASE64_SOURCE_SIZE_BYTES = Math.floor((exports.MAX_BODY_SIZE_BYTES * 3) / 4);
+class BodySizeLimitError extends Error {
+    actualBytes;
+    maxBytes;
+    statusCode = 413;
+    constructor(actualBytes, maxBytes = exports.MAX_BODY_SIZE_BYTES) {
+        const maxMiB = maxBytes / (1024 * 1024);
+        super(`Body size ${actualBytes} bytes exceeds the ${maxMiB} MiB limit.`);
+        this.actualBytes = actualBytes;
+        this.maxBytes = maxBytes;
+        this.name = "BodySizeLimitError";
+    }
+}
+exports.BodySizeLimitError = BodySizeLimitError;
+const isBodySizeLimitError = (error) => error instanceof BodySizeLimitError;
+exports.isBodySizeLimitError = isBodySizeLimitError;
+const assertBodySize = (actualBytes, maxBytes = exports.MAX_BODY_SIZE_BYTES) => {
+    if (actualBytes > maxBytes) {
+        throw new BodySizeLimitError(actualBytes, maxBytes);
+    }
+};
+exports.assertBodySize = assertBodySize;
+const assertStringBodySize = (value, maxBytes = exports.MAX_BODY_SIZE_BYTES) => {
+    (0, exports.assertBodySize)(Buffer.byteLength(value, "utf8"), maxBytes);
+};
+exports.assertStringBodySize = assertStringBodySize;
+const assertSerializedBodySize = (value) => {
+    if (value === undefined) {
+        return;
+    }
+    (0, exports.assertStringBodySize)(JSON.stringify(value));
+};
+exports.assertSerializedBodySize = assertSerializedBodySize;
+const readLimitedJsonBody = async (req) => {
+    const contentLength = req.headers["content-length"];
+    if (typeof contentLength === "string" && /^\d+$/u.test(contentLength)) {
+        (0, exports.assertBodySize)(Number(contentLength));
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(chunk);
+        totalBytes += buffer.byteLength;
+        (0, exports.assertBodySize)(totalBytes);
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0) {
+        return undefined;
+    }
+    const raw = Buffer.concat(chunks, totalBytes).toString("utf8").trim();
+    if (!raw) {
+        return undefined;
+    }
+    return JSON.parse(raw);
+};
+exports.readLimitedJsonBody = readLimitedJsonBody;

package/dist/services/features/telegram-mcp/src/shared/lib/gatewayAuth.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGatewayAuthorizationValid = isGatewayAuthorizationValid;
+const node_crypto_1 = require("node:crypto");
+function digest(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value, "utf8").digest();
+}
+function isGatewayAuthorizationValid(authorization, authToken) {
+    if (typeof authorization !== "string" || !authToken) {
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(digest(authorization), digest(`Bearer ${authToken}`));
+}

package/dist/services/features/telegram-mcp/src/shared/lib/time/localTimestamp.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLocalTimestamp = formatLocalTimestamp;
+exports.formatLocalDateSegment = formatLocalDateSegment;
+exports.formatLocalTimeSegment = formatLocalTimeSegment;
+exports.formatLocalTimestampForFileName = formatLocalTimestampForFileName;
+function padNumber(value, length = 2) {
+    return String(value).padStart(length, "0");
+}
+function formatLocalTimestamp(date = new Date()) {
+    return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}T${padNumber(date.getHours())}:${padNumber(date.getMinutes())}:${padNumber(date.getSeconds())}.${padNumber(date.getMilliseconds(), 3)}`;
+}
+function formatLocalDateSegment(date = new Date()) {
+    return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}`;
+}
+function formatLocalTimeSegment(date = new Date()) {
+    return `${padNumber(date.getHours())}-${padNumber(date.getMinutes())}-${padNumber(date.getSeconds())}`;
+}
+function formatLocalTimestampForFileName(date = new Date()) {
+    return formatLocalTimestamp(date).replace(/[:.]/gu, "-");
+}

package/docs/CHAT_CONNECTOR.md

@@ -0,0 +1,134 @@
+# ChatGPT and Claude connector
+
+TellyMCP can expose its Streamable HTTP MCP endpoint to ChatGPT and Claude
+through an OAuth 2.0 authorization-code facade with PKCE. The facade coexists
+with `MCP_HTTP_BEARER_TOKEN`; existing internal clients can continue to use the
+static bearer token.
+
+## Configure the gateway
+
+Add the following to the gateway environment file:
+
+```bash
+TELLYMCP_PUBLIC_URL=https://mcp.example.com/api
+TELLYMCP_OAUTH_ISSUER=https://mcp.example.com/api
+TELLYMCP_OAUTH_AUDIENCE=https://mcp.example.com/api
+TELLYMCP_MAGIC_TOKEN=replace_with_a_private_human_login_token
+TELLYMCP_OAUTH_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+```
+
+Generate the stable signing key with:
+
+```bash
+tellymcp oauth key
+```
+
+The command prints a dotenv-ready `TELLYMCP_OAUTH_PRIVATE_KEY_PEM` assignment.
+If the private key is omitted, TellyMCP generates an ephemeral key and existing
+OAuth access tokens stop working after a restart.
+
+For a hashed magic token, configure
+`TELLYMCP_MAGIC_TOKEN_HASH=sha256:<64-hex-digest>` instead of the raw token.
+Never configure both forms.
+
+Optional restrictions:
+
+```bash
+TELLYMCP_OAUTH_CLIENT_ID=tellymcp
+TELLYMCP_OAUTH_CLIENT_SECRET=replace_with_client_secret
+TELLYMCP_ALLOWED_REDIRECT_URIS=https://chatgpt.com/connector/oauth/...,https://claude.ai/api/mcp/auth_callback
+TELLYMCP_AUTH_CODE_TTL_SECONDS=300
+TELLYMCP_OAUTH_SCOPES=tellymcp:read tellymcp:write
+TELLYMCP_OAUTH_KEY_ID=tellymcp-oauth
+```
+
+OAuth is enabled when a connector identity, credential, redirect, or signing-key
+setting is present. `TELLYMCP_PUBLIC_URL` and one magic-token form are then
+required. Redirect URIs are matched exactly when the allowlist is configured.
+
+## Reverse proxy
+
+Proxy all `/api/` routes to TellyMCP and disable response buffering on
+`/api/mcp`. Claude also needs root path-insertion discovery routes such as:
+
+```text
+/.well-known/oauth-authorization-server/api
+/.well-known/openid-configuration/api
+/.well-known/oauth-protected-resource/api/mcp
+```
+
+The complete Nginx example is in `docs/tellymcp.gw.conf`.
+
+## Connect the chat host
+
+Use the concrete MCP endpoint in the host's `Connection` field:
+
+```text
+https://mcp.example.com/api/mcp
+```
+
+Do not enter `https://mcp.example.com/api` as the connection URL. That URL is
+the OAuth issuer/audience base, not an MCP endpoint. With the correct
+connection URL, discovery may legitimately show two related resources:
+
+```text
+OAuth issuer/audience: https://mcp.example.com/api
+MCP resource:          https://mcp.example.com/api/mcp
+```
+
+For the production deployment used while implementing this feature, the
+working ChatGPT values are:
+
+```text
+Connection:                https://drd.undoo.ru/api/mcp
+Authorization server base: https://drd.undoo.ru/api
+Resource:                  https://drd.undoo.ru/api/mcp
+OIDC configuration URL:    https://drd.undoo.ru/.well-known/openid-configuration/api
+```
+
+The `/api` suffix in the root discovery URL is expected RFC 8414
+path-insertion behavior for an issuer whose path is `/api`.
+
+Do not give the host `MCP_HTTP_BEARER_TOKEN` or the magic token. The magic token
+is entered only into the authorization page opened by the host. If a client ID
+or client secret is configured in the host, it must match the gateway values.
+
+TellyMCP tool names already use Claude-compatible letters, digits, and
+underscores, and the tools publish output schemas.
+
+## Verify before connecting
+
+```bash
+curl -fsS https://mcp.example.com/api/.well-known/oauth-protected-resource/mcp
+curl -fsS https://mcp.example.com/api/.well-known/oauth-authorization-server
+curl -fsS https://mcp.example.com/.well-known/oauth-authorization-server/api
+curl -fsS https://mcp.example.com/api/.well-known/jwks.json
+curl -i https://mcp.example.com/api/mcp
+```
+
+The last response must be `401` and include a `WWW-Authenticate` header whose
+`resource_metadata` value points to the protected-resource metadata endpoint.
+
+Access tokens are RS256 JWTs without `exp`, matching the trusted internal
+connector model. Authorization codes remain short-lived, PKCE-bound, and
+one-time-use. Failed magic-token attempts are rate-limited per source address.
+
+## Diagnostics
+
+OAuth discovery, authorization, token exchange, MCP `initialize`, and
+`tools/list` milestones are logged at `info`. Rejections are logged at `warn`
+without credentials, authorization codes, PKCE verifiers, or access tokens.
+When OAuth is enabled, every HTTP request and completed response is also logged
+with its normalized path, status, user agent, content types, MCP session id,
+and whether an Authorization header was present. Header values and tokens are
+never logged.
+
+The production Nginx sample writes connector traffic to:
+
+```text
+/var/log/nginx/tellymcp.access.log
+/var/log/nginx/tellymcp.error.log
+```
+
+If refresh stops after OAuth metadata and never logs an MCP `initialize`, first
+verify that the host's `Connection` value ends in `/api/mcp`.

package/docs/STANDALONE-ru.md

@@ -31,6 +31,8 @@ npm install -g @deadragdoll/tellymcp
 
 ```bash
 tellymcp browser install
+tellymcp extension firefox
+tellymcp extension chrome
 tellymcp codex-plugin install
 ```
 
@@ -63,6 +65,7 @@ DB_NAME=
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
 GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 ROOT_PREFIX=/api
 PORT=8080
 DISTRIBUTED_MODE=gateway
@@ -81,9 +84,15 @@ DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
 GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 GATEWAY_USER_UUID=put_owner_uuid_here
 ```
 
+Используйте один и тот же стойкий `GATEWAY_AUTH_TOKEN` на gateway и всех клиентах.
+Не смешивайте его с `GATEWAY_TOKEN`: последний разделяет данные gateway по scope,
+но не аутентифицирует HTTP- или WebSocket-транспорт. Сгенерируйте токен один раз,
+например командой `openssl rand -hex 32`, и не используйте пример значения выше.
+
 Для первого запуска также желательно задать:
 
 ```env
@@ -91,7 +100,41 @@ TELLYMCP_SESSION_ID=NEW
 TELLYMCP_SESSION_LABEL=NEW
 ```
 
-## 5. Запуск
+## 5. Attach extensions для браузера
+
+Если нужно attach'иться к уже открытому Firefox или Chrome на агентской машине, включи локальный attach bridge в env этого агента:
+
+```env
+BROWSER_ATTACH_ENABLED=true
+BROWSER_ATTACH_WS_HOST=127.0.0.1
+BROWSER_ATTACH_WS_PORT=9999
+BROWSER_ATTACH_WS_PATH=/browser-attach/ws
+```
+
+Выгрузи unpacked extension bundle из установленного пакета:
+
+```bash
+tellymcp extension firefox
+tellymcp extension chrome
+```
+
+Команда создаст один из каталогов:
+
+- `./tellymcp-firefox-attach`
+- `./tellymcp-chrome-attach`
+
+Дальше загрузи его в локальный браузер:
+
+- Firefox: `about:debugging#/runtime/this-firefox` -> `Load Temporary Add-on` -> выбрать `manifest.json`
+- Chrome: `chrome://extensions` -> включить Developer mode -> `Load unpacked` -> выбрать выгруженный каталог
+
+После этого browser control panel умеет:
+
+- attach'ить текущую agent-сессию к живой вкладке
+- запускать и останавливать structured recording bundles в `.mcp-xchange/web/...`
+- инжектить helper scripts в attached tab
+
+## 6. Запуск
 
 Gateway:
 
@@ -111,7 +154,7 @@ tellymcp run --env .env -s NEW
 tellymcp run
 ```
 
-## 6. Webhook
+## 7. Webhook
 
 Gateway поддерживает polling и webhook.
 
@@ -128,10 +171,16 @@ TELEGRAM_WEBHOOK_SECRET=change_me_webhook_secret
 
 - `/api/telegram/webhook`
 - `/api/gateway`
+- `/api/files` для короткоживущих upload/download запросов `get_file(type="url")`
 - `/api/webapp`
 - `/api/healthz`
 
-## 7. MCP
+Отдельный `location ^~ /api/files/` рекомендуется, хотя для самой маршрутизации
+он не обязателен. В нём следует отключить access log, потому что путь содержит
+токен, задать `client_max_body_size 32m` и отключить buffering запросов и
+ответов. Канонический блок приведён в `nginx/tellymcp.gw.conf`.
+
+## 8. MCP
 
 Локальный client-mode MCP endpoint:
 
@@ -141,7 +190,7 @@ http://127.0.0.1:8787/mcp
 
 Используй MCP HTTP endpoint, который поднимает `tellymcp run`.
 
-## 8. Проверки
+## 9. Проверки
 
 ```bash
 tellymcp doctor --env .env
@@ -153,7 +202,7 @@ tellymcp doctor --env .env
 tellymcp system-prune --env .env --yes
 ```
 
-## 9. Операционные заметки
+## 10. Операционные заметки
 
 - gateway-бот — это основной user-facing control plane
 - консоли видны из gateway live registry
@@ -162,7 +211,7 @@ tellymcp system-prune --env .env --yes
 - browser screenshot для человека лучше отправлять через `browser_screenshot(send_to_telegram=true)`
 - файлы между консолями лучше отправлять через `send_partner_file`
 
-## 10. Чего не делать в новых setup
+## 11. Чего не делать в новых setup
 
 Не строй новые setup вокруг:
 

package/docs/STANDALONE.md

@@ -31,6 +31,8 @@ Optional:
 
 ```bash
 tellymcp browser install
+tellymcp extension firefox
+tellymcp extension chrome
 tellymcp codex-plugin install
 ```
 
@@ -63,6 +65,7 @@ DB_NAME=
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
 GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 ROOT_PREFIX=/api
 PORT=8080
 DISTRIBUTED_MODE=gateway
@@ -81,9 +84,15 @@ DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
 GATEWAY_TOKEN=change_me_gateway_token
+GATEWAY_AUTH_TOKEN=put_strong_shared_transport_token_here
 GATEWAY_USER_UUID=put_owner_uuid_here
 ```
 
+Use the same strong `GATEWAY_AUTH_TOKEN` on the gateway and every client. Keep it
+separate from `GATEWAY_TOKEN`, which scopes gateway data but does not authenticate
+the HTTP or WebSocket transport. Generate it once, for example with
+`openssl rand -hex 32`, and do not use the illustrative value above.
+
 For the first run, also set:
 
 ```env
@@ -91,7 +100,41 @@ TELLYMCP_SESSION_ID=NEW
 TELLYMCP_SESSION_LABEL=NEW
 ```
 
-## 5. Run
+## 5. Attached Browser Extensions
+
+If you want to attach TellyMCP to an already running Firefox or Chrome tab on an agent machine, enable the local attach bridge in that agent env:
+
+```env
+BROWSER_ATTACH_ENABLED=true
+BROWSER_ATTACH_WS_HOST=127.0.0.1
+BROWSER_ATTACH_WS_PORT=9999
+BROWSER_ATTACH_WS_PATH=/browser-attach/ws
+```
+
+Export the unpacked extension bundle from the installed package:
+
+```bash
+tellymcp extension firefox
+tellymcp extension chrome
+```
+
+This creates one of:
+
+- `./tellymcp-firefox-attach`
+- `./tellymcp-chrome-attach`
+
+Load it into the local browser:
+
+- Firefox: `about:debugging#/runtime/this-firefox` -> `Load Temporary Add-on` -> choose `manifest.json`
+- Chrome: `chrome://extensions` -> enable Developer mode -> `Load unpacked` -> choose the exported directory
+
+After that the browser control panel can:
+
+- attach the current agent session to a live browser tab
+- start and stop structured recording bundles in `.mcp-xchange/web/...`
+- inject helper scripts into the attached tab
+
+## 6. Run
 
 Gateway:
 
@@ -111,7 +154,7 @@ After `.mcpsession.json` is created in the workspace, later runs can usually use
 tellymcp run
 ```
 
-## 6. Webhook
+## 7. Webhook
 
 Gateway supports polling and webhook.
 
@@ -128,10 +171,16 @@ If nginx already proxies `location /api/ { ... }` to the standalone listener, th
 
 - `/api/telegram/webhook`
 - `/api/gateway`
+- `/api/files` for short-lived `get_file(type="url")` uploads and downloads
 - `/api/webapp`
 - `/api/healthz`
 
-## 7. MCP
+A dedicated `location ^~ /api/files/` is recommended, though not required for
+routing. It should disable access logs because the path contains a token, set
+`client_max_body_size 32m`, and disable proxy request/response buffering. See
+`nginx/tellymcp.gw.conf` for the canonical block.
+
+## 8. MCP
 
 Local client-mode MCP:
 
@@ -141,7 +190,7 @@ http://127.0.0.1:8787/mcp
 
 Use the MCP HTTP endpoint exposed by `tellymcp run`.
 
-## 8. Health Checks
+## 9. Health Checks
 
 ```bash
 tellymcp doctor --env .env
@@ -153,7 +202,7 @@ Destructive cleanup:
 tellymcp system-prune --env .env --yes
 ```
 
-## 9. Operational Notes
+## 10. Operational Notes
 
 - the gateway bot is the user-facing control plane
 - consoles are discovered from the gateway live registry
@@ -162,7 +211,7 @@ tellymcp system-prune --env .env --yes
 - browser screenshot replies to humans should use `browser_screenshot(send_to_telegram=true)`
 - file results between consoles should use `send_partner_file`
 
-## 10. Legacy Concepts To Avoid
+## 11. Legacy Concepts To Avoid
 
 Do not build new setups around:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "TellyMCP - Telegram control plane for MCP-connected coding agents",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {
@@ -8,6 +8,8 @@
   },
   "files": [
     "dist",
+    "packages/firefox-attach-extension/dist",
+    "packages/chrome-attach-extension/dist",
     "scripts",
     "config/templates",
     "config/codex",
@@ -15,6 +17,7 @@
     "README-ru.md",
     "docs/STANDALONE.md",
     "docs/STANDALONE-ru.md",
+    "docs/CHAT_CONNECTOR.md",
     "VERSION.md",
     "CHANGELOG.md",
     "TOOLS.md",
@@ -36,8 +39,9 @@
   },
   "scripts": {
     "postinstall": "node ./scripts/postinstall.js",
-    "prepack": "yarn build",
-    "prepublishOnly": "yarn build && yarn lint && yarn test",
+    "build:extensions": "node ./packages/firefox-attach-extension/scripts/build.mjs && node ./packages/chrome-attach-extension/scripts/build.mjs",
+    "prepack": "yarn build && yarn build:extensions",
+    "prepublishOnly": "yarn build && yarn build:extensions && yarn lint && yarn test",
     "mcp:local": "codex mcp add telegramHuman --url http://127.0.0.1:8787/mcp",
     "dev:gw": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile /opt/tellymcp-gateway/.env-gateway --hot --mask \"**/*.service.ts\"",
     "dev:builder": "TS_NODE_TRANSPILE_ONLY=1 TS_NODE_EXPERIMENTAL_RESOLVER=1 NODE_OPTIONS=--openssl-legacy-provider ts-node ./node_modules/moleculer/bin/moleculer-runner.js src/services --config src/moleculer.config.ts --envfile ./.env-builder --hot --mask \"**/*.service.ts\"",
@@ -73,7 +77,8 @@
   "dependencies": {
     "@grammyjs/menu": "^1.3.1",
     "@grammyjs/storage-redis": "^2.5.1",
-    "@modelcontextprotocol/sdk": "^1.18.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@xterm/addon-fit": "0.10.0",
     "@xterm/headless": "5.5.0",
     "@xterm/xterm": "5.5.0",
     "amqplib": "0.10.9",
@@ -93,7 +98,7 @@
     "pino-pretty": "^13.1.3",
     "playwright": "^1.60.0",
     "socks-proxy-agent": "^8.0.5",
-    "ws": "8.20.1",
+    "ws": "8.21.0",
     "zod": "4.4.3"
   },
   "devDependencies": {