easyclaw 0.1.0__tar.gz

easyclaw-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v --tb=short

easyclaw-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read   # checkout private repo
+      id-token: write  # trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

easyclaw-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# EasyClaw runtime
+*.log
+*.pid
+*.db
+
+# Secrets — never commit
+*.key
+*.pem
+GitHub Token.txt
+OpenRouter API Key.txt
+
+# Pytest
+.pytest_cache/
+
+# MCP server data
+mcp-server/data/
+mcp-server/tokens.json

easyclaw-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to EasyClaw will be documented in this file.
+
+## [0.1.0] - 2026-03-30
+
+### Added
+- **Phase 0 — Foundation:** asyncio daemon, heartbeat, CLI (`start|stop|status|doctor`), auto-discovery, systemd/launchd service templates, `curl|bash` installer
+- **Phase 1 — The Doctor:** real-time log tailing (file + journalctl), 13 built-in classification rules, alert pipeline with 5-min dedup, webhook notifications
+- **Phase 2 — Self-Healing:** 11 built-in remediations, sandboxed command executor, OpenClaw restart manager, JSONL fix ledger, circuit breaker (3 restarts / 10 min)
+- **Phase 3 — MCP Client:** HTTP client for proprietary MCP knowledge server (17 tools, 29+ articles), retry/backoff/cache, incident reporting, periodic update polling
+- **Phase 4 — Personal Trainer:** context monitor (home dir size tracking), temp file cleaner, dependency auditor, environment validator (API keys, connectivity), CPU/RAM trend tracking with OOM projection
+- **Phase 5 — Hardening:** security sandbox (command validation, path restrictions), resource capping (nice + systemd limits), async HTTP status dashboard on `localhost:18790`, KPI tracker (MTTR, uptime, auto-fix rate)
+- **Phase 6 — Agent Brain:** LLM-powered reasoning loop via OpenRouter (GLM-4.7-Flash), 10 tools (4 local + 6 MCP), event-triggered with 10s batch window and 30s cooldown, graceful fallback to rules-based healer
+- **Phase 7 — Telegram Bot:** two-way conversational interface via python-telegram-bot, `/status` `/logs` `/stats` `/help` commands, CRITICAL alert forwarding with 10-min dedup, chat authorization
+- **MCP Server v2:** 17 tools, SQLite + FTS5 backend, 25+ seed articles, 20+ AI model catalog, 25+ error diagnostic patterns, 7 config templates, security audit checklists, n8n auto-update workflow (6h interval)

easyclaw-0.1.0/CLAUDE.md

