ai-browser-toolkit 0.2.2__tar.gz → 0.2.3__tar.gz

{ai_browser_toolkit-0.2.2 → ai_browser_toolkit-0.2.3}/AGENTS.md

@@ -161,7 +161,10 @@ guessing entirely. Point your client at it:
 {"command": "abt", "args": ["mcp"]}
 ```
 
-It forwards to the same server, so start `abt serve` first.
+It forwards to the same server, so start one first with `abt up` (never `abt
+serve` from a tool call — it is a command loop that never returns). The tools
+carry their own schemas, `browser_guidelines` reads this document and any site
+playbook, and the connection opens with instructions covering the rest.
 
 ## Site playbooks
 

ai_browser_toolkit-0.2.2/README.md → ai_browser_toolkit-0.2.3/PKG-INFO

@@ -1,30 +1,96 @@
-# aibrowsertoolkit
+Metadata-Version: 2.5
+Name: ai-browser-toolkit
+Version: 0.2.3
+Summary: Drive a real Chrome/Edge from your coding agent - CLI, MCP and HTTP. For Claude Code, Codex, Cursor, OpenCode.
+Project-URL: Homepage, https://github.com/skssmd/Ai-Browser-Toolkit
+Project-URL: Repository, https://github.com/skssmd/Ai-Browser-Toolkit
+Project-URL: Issues, https://github.com/skssmd/Ai-Browser-Toolkit/issues
+Project-URL: Playbooks, https://github.com/skssmd/ABT-Playbooks
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agentic,ai-agent,browser-automation,chrome,claude-code,cli,codex,cursor,mcp,model-context-protocol,opencode,playwright,selenium
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing :: Acceptance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: playwright>=1.50
+Requires-Dist: pydantic>=2.6
+Requires-Dist: selenium>=4.20
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AI Browser Toolkit
+
+**Give your coding agent a real browser.** `abt` drives an actual Chrome or Edge
+window — the one with your logins already in it — and hands back what changed
+after every action, in a form a model can act on directly.
+
+Built for agent harnesses: **Claude Code, Codex, OpenCode, Cursor, Gemini CLI,
+Copilot**, or anything you write yourself. Three ways in, same browser behind
+all of them:
+
+| | Use it when |
+|---|---|
+| **CLI** — `abt goto`, `abt find`, `abt click` | The agent already has a shell. Nothing to configure. |
+| **MCP** — `abt mcp` over stdio | Your client speaks MCP. Typed schemas, no shell quoting. |
+| **HTTP** — `POST /command` on :8765 | You are writing the integration yourself. |
 
-An HTTP server that lets an AI agent drive a real browser — **Chrome or Edge** — by
-sending JSON. The server process is the loop: it opens the chosen browser with a persistent
-profile, stays up waiting for commands, and only stops when you send `shutdown`.
+Why not a headless scraper: it keeps **one long-lived browser on a persistent
+profile**. Log into Gmail, your CRM, your ticket system once, by hand — every
+agent session after that is already signed in, and the window outlives your
+editor.
 
-> **Agents: read [`guidelines/toolkit-workflow.md`](guidelines/toolkit-workflow.md)
-> before driving anything.** Not "if your site looks tricky", not "if there is a
-> playbook for it" — always. Most sites have no playbook, and that file is the
-> whole answer for them. Then, only if one exists, add the site playbook from
-> [`guidelines/`](guidelines/README.md).
+```
+abt up  ──starts──>  server :8765  ──owns──>  Chrome/Edge (your profile)
+                          ^
+   abt CLI  /  abt mcp  /  your HTTP client
+```
+
+> **Agents: read the workflow before driving anything** — `abt guidelines show
+> toolkit-workflow`, or [`guidelines/toolkit-workflow.md`](https://github.com/skssmd/Ai-Browser-Toolkit/blob/main/guidelines/toolkit-workflow.md)
+> in this repo. Not "if your site looks tricky", not "if there is a playbook for
+> it" — always. Most sites have no playbook, and that file is the whole answer
+> for them.
 >
-> Skipping it costs you the things that are hard to guess: that `find` hands
-> back refs you act on directly, that a click already reports what changed so
-> you need not re-read the page, and that ops can be sent in batches.
+> Skipping it costs the things that are hard to guess: that `find` hands back
+> refs you act on directly, that a click already reports what changed so you
+> need not re-read the page, and that ops can be sent in batches.
+
+## Install
 
+Needs **Python 3.11+** and **Google Chrome** or **Microsoft Edge** installed.
+Drivers are resolved automatically — nothing to download by hand.
 
-```
-abt serve  ──starts──>  FastAPI :8765  ──owns──>  Chrome/Edge (persistent profile)
-                             ^
-   abt / curl / your agent ──┘   POST /command  |  POST /commands
+```bash
+pip install ai-browser-toolkit
+abt doctor        # what browsers are installed, and where
 ```
 
