Document Fortress stealth-browser tools

.env.example

@@ -36,3 +36,17 @@ PLAYWRIGHT_BROWSER=
 # PLAYWRIGHT_EXTRA_ARGS: shell-style extra flags for @playwright/mcp, e.g.
 #   PLAYWRIGHT_EXTRA_ARGS=--device "iPhone 15" --isolated
 PLAYWRIGHT_EXTRA_ARGS=
+
+# Fortress stealth-browser tools (MCP bridge). When FORTRESS_ENABLED=true the
+# agent gets ~30 fortress_* tools (read/extract pages as markdown, fetch pages
+# behind Cloudflare/DataDome, web search, crawl, screenshots, saved logins).
+# The Docker image ships it; on a bare host run: pip install "tilion[mcp]" "mcp<2"
+FORTRESS_ENABLED=
+# FORTRESS_COMMAND: how to start the server. Default tilion-mcp; if that isn't
+# on PATH (common on Windows) use: python -m tilion.mcp
+FORTRESS_COMMAND=
+FORTRESS_HEADLESS=true
+# Optional: residential proxy, region hint, captcha solver key.
+TILION_PROXY=
+TILION_REGION=
+CAPTCHA_API_KEY=

README.md

@@ -49,6 +49,14 @@ The bot can read and write the owner's Google Calendar. Setup is one-time in Goo
 
 The refresh token is stored at `workspace/.secretary/google-token.json`. Delete that file to disconnect; run `/connect_calendar` again to relink.
 