@@ -0,0 +1,322 @@
+# EasyClaw 2.0
+
+## What It Is
+EasyClaw is a **commercial subscription product** — an autonomous "doctor and personal trainer" sidecar for OpenClaw agents. It monitors, diagnoses, self-heals, and optimizes OpenClaw instances without user intervention. Sold via `easyclaw.help`.
+
+## Current State — Phase 8 In Progress (2026-03-30)
+- **Version:** 0.1.0
+- **Runtime:** Python 3.10+ asyncio daemon with 16 concurrent subsystems
+- **Agent Brain:** GLM-4.7-Flash via OpenRouter — LLM-powered reasoning loop (Phase 6)
+- **Telegram Bot:** Full conversational two-way communication via python-telegram-bot (Phase 7)
+- **Package:** pip-installable via hatchling (`pyproject.toml`)
+- **MCP Server:** Deployed to VPS at `http://31.220.49.171:8002` — 17 tools, 29+ articles, 19 models
+- **n8n Workflow:** "EasyClaw Knowledge Updater" (ID: Bn29wDCN97tZRfiK) — auto-ingests from GitHub, HuggingFace, arXiv, Reddit, SearXNG every 6h
+- **Dev venv:** `~/.easyclaw/venv/` in WSL2 (editable install from OneDrive source)
+- **Test Suite:** 170 tests across 8 test files (classifier, sandbox, ledger, KPI, alerts, remediation, agent, telegram)
+- **CI/CD:** GitHub Actions for test matrix (3.10/3.11/3.12) + PyPI trusted publishing
+- **All 7 build phases complete** — Phase 8 distribution prep in progress
+
+## Architecture
+
+```
+src/easyclaw/
+├── __init__.py          # version (0.1.0)
+├── __main__.py          # python -m easyclaw entry point
+├── cli.py               # CLI: easyclaw start|stop|status|doctor
+├── config.py            # loads ~/.easyclaw/config.yaml + discovers OpenClaw env
+├── agent.py             # Phase 6: LLM agent brain (OpenRouter, tool calling, event reasoning)
+├── telegram.py          # Phase 7: Telegram bot bridge (inbound chat + outbound alerts)
+├── daemon.py            # asyncio event loop, orchestrates all subsystems (Phases 1-7)
+├── discovery.py         # auto-discovers OpenClaw install (paths, PID, service, binary)
+├── logging.py           # JSON file logs + colored console output
+├── tailer.py            # async log tailing (file + journalctl) with LogAggregator
+├── classifier.py        # rules-based event classification (13 built-in patterns)
+├── alerts.py            # event queue, dedup filter, alert log, webhook notifications
+├── health.py            # process health monitor (PID, CPU/RAM, stall, session bloat)
+├── remediation.py       # remediation registry (11 built-in entries + user YAML overrides)
+├── executor.py          # sandboxed command execution (timeout, output cap, no stdin)
+├── restart.py           # OpenClaw restart manager (systemctl/SIGTERM/SIGKILL lifecycle)
+├── ledger.py            # fix ledger (JSONL audit trail) + circuit breaker
+├── healer.py            # orchestrator: events → registry → MCP fallback → execute → ledger
+├── mcp_client.py        # HTTP client for proprietary MCP server (retry, backoff, cache)
+├── updater.py           # periodic MCP polling for updates and hotfixes
+├── context_monitor.py   # Phase 4: OpenClaw home dir size/growth tracking
+├── temp_cleaner.py      # Phase 4: stale temp file cleanup + log rotation/gzip
+├── dep_auditor.py       # Phase 4: dependency version audit (psutil, pyyaml, aiofiles)
+├── env_validator.py     # Phase 4: API key + MCP + gateway connectivity checks
+├── resource_monitor.py  # Phase 4: CPU/RAM trend tracking + OOM projection
+├── dashboard.py         # Phase 5: async HTTP status dashboard (127.0.0.1:18790)
+├── kpi.py               # Phase 5: KPI tracker (MTTR, uptime, auto-fix rate, intervention rate)
+├── sandbox.py           # Phase 5: security sandbox (command validation, path restrictions)
+├── capping.py           # Phase 5: resource capping (nice, self-monitoring, systemd unit gen)
+└── templates/
+    └── easyclaw.service # systemd user service template
+
+mcp-server/                      # Deployable to Hostinger VPS (port 8002)
+├── server.py                # FastMCP server v2 (17 tools — knowledge hub)
+├── db.py                    # SQLite + FTS5 full-text search database layer
+├── models_catalog.py        # 20+ AI model catalog with pricing & recommendations
+├── error_patterns.py        # 25+ regex-based error diagnostic patterns
+├── config_templates.py      # 7 config templates + 20 validation checks + gateway config gen
+├── checklists.py            # 14 security audit checks + deployment validation (linux/macos/wsl2) + gateway troubleshooting
+├── seed_knowledge.py        # Seeds database with 25+ comprehensive articles on first run
+├── n8n-knowledge-updater.json  # n8n workflow: auto-updates KB from GitHub, HuggingFace, arXiv, Reddit, SearXNG every 6h
+├── requirements.txt         # mcp[cli], uvicorn
+├── Dockerfile
+├── tokens.json              # Subscription token store (dev token: ec_dev_token_001)
+├── data/                    # SQLite database (auto-created)
+│   └── easyclaw_knowledge.db
+└── knowledge/               # Legacy markdown (imported into SQLite on first run)
+    ├── known-issues/        # connection-refused, heap-out-of-memory, dns-failure, session-bloat
+    └── docs/                # configuration reference
+```
+
+### Supporting Files (project root)
+- `pyproject.toml` — pip-installable package (hatchling build system)
+- `Dockerfile` — EasyClaw client sidecar container
+- `install.sh` — `curl | bash` installer for easyclaw.help
+- `README.md` — Basic usage docs
+- `EasyClaw 2.0 PRD.md` — Full product requirements document
+
+## Runtime Paths (on user's machine)
+- **Config:** `~/.easyclaw/config.yaml`
+- **Logs:** `~/.easyclaw/logs/easyclaw-YYYY-MM-DD.log` (JSON lines)
+- **Alerts:** `~/.easyclaw/logs/alerts.log` (JSON lines, classified events)
+- **State:** `~/.easyclaw/state/daemon.json`, `daemon.pid`, `fix-ledger.jsonl`
+- **User remediations:** `~/.easyclaw/remediations.yaml` (optional, extends built-in rules)
+
+## OpenClaw Discovery
+EasyClaw auto-discovers OpenClaw at runtime — no hardcoded paths. It checks:
+- `~/.openclaw/` directory (home_dir, config, sessions, workspace, cron)
+- `~/.openclaw_env` (API keys, env vars)
+- `/tmp/openclaw/` (log directory)
+- `which openclaw` + common npm global paths (binary)
+- `systemctl --user` for `openclaw-gateway` service
+- `psutil` process scan for running PID
+
+## Installation Methods
+1. **pip:** `pip install easyclaw` (PyPI — not yet published)
+2. **Docker:** `docker run` sidecar with volume mounts to host OpenClaw dirs
+3. **Installer:** `curl -sL easyclaw.help/install | bash` — detects OS, installs pip package, sets up systemd service
+
+## CLI Commands
+```bash
+easyclaw start            # start daemon (background)
+easyclaw start -f         # start in foreground
+easyclaw stop             # graceful SIGTERM shutdown
+easyclaw status           # show daemon + OpenClaw status
+easyclaw doctor           # run environment diagnostics (19 checks)
+```
+
+## Config (config.yaml defaults)
+```yaml
+heartbeat_interval: 30        # seconds
+health_check_interval: 60     # seconds
+log_retention_days: 7
+max_restart_attempts: 3       # circuit breaker
+restart_window: 600           # circuit breaker window (10 min)
+gateway_port: 18789
+alert_webhook: null           # n8n/Telegram webhook URL
+mcp_endpoint: null            # proprietary MCP server URL (e.g., http://31.220.49.171:8002)
+mcp_token: null               # MCP subscription token
+update_check_interval: 21600  # 6 hours (seconds)
+
+# Agent brain (Phase 6)
+openrouter_api_key: null      # OpenRouter API key for LLM agent brain
+openrouter_model: "z-ai/glm-4.7-flash"  # Model ID on OpenRouter
+agent_enabled: true           # enable/disable agent brain
+agent_batch_window: 10        # seconds to batch events before invoking agent
+agent_cooldown: 30            # minimum seconds between agent invocations
+agent_max_turns: 10           # max tool-call round trips per invocation
+agent_temperature: 0.1        # low for deterministic behavior
+
+# Telegram bot (Phase 7)
+telegram_bot_token: null      # bot token from @BotFather
+telegram_chat_ids: []         # authorized chat IDs (list of integers)
+telegram_alert_severity: "CRITICAL"  # minimum severity to push alerts
+```
+
+## Key Design Decisions
+- **AI agent architecture:** Copies OpenClaw's agent loop pattern — system prompt -> model call -> parse tool_calls -> execute -> loop
+- **LLM-powered reasoning:** GLM-4.7-Flash via OpenRouter reasons about problems, queries MCP knowledge base, generates and executes fixes
+- **Event-triggered:** Agent brain activates on events (not continuous), with 10s batch window and 30s cooldown — typical cost <$0.02/day
+- **Graceful fallback:** No API key or OpenRouter down -> degrades to rules-based healer automatically
+- **Failsafe contract:** Top-level try/except wraps entire daemon — EasyClaw can never crash OpenClaw
+- **No hardcoded paths:** Everything discovered dynamically for portability across customer installs
+- **Platform-aware:** Detects Linux, macOS, WSL2, systemd vs launchd vs none
+- **Resource-capped:** systemd service limits to 10% CPU, 256MB RAM
+- **Commercial product:** All architecture decisions account for multi-user distribution
+- **MCP is the brain's strength:** 17 tools, 29+ articles — the agent is lightweight, MCP does the heavy lifting
+
+## Dependencies
+```
+aiofiles>=24.1.0            # async file I/O (log tailing)
+pyyaml>=6.0                 # config file parsing
+psutil>=5.9                 # process monitoring
+python-telegram-bot>=21.0   # Telegram bot API (async-native)
+```
+
+## Build Phases (from PRD)
+- [x] **Phase 0** — Foundation: daemon loop, heartbeat, discovery, CLI, installer
+- [x] **Phase 1** — The Doctor: log tailing, error detection, event classification, alerts
+- [x] **Phase 2** — Self-Healing: remediation registry, command executor, restart manager, circuit breaker
+- [x] **Phase 3** — MCP Client: proprietary MCP server, knowledge retrieval, push-pull updates
+- [x] **Phase 4** — Personal Trainer: context monitor, temp cleaner, dependency audit, env validation, resource monitor
+- [x] **Phase 5** — Hardening: installer polish, resource capping, security sandbox, dashboard, KPIs
+- [x] **Phase 6** — Agent Brain: LLM reasoning loop via OpenRouter (GLM-4.7-Flash), tool calling, event-triggered with batching, fallback to rules-based healer
+- [x] **Phase 7** — Telegram Bot: full conversational two-way via python-telegram-bot, commands (/status /logs /stats), alert forwarding, LLM chat
+
+---
+
+## Session Handoff Notes — 2026-03-31 (Phase 8 — Test Coverage + Distribution Polish)
+
+### What Was Built This Session
+
+#### Test Suite Expansion (170 tests, all passing)
+- **`tests/test_agent.py`** — 43 tests: availability (4), event enqueue (4), tool definitions (5), event formatting (3), tool execution (11), chat interface (4), system prompt (4), fallback (2), history tracking (2), utilities (3), message cleaning (2)
+- **`tests/test_telegram.py`** — 19 tests: configuration (5), authorization (3), alert forwarding (6), message splitting (3), run method (2)
+
+#### Distribution Polish
+- **`install.sh`** — config template now includes all Phase 6+7 fields (agent brain, Telegram bot settings)
+- **`.github/workflows/publish.yml`** — now runs full test matrix (3.10/3.11/3.12) before publishing to PyPI (publish job `needs: test`)
+
+### What Still Needs Rick's Manual Action
+- [ ] Create GitHub repo (`easyclaw/easyclaw`) and push code
+- [ ] Configure PyPI trusted publishing (link GitHub repo to PyPI project)
+- [ ] Create Telegram bot via @BotFather, add token + chat ID to `~/.easyclaw/config.yaml`
+- [ ] Add OpenRouter API key to config.yaml for agent brain
+- [ ] Re-install editable package: `pip install -e ".[dev]"` (picks up new test files)
+- [ ] Run `easyclaw doctor` to verify all checks pass
+- [ ] Production smoke test: run daemon 24h with agent brain + Telegram active
+- [ ] Activate n8n knowledge updater workflow (ID: Bn29wDCN97tZRfiK)
+- [ ] Test `install.sh` on clean Ubuntu VM
+- [ ] Set up easyclaw.help landing page + payment integration
+
+---
+
+## Session Handoff Notes — 2026-03-30 (Phase 6 + 7 — Agent Brain + Telegram)
+
+### What Was Built This Session
+Added the LLM agent brain and Telegram bot — the core missing pieces that make EasyClaw a true conversational AI agent.
+
+#### Phase 7 — Telegram Bot (`telegram.py`, ~300 lines)
+- **TelegramBridge** is daemon subsystem #16, connects directly to Telegram Bot API via polling (no n8n middleman)
+- **Inbound**: free-form messages routed through `AgentBrain.chat()` for full LLM-powered conversational responses with tool calling
+- **Commands**: `/status` (OpenClaw health), `/logs` (last 20 log lines), `/stats` (KPI summary), `/help`
+- **Outbound**: CRITICAL alerts auto-forwarded to authorized chat IDs with 10-min dedup
+- **Authorization**: only responds to chat IDs listed in `telegram_chat_ids` config (empty = allow all)
+- **Graceful disable**: no bot token = subsystem doesn't start, zero impact
+- **Agent chat()**: new public method on AgentBrain with conversational system prompt addendum
+- **Library**: `python-telegram-bot>=21.0` (async-native, added to main dependencies)
+
+#### Phase 6 — Agent Brain (`agent.py`, ~500 lines)
+- **Agent loop** copies OpenClaw's architecture: system prompt -> call GLM-4.7-Flash via OpenRouter -> parse tool_calls -> execute tools -> loop
+- **Event-triggered with batching**: events accumulate for 10s, agent invokes, 30s cooldown. NOT continuously running.
+- **10 tools available to the agent**: 4 local (shell command, read file, restart OpenClaw, read logs) + 6 MCP (diagnose issue, search knowledge, get guide, troubleshoot gateway, web search, report incident)
+- **Dynamic system prompt**: rebuilt each invocation with current OpenClaw status (PID/CPU/RAM), circuit breaker state, MCP status, KPIs, and last 5 intervention summaries
+- **Security**: all shell commands validated through SecuritySandbox before execution. All actions recorded to fix ledger.
+- **Graceful fallback**: no API key -> rules-based healer. OpenRouter down -> fallback to healer. Unexpected exception -> fallback to healer. Zero regression from Phase 5.
+- **Cost**: ~$0.003/invocation worst case. Typical <$0.02/day. Model: `z-ai/glm-4.7-flash` via OpenRouter.
+
+#### Integration Points
+- **daemon.py**: Agent brain is subsystem #15. Events routed to agent if available, else to healer.
+- **Healer**: always runs as fallback — agent calls `healer.enqueue()` when it can't handle events.
+- **config.py**: 7 new config fields: `openrouter_api_key`, `openrouter_model`, `agent_enabled`, `agent_batch_window`, `agent_cooldown`, `agent_max_turns`, `agent_temperature`.
+
+#### Daemon Subsystem Count: 16 concurrent tasks
+1. alert_pipeline, 2. log_aggregator, 3. health_monitor, 4. healer (fallback), 5. **agent_brain**, 6. update_checker,
+7. context_monitor, 8. temp_cleaner, 9. dep_auditor, 10. env_validator, 11. resource_monitor,
+12. kpi_tracker, 13. dashboard, 14. resource_cap, 15. **telegram_bot**, 16. heartbeat
+
+### TODO — Phase 8 (Distribution & Launch)
+- [ ] Re-install editable package in WSL2 venv: `pip install -e .` (picks up Phase 6+7 files + new dependency)
+- [ ] Install `python-telegram-bot`: `pip install python-telegram-bot>=21.0`
+- [ ] Update `~/.easyclaw/config.yaml` with agent + Telegram + MCP config:
+  ```yaml
+  mcp_endpoint: "http://31.220.49.171:8002"
+  mcp_token: "ec_dev_token_001"
+  openrouter_api_key: "sk-or-v1-YOUR-KEY"
+  openrouter_model: "z-ai/glm-4.7-flash"
+  telegram_bot_token: "YOUR-BOT-TOKEN"
+  telegram_chat_ids: [YOUR_CHAT_ID]
+  ```
+- [ ] Create Telegram bot via @BotFather, get token, get your chat ID
+- [ ] Run `easyclaw doctor` to verify all checks pass including new config fields
+- [ ] Test agent brain: `easyclaw start -f`, inject error `echo "FATAL ERROR: heap out of memory" >> /tmp/openclaw/test.log`, observe LLM reasoning in logs
+- [ ] Test Telegram: send message to bot, verify LLM response comes back with tool usage
+- [ ] Test fallback: start with invalid OpenRouter key, verify events route to healer
+- [ ] Activate n8n workflow (ID: Bn29wDCN97tZRfiK) — currently inactive
+- [ ] Test n8n workflow: verify articles land in MCP database via `search_knowledge`
+- [ ] Production smoke test: run daemon for 24h with agent brain + Telegram, verify KPI data
+- [ ] Publish to PyPI: `pip install easyclaw`
+- [ ] Test `install.sh` on clean Ubuntu VM
+- [ ] Set up easyclaw.help landing page and payment integration
+
+### How To Resume Development
+```bash
+# In WSL2:
+source ~/.easyclaw/venv/bin/activate
+cd "/mnt/c/Users/me/OneDrive/Automation Projects/EasyClaw 2.0"
+pip install -e ".[dev]"   # reinstall with dev deps after code changes
+pip install python-telegram-bot>=21.0  # new Phase 7 dependency
+easyclaw doctor           # verify environment
+easyclaw start -f         # test foreground (all 16 subsystems)
+```
+
+### Known Issues / Quirks
+- **Phase 6+7 not yet tested at runtime** — code was written this session but daemon hasn't been started with an OpenRouter key or Telegram token yet. First runtime test will be needed.
+- **python-telegram-bot not yet installed in venv** — needs `pip install python-telegram-bot>=21.0` after re-installing the editable package
+- **config.yaml on disk may be stale** — was written with Phase 3 defaults. Delete it and restart daemon to regenerate with all new fields, or manually add the new fields.
+- **Log file discovery is at startup only** — new `.log` files created after daemon starts won't be tailed until restart.
+- **MCP server uses `/call-tool` HTTP endpoint** — plain HTTP transport on VPS port 8002.
+- **pyproject.toml license field** — uses `LicenseRef-Proprietary` (SPDX format) because hatchling rejects plain `Proprietary`.
+- **`easyclaw start` (background mode)** — re-execs via subprocess. Foreground mode (`-f`) is more reliable for debugging.
+- **Alert forwarding dedup** — `_forward_alerts` reads `alert_pipeline.recent_alerts` which is an in-memory ring buffer. If the ring buffer field names differ from what `telegram.py` expects (e.g., `alert.line` vs `alert.details`), may need a small fix on first test.
+
+---
+
+## Session Handoff Notes — 2026-03-30 (Phase 8 — Distribution Prep)
+
+### What Was Built This Session
+
+#### Distribution Infrastructure
+- **README.md** — expanded from 20 lines to full product docs (features, install methods, config reference, architecture diagram)
+- **CHANGELOG.md** — version history for 0.1.0 (all 7 phases + MCP server)
+- **pyproject.toml** — added project URLs (homepage, docs, repo, issues, changelog), expanded classifiers (audience, topic, OS, framework), more keywords
+- **Dockerfile** — added HEALTHCHECK probe hitting the dashboard `/health` endpoint
+- **pytest config** — added `[tool.pytest.ini_options]` to pyproject.toml
+
+#### Test Suite (108 tests, all passing)
+- `tests/test_classifier.py` — 20 tests: pattern matching (all 13 rule types), no-match cases, priority ordering, error hash determinism, context buffering
+- `tests/test_sandbox.py` — 30 tests: blocked commands (11 base + 11 patterns), allowed commands, sudo restrictions, kill restrictions, rm validation, file operations, restart targets
+- `tests/test_ledger.py` — 12 tests: record/retrieve, file persistence, stats, restart window counting, ring buffer, circuit breaker (trip, threshold, auto-reset)
+- `tests/test_kpi.py` — 10 tests: initial state, fix recording, MTTR average, auto-fix rate, uptime tracking, snapshot save/load, intervention rate
+- `tests/test_alerts.py` — 8 tests: dedup filter (pass, suppress, cooldown, cleanup), pipeline queue, async event processing, INFO-only logging
+- `tests/test_remediation.py` — 9 tests: builtin count, lookup by pattern/event type, missing lookup, priority, action validation, user YAML override, missing file handling
+- `tests/conftest.py` — shared fixtures (tmp_easyclaw_home, tmp_openclaw_home)
+
+#### GitHub Actions CI/CD
+- `.github/workflows/ci.yml` — runs pytest on push/PR against Python 3.10, 3.11, 3.12
+- `.github/workflows/publish.yml` — publishes to PyPI on GitHub release via trusted publishing (no API token needed)
+
+### What Needs To Happen Next (requires Rick's manual action)
+- [ ] Create GitHub repo (`easyclaw/easyclaw`) and push code
+- [ ] Configure PyPI trusted publishing (link GitHub repo to PyPI project)
+- [ ] Create Telegram bot via @BotFather, add token + chat ID to config.yaml
+- [ ] Test `install.sh` on clean Ubuntu VM
+- [ ] Production smoke test: run daemon 24h with agent brain + Telegram active
+- [ ] Activate n8n knowledge updater workflow (ID: Bn29wDCN97tZRfiK)
+- [ ] Set up easyclaw.help landing page + payment integration
+
+---
+
+## Prior Session Handoff Notes (2026-03-29 and 2026-03-30 earlier sessions)
+
+### Phases 0-5 + MCP Server v2 + n8n Workflow
+Built EasyClaw from zero to Phase 5 across two sessions. Full details in git history and prior CLAUDE.md versions. Key facts:
+- Phases 0-3 (2026-03-29): foundation, detection, self-healing, MCP client + server v2 (17 tools)
+- Phase 4 (2026-03-30 morning): personal trainer (5 modules — context monitor, temp cleaner, dep auditor, env validator, resource monitor)
+- Phase 5 (2026-03-30 morning): hardening (dashboard, KPIs, sandbox, resource capping, installer)
+- MCP server v2 deployed to VPS at port 8002 (Docker container `easyclaw-mcp`)
+- n8n knowledge updater workflow created (ID: Bn29wDCN97tZRfiK, inactive, needs activation)
+- 27/29 doctor checks passing, all 14 (now 16) subsystems start/stop cleanly