-## Install
+Also on **winget** (`winget install skssmd.AIBrowserToolkit`), **Scoop**,
+**Homebrew** (`brew install skssmd/tap/abt`) and the **AUR**.
+
+Point an MCP client at it:
 
-Needs **Python 3.11+** and **Google Chrome** or **Microsoft Edge** installed. The matching
-chromedriver/msedgedriver is resolved automatically by Selenium Manager — nothing to download by hand.
+```json
+{"mcpServers": {"browser": {"command": "abt", "args": ["mcp"]}}}
+```
+
+<details>
+<summary>From a source checkout instead</summary>
 
 ```bash
 git clone https://github.com/skssmd/Ai-Browser-Toolkit
@@ -33,12 +99,7 @@ cd Ai-Browser-Toolkit
 python -m venv .venv
 .venv/Scripts/python -m pip install -e ".[dev]"     # Windows
 # .venv/bin/python -m pip install -e ".[dev]"       # macOS / Linux
-```
-
-Check it worked:
-
-```bash
-.venv/Scripts/python -m pytest -q     # 485 tests, needs Chrome
+.venv/Scripts/python -m pytest -q                   # 485 tests, needs Chrome
 ```
 
 The `abt` command lands in the venv. Either activate it
@@ -46,6 +107,8 @@ The `abt` command lands in the venv. Either activate it
 PATH, or call it explicitly as `.venv/Scripts/python -m abt.cli …` everywhere
 below.
 
+</details>
+
 ## Run
 
 > **Start the server as a separate process.** `abt serve` is the command loop —
@@ -262,7 +325,7 @@ returns only what arrived since your last read of that thread — matched by
 content, not position, because Messenger trims the top of a long thread as it
 grows.
 
