2.3 KiB
Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
- Executive Summary
- 1. Architectural Strategy: The I/O Bridge
- 2. Environment & Dependency Management
- 3. Cognitive Tooling
- 4. PSF Mandate Alignment
- 5. Permanent Learnings
Executive Summary
Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `org-agent` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
1. Architectural Strategy: The I/O Bridge
Problem
Common Lisp lacks a mature, native Playwright implementation. Direct bindings are complex and fragile.
Resolution
Implemented a JSON-over-STDIO Bridge.
- A standalone Python script (`browser-bridge.py`) manages the Playwright lifecycle and Chromium instance.
- The Lisp kernel communicates with this script using `uiop:run-program`, passing parameters via `stdin` and receiving structured results via `stdout`. This provides a stable, decoupled interface.
2. Environment & Dependency Management
Issue
Playwright requires a specific version of Chromium and several system-level libraries not present in the base Debian image.
Resolution
Updated the `Dockerfile` to:
- Install Python3, pip, and venv.
- Create a virtual environment for isolated dependency management.
- Install the `playwright` package and execute `playwright install –with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.
3. Cognitive Tooling
Created the `:browser` cognitive tool, which exposes three primary capabilities to Probabilistic Engine:
- Navigation: Full JS rendering and waiting for network idle.
- Extraction: Targeted text retrieval via CSS selectors.
- Vision: Base64-encoded screenshot capture for future multimodal processing.
4. PSF Mandate Alignment
Zero-Bloat (Managed)
While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
Literate Granularity
The `org-skill-playwright.org` file strictly follows the "one definition per block" mandate.
5. Permanent Learnings
- Inter-Process JSON: JSON is the ideal lingua franca for Lisp-Python bridges.
- Path Portability: Always use `uiop:native-namestring` when passing Lisp paths to external shell commands to ensure OS compatibility.