easyclaw-0.1.0/Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.12-slim
+
+LABEL maintainer="EasyClaw Team"
+LABEL description="EasyClaw — Autonomous doctor and personal trainer for OpenClaw"
+
+# Create non-root user
+RUN groupadd -r easyclaw && useradd -r -g easyclaw -m easyclaw
+
+# Install system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install EasyClaw
+WORKDIR /app
+COPY pyproject.toml .
+COPY src/ src/
+RUN pip install --no-cache-dir .
+
+# Runtime config
+USER easyclaw
+ENV EASYCLAW_HOME=/home/easyclaw/.easyclaw
+
+# The sidecar needs access to the host's OpenClaw dirs via volume mounts:
+#   -v ~/.openclaw:/host/.openclaw:ro
+#   -v /tmp/openclaw:/host/tmp/openclaw:ro
+# EasyClaw will auto-discover via OPENCLAW_HOME override or default paths.
+
+HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
+    CMD ["python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:18790/health', timeout=5)"]
+
+ENTRYPOINT ["easyclaw"]
+CMD ["start", "--foreground"]

easyclaw-0.1.0/EasyClaw 2.0 PRD.md

@@ -0,0 +1,52 @@
+# Product Requirements Document (PRD): EasyClaw Autonomous Agent
+
+## 1. Executive Summary
+**Project Name:** EasyClaw
+**Product Vision:** To provide an invisible, autonomous "doctor and personal trainer" for the OpenClaw agent. EasyClaw runs in tandem with OpenClaw in the same environment, ensuring optimal health, maximum uptime, and seamless functionality. By connecting to a proprietary Model Context Protocol (MCP) containing up-to-date documentation, troubleshooting steps, and system fixes, EasyClaw drastically reduces user friction and technical overhead.
+
+As this ecosystem is deployed to users—potentially acting as the core value proposition for onboarding portals like easyclaw.help—EasyClaw will ensure that non-technical users can maintain complex AI agents without needing developer-level intervention.
+
+## 2. Goals & Objectives
+* **Zero-Touch Maintenance:** Automatically detect, diagnose, and resolve OpenClaw runtime errors, configuration drift, and dependency issues without user intervention.
+* **Performance Optimization:** Act as a "personal trainer" by managing OpenClaw's memory, optimizing its context windows, and cleaning up temporary files or stalled background tasks.
+* **Seamless Integration:** Install and operate alongside OpenClaw as a "sidecar" process, sharing the same environmental variables, file system, and permissions natively.
+* **Real-Time Expertise:** Leverage a proprietary MCP to instantly access the latest OpenClaw documentation, GitHub issues, and patch notes to solve novel problems.
+
+## 3. User Personas
+* **The Primary User:** Uses the main OpenClaw agent for daily tasks, automation, and communication. They want OpenClaw to "just work" and do not want to deal with terminal errors, environment configuration, or broken dependencies.
+* **The System Administrator / Developer:** Needs a reliable way to push updates, hotfixes, and new documentation to remote OpenClaw instances. They will maintain the central proprietary MCP that EasyClaw talks to.
+
+## 4. System Architecture
+EasyClaw will be built on the exact same underlying architecture as OpenClaw, ensuring perfect compatibility and eliminating the need for a separate tech stack.
+
+* **Deployment Pattern:** Sidecar container or parallel background service. EasyClaw and OpenClaw exist in the same host environment/workspace.
+* **Interaction Layer:** * **OpenClaw:** Front-facing, interacts with the User.
+    * **EasyClaw:** Backend-facing, interacts with OpenClaw's environment, logs, and processes. Communicates with the User *only* for critical alerts (e.g., "I need a system reboot to apply a critical patch").
+* **Knowledge Layer:** EasyClaw securely authenticates to a remote, proprietary MCP server to fetch dynamic context (docs, fixes, updates).
+
+## 5. Core Features & Requirements
+
+### 5.1. The "Doctor" (Health & Remediation)
+* **Log Ingestion & Analysis:** EasyClaw must continuously tail OpenClaw’s execution logs. If a crash, loop, or error is detected, EasyClaw intercepts it.
+* **Automated Troubleshooting:** Upon detecting an error, EasyClaw queries the proprietary MCP with the stack trace to find the exact fix.
+* **Self-Healing Execution:** EasyClaw must have the permission to execute shell commands, edit OpenClaw configuration files, and restart the OpenClaw process to apply fixes.
+
+### 5.2. The "Personal Trainer" (Optimization & Maintenance)
+* **Context & Memory Management:** Monitor OpenClaw's token usage and memory footprint. If OpenClaw becomes sluggish, EasyClaw archives old context or clears cache.
+* **Dependency Auditing:** Routinely check OpenClaw's tools, plugins, and libraries. If an update is available via the MCP, EasyClaw safely applies it during idle hours.
+* **Environment Validation:** Ensure that API keys, database connections, and automation webhooks (such as connected n8n workflows) are valid and actively pinging.
+
+### 5.3. Proprietary MCP Integration
+* **Dynamic Knowledge Retrieval:** The MCP will serve as EasyClaw's external brain. It must stream markdown docs, JSON schemas for new commands, and known issue registries.
+* **Secure Authentication:** EasyClaw must use secure tokens to access the proprietary MCP, ensuring unauthorized agents cannot pull the proprietary documentation.
+* **Push-Pull Updates:** The MCP should be able to broadcast "Hotfix Alerts" that EasyClaw can pull down and apply instantly.
+
+## 6. Non-Functional Requirements
+* **Footprint:** Because EasyClaw runs alongside OpenClaw, its baseline CPU and RAM usage must be highly optimized (under 5-10% of total system resources) to avoid choking the main agent.
+* **Security & Permissions:** EasyClaw requires elevated privileges to restart OpenClaw and edit files. Strict sandboxing is required so that if OpenClaw is compromised, EasyClaw cannot be used as an escalation vector.
+* **Failsafe:** If EasyClaw crashes or fails to connect to the MCP, it must fail gracefully without taking OpenClaw down with it.
+
+## 7. Success Metrics (KPIs)
+* **Mean Time to Recovery (MTTR):** How quickly EasyClaw detects an OpenClaw error and restarts/fixes it (Target: < 60 seconds).
+* **Intervention Rate:** The percentage of errors EasyClaw fixes automatically vs. errors that require the user to step in.
+* **Uptime:** Overall availability of the OpenClaw agent.