-Full details and the traps behind them: [guidelines/messenger.com/messenger.md](guidelines/messenger.com/messenger.md).
+Full details and the traps behind them: [guidelines/messenger.com/messenger.md](https://github.com/skssmd/Ai-Browser-Toolkit/blob/main/guidelines/messenger.com/messenger.md).
 
 ## Console and network
 
@@ -615,7 +678,7 @@ needed to turn something you can read into something you can act on.
 **The limit:** `mode: "closed"` makes `.shadowRoot` null. No JavaScript can read
 such a root or prove it exists, so nothing here can either. "Not found" means
 nothing reachable has it — see the search ladder in
-[`guidelines/toolkit-workflow.md`](guidelines/toolkit-workflow.md).
+[`guidelines/toolkit-workflow.md`](https://github.com/skssmd/Ai-Browser-Toolkit/blob/main/guidelines/toolkit-workflow.md).
 
 ### The manual check
 
@@ -877,10 +940,16 @@ guessed parameter name — `label` on a `select`, `diff` on a `get_text`, a
 the JSON never meets a shell, which on Windows is its own source of quoting
 failures.
 
-Thirteen tools rather than one per op, since every schema sits in the model's
+Seventeen tools rather than one per op, since every schema sits in the model's
 context for the whole session. `browser_batch` sends a whole sequence in one
 call, and `browser_command` passes through any raw op the named tools miss.
 
+The server also answers `initialize` with MCP `instructions` — how the pieces
+fit together, which most clients place in the system prompt once. That is where
+the orientation goes, because it is paid for once rather than re-sent with the
+schemas on every turn. `browser_guidelines` reads the rest: the whole
+workflow document, or a fuzzy search for a site's playbook.
+
 ## Tests
 
 ```bash

ai_browser_toolkit-0.2.2/PKG-INFO → ai_browser_toolkit-0.2.3/README.md

@@ -1,49 +1,61 @@
-Metadata-Version: 2.5
-Name: ai-browser-toolkit
-Version: 0.2.2
-Summary: Agentic browser automation CLI for AI agents
-License-Expression: Apache-2.0
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: fastapi>=0.110
-Requires-Dist: httpx>=0.27
-Requires-Dist: playwright>=1.50
-Requires-Dist: pydantic>=2.6
-Requires-Dist: selenium>=4.20
-Requires-Dist: typer>=0.12
-Requires-Dist: uvicorn>=0.29
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: pyyaml>=6.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# aibrowsertoolkit
-
-An HTTP server that lets an AI agent drive a real browser — **Chrome or Edge** — by
-sending JSON. The server process is the loop: it opens the chosen browser with a persistent
-profile, stays up waiting for commands, and only stops when you send `shutdown`.
-
-> **Agents: read [`guidelines/toolkit-workflow.md`](guidelines/toolkit-workflow.md)
-> before driving anything.** Not "if your site looks tricky", not "if there is a
-> playbook for it" — always. Most sites have no playbook, and that file is the
-> whole answer for them. Then, only if one exists, add the site playbook from
-> [`guidelines/`](guidelines/README.md).
->
-> Skipping it costs you the things that are hard to guess: that `find` hands
-> back refs you act on directly, that a click already reports what changed so
-> you need not re-read the page, and that ops can be sent in batches.
+# AI Browser Toolkit
+
+**Give your coding agent a real browser.** `abt` drives an actual Chrome or Edge
+window — the one with your logins already in it — and hands back what changed
+after every action, in a form a model can act on directly.
+
+Built for agent harnesses: **Claude Code, Codex, OpenCode, Cursor, Gemini CLI,
+Copilot**, or anything you write yourself. Three ways in, same browser behind
+all of them:
 
+| | Use it when |
+|---|---|
+| **CLI** — `abt goto`, `abt find`, `abt click` | The agent already has a shell. Nothing to configure. |
+| **MCP** — `abt mcp` over stdio | Your client speaks MCP. Typed schemas, no shell quoting. |
+| **HTTP** — `POST /command` on :8765 | You are writing the integration yourself. |
+
+Why not a headless scraper: it keeps **one long-lived browser on a persistent
+profile**. Log into Gmail, your CRM, your ticket system once, by hand — every
+agent session after that is already signed in, and the window outlives your
+editor.
 
 ```
-abt serve  ──starts──>  FastAPI :8765  ──owns──>  Chrome/Edge (persistent profile)
-                             ^
-   abt / curl / your agent ──┘   POST /command  |  POST /commands
+abt up  ──starts──>  server :8765  ──owns──>  Chrome/Edge (your profile)
+                          ^
+   abt CLI  /  abt mcp  /  your HTTP client
 ```
 
+> **Agents: read the workflow before driving anything** — `abt guidelines show
+> toolkit-workflow`, or [`guidelines/toolkit-workflow.md`](https://github.com/skssmd/Ai-Browser-Toolkit/blob/main/guidelines/toolkit-workflow.md)
+> in this repo. Not "if your site looks tricky", not "if there is a playbook for
+> it" — always. Most sites have no playbook, and that file is the whole answer
+> for them.
+>
+> Skipping it costs the things that are hard to guess: that `find` hands back
+> refs you act on directly, that a click already reports what changed so you
+> need not re-read the page, and that ops can be sent in batches.
+
 ## Install
 
-Needs **Python 3.11+** and **Google Chrome** or **Microsoft Edge** installed. The matching
-chromedriver/msedgedriver is resolved automatically by Selenium Manager — nothing to download by hand.
+Needs **Python 3.11+** and **Google Chrome** or **Microsoft Edge** installed.
+Drivers are resolved automatically — nothing to download by hand.
+
+```bash
+pip install ai-browser-toolkit
+abt doctor        # what browsers are installed, and where
+```
+
+Also on **winget** (`winget install skssmd.AIBrowserToolkit`), **Scoop**,
+**Homebrew** (`brew install skssmd/tap/abt`) and the **AUR**.
+
+Point an MCP client at it:
+
+```json
+{"mcpServers": {"browser": {"command": "abt", "args": ["mcp"]}}}
+```
+
+<details>
+<summary>From a source checkout instead</summary>
 
 ```bash
 git clone https://github.com/skssmd/Ai-Browser-Toolkit
@@ -52,12 +64,7 @@ cd Ai-Browser-Toolkit
 python -m venv .venv
 .venv/Scripts/python -m pip install -e ".[dev]"     # Windows
 # .venv/bin/python -m pip install -e ".[dev]"       # macOS / Linux
-```
-
-Check it worked:
-
-```bash
-.venv/Scripts/python -m pytest -q     # 485 tests, needs Chrome
+.venv/Scripts/python -m pytest -q                   # 485 tests, needs Chrome
 ```
 
 The `abt` command lands in the venv. Either activate it
@@ -65,6 +72,8 @@ The `abt` command lands in the venv. Either activate it
 PATH, or call it explicitly as `.venv/Scripts/python -m abt.cli …` everywhere
 below.
 
+</details>
+
 ## Run
 
 > **Start the server as a separate process.** `abt serve` is the command loop —
@@ -281,7 +290,7 @@ returns only what arrived since your last read of that thread — matched by
 content, not position, because Messenger trims the top of a long thread as it
 grows.
 
-Full details and the traps behind them: [guidelines/messenger.com/messenger.md](guidelines/messenger.com/messenger.md).
+Full details and the traps behind them: [guidelines/messenger.com/messenger.md](https://github.com/skssmd/Ai-Browser-Toolkit/blob/main/guidelines/messenger.com/messenger.md).
 
 ## Console and network
 
@@ -634,7 +643,7 @@ needed to turn something you can read into something you can act on.
 **The limit:** `mode: "closed"` makes `.shadowRoot` null. No JavaScript can read
 such a root or prove it exists, so nothing here can either. "Not found" means
 nothing reachable has it — see the search ladder in
-[`guidelines/toolkit-workflow.md`](guidelines/toolkit-workflow.md).
+[`guidelines/toolkit-workflow.md`](https://github.com/skssmd/Ai-Browser-Toolkit/blob/main/guidelines/toolkit-workflow.md).
 
 ### The manual check
 
@@ -896,10 +905,16 @@ guessed parameter name — `label` on a `select`, `diff` on a `get_text`, a
 the JSON never meets a shell, which on Windows is its own source of quoting
 failures.
 
-Thirteen tools rather than one per op, since every schema sits in the model's
+Seventeen tools rather than one per op, since every schema sits in the model's
 context for the whole session. `browser_batch` sends a whole sequence in one
 call, and `browser_command` passes through any raw op the named tools miss.
 
+The server also answers `initialize` with MCP `instructions` — how the pieces
+fit together, which most clients place in the system prompt once. That is where
+the orientation goes, because it is paid for once rather than re-sent with the
+schemas on every turn. `browser_guidelines` reads the rest: the whole
+workflow document, or a fuzzy search for a site's playbook.
+
 ## Tests
 
 ```bash

ai_browser_toolkit-0.2.3/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-browser-toolkit"
+version = "0.2.3"
+# One line, and it is what PyPI search results show. It has to answer "for
+# whom" as well as "what": a browser-automation library is a crowded shelf, and
+# the thing that makes this one different is that a coding agent drives it,
+# through whichever of the three interfaces that agent already speaks.
+description = "Drive a real Chrome/Edge from your coding agent - CLI, MCP and HTTP. For Claude Code, Codex, Cursor, OpenCode."
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "browser-automation",
+    "ai-agent",
+    "agentic",
+    "claude-code",
+    "codex",
+    "opencode",
+    "cursor",
+    "playwright",
+    "selenium",
+    "chrome",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Testing :: Acceptance",
+    "Topic :: Utilities",
+]
+
+# PyPI renders this as the whole project page. Without it the page is a blank
+# stub carrying only the one-line description above -- which is what every
+# `pip install ai-browser-toolkit` sends people to look at.
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = [
+    # Playwright is the default engine. Selenium is still required rather
+    # than optional because `engine.py` derives the neutral exception names
+    # from Selenium's classes at import time -- making it opt-in means
+    # defining those natively first. See docs/TODO.md.
+    "playwright>=1.50",
+    "selenium>=4.20",
+    "fastapi>=0.110",
+    "uvicorn>=0.29",
+    "pydantic>=2.6",
+    "httpx>=0.27",
+    "typer>=0.12",
+]
+
+# The PyPI sidebar. Without these the page offers no way back to the source,
+# and a reader who wants to know what a playbook actually contains before
+# trusting one has nowhere to go.
+[project.urls]
+Homepage = "https://github.com/skssmd/Ai-Browser-Toolkit"
+Repository = "https://github.com/skssmd/Ai-Browser-Toolkit"
+Issues = "https://github.com/skssmd/Ai-Browser-Toolkit/issues"
+Playbooks = "https://github.com/skssmd/ABT-Playbooks"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pyyaml>=6.0"]
+
+[project.scripts]
+abt = "abt.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/abt"]
+# onehr names a real organisation, its routes and its staff records. It is
+# gitignored, but a build reads the working tree rather than git -- so without
+# this, anyone building from a checkout that still has those files would ship
+# them to PyPI. A test asserts they are absent from the built wheel.
+exclude = ["**/onehr/**", "**/*onehr*"]
+
+[tool.hatch.build.targets.wheel.force-include]
+# Shipped inside the package so every channel carries them, and so the server
+# can serve one to an agent that is already talking to it.
+"guidelines" = "abt/guidelines"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{ai_browser_toolkit-0.2.2 → ai_browser_toolkit-0.2.3}/src/abt/mcp.py