+## Stealth browsing (Fortress)
+
+[Fortress](https://github.com/tiliondev/fortress) is a Chromium build that corrects the browser fingerprint inside the engine, so pages behind Cloudflare, DataDome, PerimeterX, or Akamai load instead of returning 403 or a challenge. With `FORTRESS_ENABLED=true` the bot starts its MCP server (`tilion-mcp`) and the agent gets about 30 `fortress_*` tools: `read_page` and `extract_page` (clean markdown, far fewer tokens than raw HTML), `fetch_protected_page`, `search_web`, `crawl_site`, `screenshot_page`, `save_profile` / `load_profile` for keeping logins, and more. It sits next to the Playwright tools; the agent is told to reach for Fortress when reading the web or when a site blocks it.
+
+The Docker image ships it ready to use. On a bare host, install it once with `pip install "tilion[mcp]" "mcp<2"` (the pin works around tilion not supporting the 2.x MCP library yet); the engine, about 200 MB, downloads on first use. Linux x64 and Windows x64 only.
+
+Screenshots, saved pages, downloads, and saved profiles land in `workspace/fortress/`, so the agent can send them back with `send`. If Fortress fails to start, the bot logs the error and runs without it. Set `LOG_LEVEL=debug` to see the server's own output.
+
 ## Workspace
 
 ```
@@ -57,6 +65,7 @@ workspace/
   MEMORY.md    facts the assistant keeps; it edits this itself
   scripts/     scripts for scheduled jobs
   inbox/       files you sent
+  fortress/    files written by the Fortress tools
   .secretary/  runtime state
 ```
 
@@ -80,6 +89,13 @@ The agent's edits to `MEMORY.md` are local runtime data. Leave them uncommitted,
 | `PLAYWRIGHT_HEADLESS` | no | `true` | Run browser headless. `false` opens a visible window |
 | `PLAYWRIGHT_BROWSER` | no | `chrome` | `chrome`, `firefox`, `webkit`, or `msedge` |
 | `PLAYWRIGHT_EXTRA_ARGS` | no | | Extra flags passed to `@playwright/mcp` (shell-quoted) |
+| `FORTRESS_ENABLED` | no | `false` | Enable the Fortress stealth-browser MCP bridge (`fortress_*` tools) |
+| `FORTRESS_COMMAND` | no | `tilion-mcp` | Command that starts the Fortress MCP server (shell-quoted), e.g. `python -m tilion.mcp` |
+| `FORTRESS_HEADLESS` | no | `true` | `false` opens a visible Fortress window (native hosts only) |
+| `FORTRESS_CHANNEL` | no | `latest` | Fortress engine channel. `stable` currently fails to launch (upstream bundle naming bug) |
+| `TILION_PROXY` | no | | Egress proxy for Fortress, `http://user:pass@host:port`. A residential proxy is the main lever on hard targets |
+| `TILION_REGION` | no | | Region hint for Fortress, e.g. `us`, so timezone and locale match the proxy IP |
+| `CAPTCHA_API_KEY` | no | | Captcha solver key; enables `fortress_solve_captcha` and auto-solve during fetch |
 | `GOOGLE_CLIENT_ID` | no | | OAuth client id (TVs and Limited Input devices) — enables the calendar tool |
 | `GOOGLE_CLIENT_SECRET` | no | | OAuth client secret — required alongside `GOOGLE_CLIENT_ID` |
 | `GOOGLE_REFRESH_TOKEN` | no | | Deprecated. If set, seeded once into `workspace/.secretary/google-token.json`, then ignored. |
@@ -121,3 +137,5 @@ Run `npm run dev` with a real bot and walk through every line:
 19. Reply to one of the bot's earlier messages with a follow-up like "what did you mean by that?" → the answer references that specific message, not the most recent one. Then "reply with quote" a specific phrase from a bot message → the answer references the quoted phrase.
 20. Forward a voice message from another chat and add a text comment. The bot should reply once, referencing both your comment and what the voice said, not twice with each in isolation.
 21. Delete `workspace/.secretary/google-token.json` if it exists. Ask "what's on my calendar tomorrow?" → tool replies with a "not connected" message referencing `/connect_calendar`. Run `/connect_calendar` → bot replies with a `https://google.com/device` URL and a short code. Approve on that page, then `/calendar_done` → bot replies `✅ Calendar connected.` and the token file now exists. Ask the same calendar question again → the tool answers.
+22. Start with `FORTRESS_ENABLED=true`. Startup log shows `fortress tools enabled (N tools)` with N around 30. Ask "read https://quotes.toscrape.com/js/ and give me the first three quotes" → the quotes come back (that page is empty without JavaScript).
+23. With Fortress enabled, ask "take a Fortress screenshot of https://example.com and send it" → an image attachment arrives and `workspace/fortress/` has the PNG.

SETUP-WINDOWS.md

@@ -51,6 +51,8 @@ No quotes, no spaces around `=`.
 | `SECRETARY_SHELL=` | Full path to `bash.exe` if Git is not installed at `C:\Program Files\Git`. |
 | `WORKSPACE_DIR=./workspace` | Where the assistant keeps its memory file, scripts, and files you send. |
 | `LOG_LEVEL=info` | Set to `debug` to see more in the console. |
+| `FORTRESS_ENABLED=` | Set to `true` to give the assistant the Fortress stealth browser, for reading pages that block normal browsers. Needs Python: open a terminal and run `pip install "tilion[mcp]" "mcp<2"` once. The browser engine (about 200 MB) downloads the first time it is used. |
+| `FORTRESS_COMMAND=` | Leave empty. If the console says `fortress bridge failed to start` with `ENOENT`, set it to `python -m tilion.mcp`. |
 
 4. Save the file and close Notepad.
 
@@ -120,6 +122,8 @@ Alternatively, Windows Task Scheduler can start `run.bat` at logon, but any star
 | Voice notes reply "Voice transcription is not configured" | No OpenAI key | Add `OPENAI_API_KEY` to `.env` and restart |
 | A scheduled script fails with `failed to start bash` | Git for Windows is not at the default path | Set `SECRETARY_SHELL` to the full path of `bash.exe` |
 | Replies arrive as raw text with `<b>` tags | Telegram rejected the formatting, the bot fell back to plain text | Harmless; report the message content if it repeats |
+| `fortress bridge failed to start` with `ENOENT` | `tilion-mcp` is not on PATH | Set `FORTRESS_COMMAND=python -m tilion.mcp` in `.env` |
+| `fortress bridge failed to start` with `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | pip installed the 2.x MCP library, which Fortress doesn't support yet | Run `pip install "mcp<2"` |
 | The window closes before you can read anything | An error happened before the launcher's pause | Open a terminal in the folder and run `.\run.bat` from there |
 
 If the console shows a message not in this table, start the bot with `LOG_LEVEL=debug` in `.env` and read the last few lines before the exit.