🚀 WebPilot Engine v2.5.0
Enterprise Autonomous Browser Engine, Universal Form Inspector & AI Agent Web Runtime
WebPilot Engine is a high-performance, enterprise-grade autonomous browser engine and AI agent web runtime designed to inspect, interact with, populate, and operate complex modern web applications, single-page apps (SPAs), dynamic Shadow DOMs, and enterprise ATS/ERP widgets (Workday, SAP SuccessFactors, Taleo, Oracle Cloud, custom modal flows) with zero site-specific selectors or hardcoded scripts.
🏛️ 3-Tier Zero-Elevation Multi-Process Architecture
To overcome the fundamental operating system limitation where terminal runners and subshells terminate background browser child processes upon command completion (such as the Windows Job Object JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE), WebPilot implements a hardened Zero-Elevation Three-Tier Process Architecture:
┌────────────────────────────────────────────────────────────────────────┐
│ WebPilot CLI & REPL Shell (webpilot / wp) │
└───────────────────────────────────┬────────────────────────────────────┘
│ HTTP REST (127.0.0.1:9333)
▼
┌────────────────────────────────────────────────────────────────────────┐
│ Layer 1: Master Supervisor Host (Daemon) │
│ • Ultra-Lightweight IPC Controller (~15 MB RAM) │
│ • Zero Playwright Imports (Starts instantaneously) │
│ • 30-Minute Inactivity Watchdog Sentinel (Automatic RAM release) │
│ • Detached Background Auto-Spawn via Windows WMI / POSIX double-fork │
└───────────────────────────────────┬────────────────────────────────────┘
│ stdin / stdout (Isolated JSON-RPC)
▼
┌────────────────────────────────────────────────────────────────────────┐
│ Layer 2: Operational Worker Process │
│ • Playwright Runtime + SessionCoordinator │
│ • Persistent in-memory browser session maintained across CLI calls │
│ • Decoupled DOM Services (Field, Auth, Reactive, Inspection) │
│ • Multi-Stage Verification Barrier & Dynamic Section Expander │
└───────────────────────────────────┬────────────────────────────────────┘
│ Process Tree Attachment
▼
┌────────────────────────────────────────────────────────────────────────┐
│ Layer 3: Chromium Browser Engine │
│ • Chromium Main Process + GPU Process + Sandboxed Renderers │
│ • Deterministic Cascading Termination (Zero Zombie Leaks) │
└────────────────────────────────────────────────────────────────────────┘
⚡ Architectural Pillars:
- Persistent Browser Session Across Disconnected CLI Invocations: Execute multi-step sequential interactions (
open➔fill profile➔upload resume➔press submit) without closing the browser, losing session state, or re-authenticating. - Zero Administrative Elevation (Standard User): Operates 100% in unprivileged standard user space. Zero Administrator / UAC escalation required.
- Deterministic Cascading Termination & Auto-Healing: Terminating Layer 2 instantly tears down the entire Chromium process tree with zero zombie process leaks. Layer 1 automatically auto-spawns a fresh Layer 2 worker in ~300ms.
- Memory Watchdog Sentinel: Automatically reclaims all browser resources and cleanly exits after 30 minutes of idle inactivity.
🐍 Python SDK: Programmatic AI Agent Usage
WebPilot provides a first-class, ergonomic Python SDK for AI agents, automation pipelines, and Python applications via import webpilot:
from webpilot import WebPilot
# Connects to background supervisor automatically (or auto-spawns detached host)
with WebPilot() as wp:
# 1. Inspect Form Schema (returns JSON dictionary of inputs, dropdowns, buttons)
schema = wp.inspect("https://careers.example.com/apply")
# 2. Fill Fields with 0.0% False Success Physical Truth Verification
result = wp.apply(
url="https://careers.example.com/apply",
fields={
"First Name": "Alice",
"Last Name": "Nakamura",
"Email": "alice@example.com",
"Degree": "Master's",
"Authorized to work": "Yes"
},
press="Submit Application"
)
if result.success:
print(f"Application confirmed! Confirmed fields: {len(result.confirmed_fields)}")
else:
print(f"Application failed verification: {result.unconfirmed_fields}")
# 3. Probe Specific Element or Dropdown Options
probe = wp.find("Country", options=True)
print("Available options:", probe.output_lines)
# 4. Multi-Tab Session Management
tabs = wp.list_tabs()
wp.switch_tab(0)
⚡ The Performance Breakthrough (9x Native Speedup)
In version 2.0.11 and 2.0.12, WebPilot underwent a comprehensive timing and latency overhaul, transitioning from legacy synthetic delays to reactive, event-driven DOM readiness:
- Elimination of Artificial Pauses: Replaced blind 3,000ms pauses (
PAUSE_DOM_CONTENT_LOADED_MS,PAUSE_REACTIVE_STABILIZE_MS) with deterministic condition checking and DOM event listeners. - Bounded Actionability Timeouts: Added strict 1,000ms locator timeouts to prevent Playwright from hanging for 30 seconds on non-actionable or overlayed buttons (e.g. S10 overlay trap).
- Conditional Accordion Expansion: Section expansions only wait if closed accordions were actually detected and opened.
📊 Benchmark Execution Latency Comparison:
| Benchmark Metric | Legacy / Pre-v2.0.11 | WebPilot v2.0.12 | Performance Gain |
|---|---|---|---|
| Full 50-Scenario Test Suite | 519.9 seconds (~8.6 mins) | 58.58 seconds | 8.9x Faster (-88.7%) |
| Average Latency Per Form | 10.40 seconds | 1.172 seconds | Native Playwright Speed |
| Fastest Scenario Execution | ~4.20 seconds | 0.68 seconds | 6.2x Faster |
🛡️ The Truth Barrier: 0.0% False Success Guarantee
A major vulnerability in AI browser agents and web automation frameworks is False Success (Silent Failure): claiming an operation succeeded when inputs were silently rejected, cleared by reactive JavaScript, or blocked by invisible validation errors.
WebPilot enforces a strict Multi-Stage Physical Truth Verification Pipeline:
[Fill Attempt] ➔ [1. Inline DOM Re-read] ➔ [2. Pre-Submit Verification Barrier] ➔ [Button Click / Submit] ➔ [3. Post-Interaction Verification Barrier]
- Inline DOM Re-read (
verify_field_value): Immediately reads the physical DOM property after setting an input to confirm that the value took effect. - Pre-Submit Verification Barrier (
_reverify_fields): Re-checks all previously confirmed fields right before triggering submit buttons to catch delayed resets. - Post-Interaction Verification Barrier: Re-verifies all fields after button clicks to detect adversarial scripts or form handlers that clear or revert values upon clicking (e.g. S29, S44).
- Dynamic Repeating Section Expansion (
expand_dynamic_section): Automatically identifies and clicks dynamic repeater triggers (Add,Add another,+) when target fields do not yet exist in the DOM (e.g. S27). - Categorized Telemetry Accounting: Categorizes every field deterministically as
confirmed,unconfirmed, orfailed. If even a single field is unconfirmed, WebPilot reports operation failure rather than making speculative success claims.
🧹 Clean Architecture & SOLID Engineering (v2.5.0)
Following an extensive project-wide architectural refactoring milestone, the codebase adheres to strict enterprise software standards:
- Strict Multi-Tier Layering & Separation of Concerns:
- Presentation Layer: CLI Dispatcher (
cli.py), Modular Subcommands (cli_commands/), Modular CLI Parser (cli_parser.py), MCP Server (mcp_server.py), MCP Tool Dispatchers (mcp_tools.py), REPL Shell (supervisor/shell.py), Telemetry (common/telemetry.py). - Orchestration & Supervision: Master Daemon (
master_daemon.py), HTTP Handler (supervisor/handler.py), Inactivity Watchdog (supervisor/watchdog.py), Worker Daemon (supervisor/worker_process.py), Worker Execution Handlers (supervisor/worker_handlers.py), Pipeline Orchestration (flow_orchestrator.py). - Domain Services: Field Interactions (
FieldInteractionService), Form Application Pipeline (FormApplicationPipeline), Target Descriptor Parser (TargetDescriptorParser), DOM Data Matcher (DOMDataMatcher), Schema Merger (SchemaMerger), Inspection (InspectionService), Reactive Interactions (ReactiveInteractionService), Page Lifecycle (PageLifecycleService). - Infrastructure & Adapters: Browser Adapter (
BrowserAdapter), Tab & Window Manager (TabManager), Playwright Fallbacks (PlaywrightLocatorFallback).
- Presentation Layer: CLI Dispatcher (
- Modular DOM Script Engine (
adapters/dom/):- Decomposed legacy 1,000+ line monolithic scripts into focused, single-responsibility modules:
lifecycle.py,navigation.py,set_field.py,picklist.py,verify.py,inspection.py,probe.py,reactive.py.
- Decomposed legacy 1,000+ line monolithic scripts into focused, single-responsibility modules:
- Universal Page Lifecycle Paradigm:
- Eliminated bespoke auth hacks; all portals and login pages are managed uniformly through event-driven DOM readiness and accordion expansion in
PageLifecycleService.
- Eliminated bespoke auth hacks; all portals and login pages are managed uniformly through event-driven DOM readiness and accordion expansion in
- Tab & Multi-Window Isolation:
- Fully abstracted browser context, tab lifecycle, popup tracking, and route interception into
TabManager.
- Fully abstracted browser context, tab lifecycle, popup tracking, and route interception into
- DRY Consolidation & Single Source of Truth:
- Pipeline phases consolidated in
FormApplicationPipelinewith deterministic 3-stage physical truth verification. - Eliminated circular imports and inline imports in compliance with PEP 8.
- Pipeline phases consolidated in
🔬 Empirical Adversarial Benchmark Suite (50 Scenarios)
The repository includes a complete, fully reproducible 50-Scenario Adversarial Benchmark Suite under eval/ containing real-world edge cases, anti-automation traps, and complex widget patterns:
Certified Evaluation Results (v2.0.12 on Linux Cloud VPS):
| Benchmark Metric | Result / Score | Certification Note |
|---|---|---|
| Total Scenarios Evaluated | 50 Scenarios | Full comprehensive suite |
| Solvable Form Pass Rate | 47 / 47 (100.0%) | 100% of solvable forms completed |
| Total Form Pass Rate | 47 / 50 (94.0%) | 3 remaining are unsolvable traps (S02, S06, S22) |
| False Success Rate | 0.0% (0 / 50) | Zero False Claims |
| Field Accuracy | 159 / 161 (98.76%) | Accurate physical DOM value binding |
| Total Suite Wall Clock Time | 58.58 seconds | Sub-60-second full suite execution |
| Average Time Per Scenario | 1.172 seconds | Sub-1.5s per form average |
| Worker Crashes / Zombie Reaps | 0 (Zero) | 100% process stability |
Reproducing the Benchmark:
# 1. Start the local evaluation lab server
python eval/lab/server.py --port 8900 &
# 2. Run the monitored benchmark suite
python eval/scripts/run_suite.py --tool webpilot --wp wp --runs 1 --label v2012 --out-dir eval/results
The benchmark fixtures, expected JSON contracts, and in-depth analytical reports are accessible in:
eval/lab/scenarios.py— Definitions of all 50 test scenarios.eval/docs/REPORT.md— Comprehensive benchmark evaluation report.eval/docs/FALSE_SUCCESS_ANATOMY.md— Architectural breakdown of false success prevention.eval/docs/DEFECTS.md— Documented edge cases, trap analysis, and resolution history.
🚀 Quick Start Guide
Installation:
# Clone the repository
git clone https://github.com/AbdulkarimSSS/webpilot.git
cd webpilot
# Install in editable mode
pip install -e .
# Install Playwright browser binaries
playwright install chromium
You can use either the full webpilot command or the shortcut wp:
1. Inspect Any Web Page
Extract a token-optimized, clean schema of inputs, dropdowns, and buttons:
wp inspect --url "https://example.com/portal" --output "schema.json" --screenshot "page.png"
2. Autonomous Form Filling & Submission
Fill fields using JSON data payloads or inline flags:
# Using inline arguments
wp apply --url "https://example.com/login" \
--fill "username=demo@example.com" \
--fill "password=MySecurePassword123!" \
--press "Sign In" \
--submit
# Using JSON payload file
wp apply --url "https://example.com/job-application" \
--data "applicant_data.json" \
--press "Submit Application"
3. Step-by-Step Multi-Turn Execution
Commands run sequentially against the same active persistent browser session:
# Step 1: Open target portal
wp apply --url "https://example.com/register"
# Step 2: Fill personal details
wp apply --fill "first_name=John" --fill "last_name=Doe"
# Step 3: Fill contact info
wp apply --fill "email=john.doe@example.com" --fill "phone=+1234567890"
# Step 4: Click Next, detect dynamic expansion, and complete registration
wp apply --press "Next" --submit --screenshot "complete.png"
4. Interactive REPL Shell
Launch the sub-second interactive automation shell:
wp shell
webpilot> open https://example.com/login
webpilot> fill username=john.doe@example.com
webpilot> fill password=MyPassword123!
webpilot> press Sign In
webpilot> tabs
webpilot> screenshot dashboard.png
webpilot> exit
5. Supervisor Service Management
wp service status # View real-time PID telemetry for Layer 1, Layer 2, and Layer 3
wp service restart # Cascading kill of Layer 2 & 3, auto-respawns in ~300ms
wp service stop # Cleanly terminate all processes and reclaim 100% of memory
🧪 Unit Testing & Verification
WebPilot includes a comprehensive test suite covering IPC wire contracts, supervisor lifecycle, redaction, and DOM interaction services:
pytest tests/
All 58 unit tests execute in < 28 seconds:
tests/test_contracts.py ....... [ 12%]
tests/test_engine_facade.py ..... [ 20%]
tests/test_live_session.py ... [ 25%]
tests/test_orchestration.py ...... [ 36%]
tests/test_redaction.py ........ [ 50%]
tests/test_services.py .............. [ 74%]
tests/test_supervisor.py ................ [100%]
============================== 58 passed in 27.42s ==============================
🔒 Security & Privacy
- Automatic Credential Redaction: Passwords, API tokens, and sensitive inputs are automatically masked as
***REDACTED***in CLI output, logs, and telemetry cards. - Standard User Security: Requires zero Administrator / root permissions; never triggers UAC prompts or elevates tokens.
- Local Loopback Isolation: The Master Supervisor listens strictly on
127.0.0.1:9333.
📄 License
This project is licensed under the MIT License — free for commercial, research, and personal use.
Metadata
Release files for webpilot-engine 2.7.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| webpilot_engine-2.7.5.tar.gz | 277.6 kB | Without provenance | Details for webpilot_engine-2.7.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| webpilot_engine-2.7.5-py3-none-any.whl | Python 3 | none | any | Details for webpilot_engine-2.7.5-py3-none-any.whl |
Total release size: 532.6 kB
Release files / webpilot_engine-2.7.5.tar.gz
| Download URL | webpilot_engine-2.7.5.tar.gz |
|---|---|
| Size | 277.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6ba02be3afc03d36b7fc32f7a6f26ca3566f273c9832623391b0aa3f1a924123
|
|
BLAKE2b-256 checksum How to use checksums |
f323fda6db59f8232809f82cca85a644185191895ab34b864d8b83439409c06f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / webpilot_engine-2.7.5-py3-none-any.whl
| Download URL | webpilot_engine-2.7.5-py3-none-any.whl |
|---|---|
| Size | 255.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
148b9f4bf53eb3387e18a5e0adeb7211523a80da78fe08d1a8d49d626b8bc1ab
|
|
BLAKE2b-256 checksum How to use checksums |
ef91cf06cca233e336386dfd55cdcb12a6ce4be5bd03432197dbf537610a47ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for webpilot-engine 2.7.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.