loom-harness 0.1.0__tar.gz

loom_harness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Caron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loom_harness-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: loom-harness
+Version: 0.1.0
+Summary: Stealth browser harness for autonomous LLM agents — Camoufox/Playwright wrapped behind a CLI, JSON-RPC daemon, and MCP server.
+Keywords: browser,automation,playwright,camoufox,agent,llm,mcp,scraping,stealth
+Author: Thomas Caron
+Author-email: Thomas Caron <thomas.caron00@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Dist: playwright>=1.49
+Requires-Dist: camoufox[geoip]>=0.4
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: websockets>=12
+Requires-Dist: anyio>=4
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10
+Requires-Dist: orjson>=3.11.8
+Requires-Dist: pytesseract>=0.3 ; extra == 'ocr'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/tomtom103/loom
+Project-URL: Repository, https://github.com/tomtom103/loom
+Project-URL: Issues, https://github.com/tomtom103/loom/issues
+Provides-Extra: ocr
+Description-Content-Type: text/markdown
+
+# Loom
+
+**Stealth browser harness for autonomous LLM agents.**
+
+Loom gives an agent a fast, observable handle on a real browser — open a tab,
+click things, read the DOM, watch the network, run JS, replay APIs, persist
+auth — exposed three ways:
+
+- A CLI: `loom <namespace> <verb>` (JSONL output, scriptable, debuggable).
+- A long-lived JSON-RPC daemon: `loomd` (Unix socket at `~/.loom/loomd.sock`,
+  auto-spawned on the first command).
+- An MCP server: `loom mcp` (stdio transport, ~50 tools auto-derived from the
+  RPC registry).
+
+All three share the same daemon, so a session opened from the CLI is drivable
+from MCP and vice versa.
+
+The default engine is **[Camoufox](https://github.com/daijro/camoufox)**, a
+stealth-patched Firefox build with BrowserForge fingerprints. Chromium,
+Firefox, and WebKit are also supported by passing `--engine`.
+
+## Why
+
+Agent automation against real websites is a pile of small problems: bot
+detection, flaky locators, capturing network traffic, persisting login state,
+juggling multi-tab work, snapshotting state for the model to reason over.
+Loom packages those into one fast, predictable harness so the agent can spend
+its tokens on the actual task.
+
+## Status
+
+Beta. ~625 unit tests, 81% line coverage. The public RPC surface is stable;
+internal layout still moves between releases.
+
+## Install
+
+```bash
+pip install loom-harness
+playwright install firefox     # for chromium/firefox/webkit engines
+camoufox fetch                 # for the camoufox stealth engine
+```
+
+On headless Linux, Loom can run any engine **headed** against a virtual
+display for better stealth. Install Xvfb once:
+
+```bash
+sudo apt-get install xvfb      # Debian/Ubuntu
+```
+
+Loom auto-detects Xvfb on `PATH` and uses it when `--display auto` is set
+(the default).
+
+## Quickstart
+
+```bash
+# Daemon starts itself the first time the CLI talks to it.
+loom browser open --session s1 --display virtual --viewport 1280x720
+loom page goto https://example.com -s s1
+loom page snap -s s1 --max 30 | jq '.elements[0:5]'
+loom dom click 'role:link[name="More information..."]' -s s1
+loom page info -s s1
+loom browser close -s s1
+```
+
+`page snap` is the agent's primary "look" call — one payload combining a
+screenshot, an element index, and stable, semantic locator strings (the same
+grammar accepted by `dom.click`, `dom.type`, etc).
+
+## What's in the box
+
+| Namespace   | Highlights |
+|-------------|------------|
+| `browser`   | open / close / list; multi-engine (camoufox \| chromium \| firefox \| webkit); persistent profiles; emulation knobs (viewport, locale, timezone, geolocation, color scheme, proxy, UA); Camoufox stealth knobs (OS fingerprint, geoip, humanize, WebRTC/WebGL blocks). |
+| `page`      | goto / reload / back / forward; new / close / switch / list / info; snap (annotated screenshot + element index); screenshot / pdf / metrics / console; wait-{selector, text, function, url, idle, request, response}; trace start/stop. |
+| `dom`       | click / type / press / hover / select / check / scroll / upload / text / html / query — all locator-grammar aware. |
+| `frame`     | list / info / switch / reset — every primitive after `frame switch` runs inside the iframe. Shadow DOM is pierced automatically by Playwright locators. |
+| `network`   | query / block / unblock / mock / unmock / offline / cache-clear / export / set-extra-headers / execute (replay a captured request via httpx with the live cookies). |
+| `cookies`, `storage`, `storage idb`, `clipboard` | full CRUD on cookies, localStorage / sessionStorage, IndexedDB, and the page clipboard. |
+| `auth`      | interactive (block while operator logs in, snapshot `storage_state`); list / status / delete; replay via `--auth-profile` on subsequent sessions. |
+| `context`   | list / new / switch / close — multiple isolated cookie/storage worlds inside one browser. |
+| `mouse`, `keyboard` | coordinate-based mouse + per-key keyboard control. |
+| `dialog`, `download`, `eval` | handle native dialogs, wait for downloads, evaluate JS in the page. |
+| `worker`, `coverage` | service / dedicated worker control; JS+CSS coverage (chromium only). |
+| `observe`, `batch` | snap-act-snap-diff helper; multi-step RPC chains in one daemon dispatch. |
+| `daemon`    | start / stop / status. |
+
+Full agent-facing reference: [`AGENTS.md`](./AGENTS.md). A drop-in skill for
+Claude Code lives at [`.claude/skills/loom-browser-harness/SKILL.md`](./.claude/skills/loom-browser-harness/SKILL.md).
+
+## Live dashboard
+
+```bash
+loom dashboard [-s SESSION] [--port 9876]
+```
+
+Spins up a single-page web viewer at `http://127.0.0.1:9876/` showing a
+live screenshot of the active page plus a scrolling timeline of every
+RPC the daemon dispatches. Useful for demos and for watching long
+autonomous runs from the browser instead of the CLI.
+
+The same data is also available as a raw stream:
+
+```bash
+loom events tail [-s SESSION] [--frames] [--save DIR]
+```
+
+`--frames` opts in to base64 JPEG captures (~5fps per session, gated on
+subscriber demand). `--save DIR` drops each frame to disk for replay.
+
+## MCP
+
+```bash
+loom mcp                       # stdio transport — point any MCP client at this command
+```
+
+Each RPC method is auto-exposed as one MCP tool with a JSON Schema derived
+from its Python type hints. State is shared with the CLI through the daemon,
+so an agent can mix MCP tool calls with shell `loom …` invocations freely.
+
+## Layout
+
+```
+src/loom/
+  browser.py             browser.open / close / list, engine launching
+  pages.py               page.* primitives
+  dom.py                 dom.* primitives
+  snap.py                page.snap — annotated screenshot + element index
+  locators.py            semantic locator grammar (testid:, role:, text:, …)
+  frames.py              frame.* primitives
+  network/               capture sink, route mocking, replay, waits
+  auth.py                auth profile lifecycle
+  contexts.py            multi-context per session
+  observe.py             snap-act-snap-diff helper
+  batch.py               multi-step RPC chains
+  daemon/                loomd: server, per-session worker pool, connection cache
+  rpc/                   JSON-RPC codec + method registry
+  mcp/                   stdio MCP server, schema generator
+  cli/                   Typer entry points (one module per namespace)
+  client.py              CLI ↔ daemon Unix-socket client (auto-spawn)
+  session.py             session file CRUD (fcntl-locked updates)
+  paths.py               ~/.loom layout (LOOM_HOME override)
+  errors.py              structured error codes
+```
+
+## Development
+
+```bash
+git clone https://github.com/tomtom103/loom
+cd loom
+make install        # uv sync
+make lint           # ruff check
+make type-check     # mypy --strict
+make test           # pytest (mocked, fast)
+make test-all       # add the integration tests (real browsers)
+```
+
+Requirements: Python 3.12+, [uv](https://docs.astral.sh/uv/) for the dev
+setup, and one of the supported browser engines installed.
+
+## Files Loom owns
+
+```
+~/.loom/loomd.sock              daemon Unix socket
+~/.loom/loomd.pid               daemon pidfile (flock-guarded)
+~/.loom/loomd.log               daemon log
+~/.loom/sessions/<name>.json    session state (engine, ws_url, tabs, contexts, ...)
+~/.loom/captures/<name>/        per-session network + console capture
+~/.loom/downloads/<name>/       files saved via the page's download flow
+~/.loom/profiles/<name>/        saved auth profiles (storage_state.json)
+```
+
+Override the root with `LOOM_HOME`.
+
+## Opting out of the daemon
+
+```bash
+loom --no-daemon page goto https://example.com       # in-process
+LOOM_NO_DAEMON=1 loom page goto https://example.com  # same, env-scoped
+```
+
+Useful for tests, debugging, or scripts that don't want a daemon on disk.
+You lose persistence between calls — the browser disconnects when the CLI
+returns — but every primitive still works.
+
+## Releases
+
+See [CHANGELOG.md](./CHANGELOG.md) for the history of public changes.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

loom_harness-0.1.0/README.md

@@ -0,0 +1,191 @@
+# Loom
+
+**Stealth browser harness for autonomous LLM agents.**
+
+Loom gives an agent a fast, observable handle on a real browser — open a tab,
+click things, read the DOM, watch the network, run JS, replay APIs, persist
+auth — exposed three ways:
+
+- A CLI: `loom <namespace> <verb>` (JSONL output, scriptable, debuggable).
+- A long-lived JSON-RPC daemon: `loomd` (Unix socket at `~/.loom/loomd.sock`,
+  auto-spawned on the first command).
+- An MCP server: `loom mcp` (stdio transport, ~50 tools auto-derived from the
+  RPC registry).
+
+All three share the same daemon, so a session opened from the CLI is drivable
+from MCP and vice versa.
+
+The default engine is **[Camoufox](https://github.com/daijro/camoufox)**, a
+stealth-patched Firefox build with BrowserForge fingerprints. Chromium,
+Firefox, and WebKit are also supported by passing `--engine`.
+
+## Why
+
+Agent automation against real websites is a pile of small problems: bot
+detection, flaky locators, capturing network traffic, persisting login state,
+juggling multi-tab work, snapshotting state for the model to reason over.
+Loom packages those into one fast, predictable harness so the agent can spend
+its tokens on the actual task.
+
+## Status
+
+Beta. ~625 unit tests, 81% line coverage. The public RPC surface is stable;
+internal layout still moves between releases.
+
+## Install
+
+```bash
+pip install loom-harness
+playwright install firefox     # for chromium/firefox/webkit engines
+camoufox fetch                 # for the camoufox stealth engine
+```
+
+On headless Linux, Loom can run any engine **headed** against a virtual
+display for better stealth. Install Xvfb once:
+
+```bash
+sudo apt-get install xvfb      # Debian/Ubuntu
+```
+
+Loom auto-detects Xvfb on `PATH` and uses it when `--display auto` is set
+(the default).
+
+## Quickstart
+
+```bash
+# Daemon starts itself the first time the CLI talks to it.
+loom browser open --session s1 --display virtual --viewport 1280x720
+loom page goto https://example.com -s s1
+loom page snap -s s1 --max 30 | jq '.elements[0:5]'
+loom dom click 'role:link[name="More information..."]' -s s1
+loom page info -s s1
+loom browser close -s s1
+```
+
+`page snap` is the agent's primary "look" call — one payload combining a
+screenshot, an element index, and stable, semantic locator strings (the same
+grammar accepted by `dom.click`, `dom.type`, etc).
+
+## What's in the box
+
+| Namespace   | Highlights |
+|-------------|------------|
+| `browser`   | open / close / list; multi-engine (camoufox \| chromium \| firefox \| webkit); persistent profiles; emulation knobs (viewport, locale, timezone, geolocation, color scheme, proxy, UA); Camoufox stealth knobs (OS fingerprint, geoip, humanize, WebRTC/WebGL blocks). |
+| `page`      | goto / reload / back / forward; new / close / switch / list / info; snap (annotated screenshot + element index); screenshot / pdf / metrics / console; wait-{selector, text, function, url, idle, request, response}; trace start/stop. |
+| `dom`       | click / type / press / hover / select / check / scroll / upload / text / html / query — all locator-grammar aware. |
+| `frame`     | list / info / switch / reset — every primitive after `frame switch` runs inside the iframe. Shadow DOM is pierced automatically by Playwright locators. |
+| `network`   | query / block / unblock / mock / unmock / offline / cache-clear / export / set-extra-headers / execute (replay a captured request via httpx with the live cookies). |
+| `cookies`, `storage`, `storage idb`, `clipboard` | full CRUD on cookies, localStorage / sessionStorage, IndexedDB, and the page clipboard. |
+| `auth`      | interactive (block while operator logs in, snapshot `storage_state`); list / status / delete; replay via `--auth-profile` on subsequent sessions. |
+| `context`   | list / new / switch / close — multiple isolated cookie/storage worlds inside one browser. |
+| `mouse`, `keyboard` | coordinate-based mouse + per-key keyboard control. |
+| `dialog`, `download`, `eval` | handle native dialogs, wait for downloads, evaluate JS in the page. |
+| `worker`, `coverage` | service / dedicated worker control; JS+CSS coverage (chromium only). |
+| `observe`, `batch` | snap-act-snap-diff helper; multi-step RPC chains in one daemon dispatch. |
+| `daemon`    | start / stop / status. |
+
+Full agent-facing reference: [`AGENTS.md`](./AGENTS.md). A drop-in skill for
+Claude Code lives at [`.claude/skills/loom-browser-harness/SKILL.md`](./.claude/skills/loom-browser-harness/SKILL.md).
+
+## Live dashboard
+
+```bash
+loom dashboard [-s SESSION] [--port 9876]
+```
+
+Spins up a single-page web viewer at `http://127.0.0.1:9876/` showing a
+live screenshot of the active page plus a scrolling timeline of every
+RPC the daemon dispatches. Useful for demos and for watching long
+autonomous runs from the browser instead of the CLI.
+
+The same data is also available as a raw stream:
+
+```bash
+loom events tail [-s SESSION] [--frames] [--save DIR]
+```
+
+`--frames` opts in to base64 JPEG captures (~5fps per session, gated on
+subscriber demand). `--save DIR` drops each frame to disk for replay.
+
+## MCP
+
+```bash
+loom mcp                       # stdio transport — point any MCP client at this command
+```
+
+Each RPC method is auto-exposed as one MCP tool with a JSON Schema derived
+from its Python type hints. State is shared with the CLI through the daemon,
+so an agent can mix MCP tool calls with shell `loom …` invocations freely.
+
+## Layout
+
+```
+src/loom/
+  browser.py             browser.open / close / list, engine launching
+  pages.py               page.* primitives
+  dom.py                 dom.* primitives
+  snap.py                page.snap — annotated screenshot + element index
+  locators.py            semantic locator grammar (testid:, role:, text:, …)
+  frames.py              frame.* primitives
+  network/               capture sink, route mocking, replay, waits
+  auth.py                auth profile lifecycle
+  contexts.py            multi-context per session
+  observe.py             snap-act-snap-diff helper
+  batch.py               multi-step RPC chains
+  daemon/                loomd: server, per-session worker pool, connection cache
+  rpc/                   JSON-RPC codec + method registry
+  mcp/                   stdio MCP server, schema generator
+  cli/                   Typer entry points (one module per namespace)
+  client.py              CLI ↔ daemon Unix-socket client (auto-spawn)
+  session.py             session file CRUD (fcntl-locked updates)
+  paths.py               ~/.loom layout (LOOM_HOME override)
+  errors.py              structured error codes
+```
+
+## Development
+
+```bash
+git clone https://github.com/tomtom103/loom
+cd loom
+make install        # uv sync
+make lint           # ruff check
+make type-check     # mypy --strict
+make test           # pytest (mocked, fast)
+make test-all       # add the integration tests (real browsers)
+```
+
+Requirements: Python 3.12+, [uv](https://docs.astral.sh/uv/) for the dev
+setup, and one of the supported browser engines installed.
+
+## Files Loom owns
+
+```
+~/.loom/loomd.sock              daemon Unix socket
+~/.loom/loomd.pid               daemon pidfile (flock-guarded)
+~/.loom/loomd.log               daemon log
+~/.loom/sessions/<name>.json    session state (engine, ws_url, tabs, contexts, ...)
+~/.loom/captures/<name>/        per-session network + console capture
+~/.loom/downloads/<name>/       files saved via the page's download flow
+~/.loom/profiles/<name>/        saved auth profiles (storage_state.json)
+```
+
+Override the root with `LOOM_HOME`.
+
+## Opting out of the daemon
+
+```bash
+loom --no-daemon page goto https://example.com       # in-process
+LOOM_NO_DAEMON=1 loom page goto https://example.com  # same, env-scoped
+```
+
+Useful for tests, debugging, or scripts that don't want a daemon on disk.
+You lose persistence between calls — the browser disconnects when the CLI
+returns — but every primitive still works.
+
+## Releases
+
+See [CHANGELOG.md](./CHANGELOG.md) for the history of public changes.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

loom_harness-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "loom-harness"
+version = "0.1.0"
+description = "Stealth browser harness for autonomous LLM agents — Camoufox/Playwright wrapped behind a CLI, JSON-RPC daemon, and MCP server."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Thomas Caron", email = "thomas.caron00@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = [
+    "browser",
+    "automation",
+    "playwright",
+    "camoufox",
+    "agent",
+    "llm",
+    "mcp",
+    "scraping",
+    "stealth",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "playwright>=1.49",
+    "camoufox[geoip]>=0.4",
+    "pydantic>=2.9",
+    "pyyaml>=6.0",
+    "typer>=0.12",
+    "websockets>=12",
+    "anyio>=4",
+    "mcp>=1.0",
+    "httpx>=0.27",
+    "pillow>=10",
+    "orjson>=3.11.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/tomtom103/loom"
+Repository = "https://github.com/tomtom103/loom"
+Issues = "https://github.com/tomtom103/loom/issues"
+
+[project.scripts]
+loom = "loom.cli:main"
+
+[project.optional-dependencies]
+ocr = ["pytesseract>=0.3"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.11",
+    "mypy>=1.15",
+    "types-pyyaml>=6.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "loom"
+module-root = "src"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+# Inline HTML/CSS/JS for the dashboard ships as a single string — line-length
+# wrapping would corrupt the rendered output, so allow long lines here.
+"src/loom/cli/dashboard.py" = ["E501"]
+"tests/test_dashboard.py" = ["E501"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Option", "typer.Argument"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["pytesseract"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "integration: tests that launch a real browser (slow; opt-in).",
+]

loom_harness-0.1.0/src/loom/__init__.py

@@ -0,0 +1,5 @@
+"""Loom — browser automation toolkit for agents and scheduled scrapers."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

loom_harness-0.1.0/src/loom/__main__.py

@@ -0,0 +1,4 @@
+from loom.cli import main
+
+if __name__ == "__main__":
+    main()