@@ -36,6 +36,48 @@ import httpx
 PROTOCOL_VERSION = "2025-06-18"
 DEFAULT_API = "http://127.0.0.1:8765"
 
+# Sent once, in the initialize reply, and clients put it in the system prompt.
+# That is the cheap slot: per-tool descriptions are re-sent every turn, so
+# anything that is true of the *toolkit* rather than of one tool belongs here
+# and is paid for once. Without it a model knows what each tool does and still
+# does not know that the browser is a separate step from the server, or that
+# the reply it already holds contains the page.
+INSTRUCTIONS = """\
+Browser automation against one long-lived Chrome. The server is a separate
+process that outlives this session; it owns the browser and this connection
+owns nothing.
+
+Start here:
+
+  browser_session {"action":"start"}   -- the server runs WITHOUT a browser on
+  purpose, and nothing starts one for you. Every page tool fails with
+  browser_dead until you do this. It can take up to two minutes on a profile
+  that has logins in it. browser_session {"action":"status"} says what is up.
+
+Then read what you are given. Every tool that changes the page returns a
+dom_diff: the text that appeared, and dom_diff.actionable listing new controls
+with refs. Re-reading the page to see what happened is the most common and most
+expensive mistake made with this toolkit -- the answer is already in the reply.
+
+Addressing an element: exactly ONE of ref, css, xpath or text. Refs come from
+browser_find and from a diff's actionable list, and they die on navigation.
+
+browser_find searches the document, every frame and (with shadow=true) open
+shadow roots. count=0 is an answer, not a bad selector -- the control does not
+exist yet, so click whatever creates it. Do not fall back to browser_run_js to
+scan the DOM.
+
+browser_batch runs a sequence you already know in one round trip. Prefer it
+over one call per step.
+
+Site playbooks: before driving an unfamiliar site call browser_guidelines with
+that domain. Some sites have a written procedure, and it is shorter than
+discovering the page. browser_guidelines {"name":"toolkit-workflow"} is the
+full workflow document.
+
+Every failure carries a `hint` saying what to do next. Read it before retrying.
+"""
+
 _TARGET = {
     "ref": {"type": "string", "description": "Ref from a find, or from a diff's actionable list."},
     "css": {"type": "string"},
@@ -221,6 +263,19 @@ TOOLS: list[dict] = [
         ),
         "inputSchema": _schema({"command": {"type": "object"}}, ["command"]),
     },
+    {
+        "name": "browser_guidelines",
+        "description": (
+            "The toolkit's own docs. domain=<host> asks whether a written "
+            "playbook exists for a site -- fuzzy, so 'sheets' finds "
+            'docs.google.com. name="toolkit-workflow" returns the full '
+            "workflow. Neither argument lists what is installed."
+        ),
+        "inputSchema": _schema({
+            "domain": {"type": "string", "description": "Site to look up. Fuzzy."},
+            "name": {"type": "string", "description": "Playbook to read in full."},
+        }),
+    },
     {
         "name": "browser_session",
         "description": (
@@ -246,6 +301,22 @@ TOOLS: list[dict] = [
 ]
 
 
+def _version() -> str:
+    """The installed version, or a placeholder from a source tree.
+
+    Hardcoding it here meant every release since 0.1.0 announced itself as
+    0.1.0 to every MCP client.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    from . import paths
+
+    try:
+        return version(paths.DIST_NAME)
+    except PackageNotFoundError:
+        return "0"
+
+
 def _one_of(args: dict, *names: str) -> dict:
     return {name: args[name] for name in names if args.get(name) is not None}
 
@@ -336,19 +407,40 @@ class Bridge:
 
     def call(self, tool: str, args: dict) -> tuple[str, bool]:
         """Returns (text, is_error). Never raises -- an agent needs a message."""
+        # Playbooks are reads, not ops: they live behind GET /guidelines, and
+        # the server never serves an untrusted one. Routed here rather than in
+        # to_op because to_op's whole output shape is "an op".
+        if tool == "browser_guidelines":
+            if args.get("name"):
+                request = ("GET", f"/guidelines/{args['name']}", None)
+            elif args.get("domain"):
+                # /search, not /lookup: lookup is exact-domain only, and an
+                # agent that has just landed somewhere has a hostname it is
+                # guessing at. No match comes back as an empty list.
+                request = ("GET", "/guidelines/search", {"q": args["domain"]})
+            else:
+                request = ("GET", "/guidelines", None)
+        else:
+            try:
+                payload = to_op(tool, args)
+            except KeyError:
+                return f"no such tool: {tool}", True
+            endpoint = "/commands" if tool == "browser_batch" else "/command"
+            request = ("POST", endpoint, payload)
+
+        method, path, body = request
         try:
-            payload = to_op(tool, args)
-        except KeyError:
-            return f"no such tool: {tool}", True
-
-        endpoint = "/commands" if tool == "browser_batch" else "/command"
-        try:
-            response = self.client.post(f"{self.api}{endpoint}", json=payload)
+            if method == "GET":
+                response = self.client.get(f"{self.api}{path}", params=body)
+            else:
+                response = self.client.post(f"{self.api}{path}", json=body)
         except httpx.RequestError as exc:
             return (
                 f"cannot reach the toolkit at {self.api} ({exc}). It is a separate, "
                 "long-lived process that owns the browser -- start it with "
-                "`abt serve --browser chrome` and wait for GET /status to answer.",
+                "`abt up` and wait for GET /status to answer. Never run "
+                "`abt serve` from a tool call: it is a command loop that never "
+                "returns, and whatever launched it hangs.",
                 True,
             )
 
@@ -385,7 +477,11 @@ class Server:
             return self._ok(request_id, {
                 "protocolVersion": PROTOCOL_VERSION,
                 "capabilities": {"tools": {}},
-                "serverInfo": {"name": "aibrowsertoolkit", "version": "0.1.0"},
+                "serverInfo": {"name": "aibrowsertoolkit", "version": _version()},
+                # Where the orientation goes. Clients that honour it put this
+                # in the system prompt once; the rest ignore it and lose
+                # nothing, because every tool still describes itself.
+                "instructions": INSTRUCTIONS,
             })
 
         if method == "tools/list":

{ai_browser_toolkit-0.2.2 → ai_browser_toolkit-0.2.3}/src/abt/server.py

@@ -353,9 +353,27 @@ def create_app(
 
         found = await run_in_threadpool(g.lookup, domain)
         if found is None:
-            return fail(OpError("element_not_found", f"no playbook for {domain}"))
+            return fail(
+                OpError(
+                    "element_not_found",
+                    f"no playbook for {domain}",
+                    hint=(
+                        "This is an exact-domain lookup. For anything else -- a "
+                        "product name, a subdomain, a guess -- use "
+                        "GET /guidelines/search?q=, which is fuzzy. A site with "
+                        "no playbook is normal: drive it directly."
+                    ),
+                )
+            )
         return ok(found)
 
+    @app.get("/guidelines/search")
+    async def guidelines_search(q: str):
+        """Fuzzy, and never an error: no match is an answer, not a failure."""
+        from . import guidelines as g
+
+        return ok(await run_in_threadpool(g.search, q))
+
     @app.get("/guidelines/{name:path}")
     async def guidelines_read(name: str):
         from . import guidelines as g
@@ -366,7 +384,18 @@ def create_app(
             # --pending` is the reviewing path, and it warns.
             return ok({"name": name, "markdown": g.read(name)})
         except KeyError:
-            return fail(OpError("element_not_found", f"no playbook named {name}"))
+            return fail(
+                OpError(
+                    "element_not_found",
+                    f"no playbook named {name}",
+                    hint=(
+                        "GET /guidelines lists what is installed and readable. "
+                        "A playbook that was pulled but not trusted is not "
+                        "served here at all -- `abt guidelines trust <domain>` "
+                        "after a person has read it."
+                    ),
+                )
+            )
 
     # --- browser lifecycle ----------------------------------------------------
 

ai_browser_toolkit-0.2.2/pyproject.toml

@@ -1,49 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "ai-browser-toolkit"
-version = "0.2.2"
-description = "Agentic browser automation CLI for AI agents"
-# PyPI renders this as the whole project page. Without it the page is a blank
-# stub carrying only the one-line description above -- which is what every
-# `pip install ai-browser-toolkit` sends people to look at.
-readme = "README.md"
-license = "Apache-2.0"
-requires-python = ">=3.11"
-dependencies = [
-    # Playwright is the default engine. Selenium is still required rather
-    # than optional because `engine.py` derives the neutral exception names
-    # from Selenium's classes at import time -- making it opt-in means
-    # defining those natively first. See docs/TODO.md.
-    "playwright>=1.50",
-    "selenium>=4.20",
-    "fastapi>=0.110",
-    "uvicorn>=0.29",
-    "pydantic>=2.6",
-    "httpx>=0.27",
-    "typer>=0.12",
-]
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0", "pyyaml>=6.0"]
-
-[project.scripts]
-abt = "abt.cli:app"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/abt"]
-# onehr names a real organisation, its routes and its staff records. It is
-# gitignored, but a build reads the working tree rather than git -- so without
-# this, anyone building from a checkout that still has those files would ship
-# them to PyPI. A test asserts they are absent from the built wheel.
-exclude = ["**/onehr/**", "**/*onehr*"]
-
-[tool.hatch.build.targets.wheel.force-include]
-# Shipped inside the package so every channel carries them, and so the server
-# can serve one to an agent that is already talking to it.
-"guidelines" = "abt/guidelines"
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]