q792602257
433ab41f95
Adds a Streamable HTTP MCP server (mount /mcp, port 8765) to the device-host-agent process so Hermes Agent (or any MCP client) can drive devices directly, coexisting with the Cloud Control Plane worker path. Per-device session-level locking with 20s TTL, independent bearer-token auth, and bidirectional cloud ↔ MCP coordination via a new heartbeat field. Implementation: - 4 new modules (mcp_token, mcp_lock, web/mcp_auth, web/mcp) - Console mount at /mcp with bearer auth sub-app - Cloud heartbeat payload + scheduler skip MCP-busy devices - AssignmentExecutor fail-fast reverse check - CLI mcp-token subcommand - docs/MCP_INTEGRATION.md + MACOS_IPHONE_SETUP.md section Spec: docs/superpowers/specs/2026-07-21-host-agent-mcp-server-design.md Plan: docs/superpowers/plans/2026-07-21-host-agent-mcp-server.md 18 implementation commits ( Tasks 1-15 + final fix wave). Spec/plan cherry-picks are detected as already-applied via patch-id. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> # Conflicts: # docs/superpowers/specs/2026-07-21-host-agent-mcp-server-design.md
Device Agent Runtime
Device Agent Runtime is a device-agnostic runtime for LLM-driven automation. It gives agents a stable way to observe, decide, and act against real devices through a small set of domain models, driver contracts, tools, perception providers, and runtime orchestration.
iPhone automation through WebDriverAgent/Appium is the first driver, not the platform boundary. Future drivers can target Android, browsers, desktop environments, or other device surfaces without changing the runtime's core contracts.
Current Shape
core/: shared domain models and runtime errors.driver/: theDrivercontract, concrete driver adapters, and driver-type registry.device/: device lifecycle and active driver management.tools/: device capabilities exposed to Runtime and adapter layers.perception/: screen-to-Sceneperception behindPerceptionProvider.runtime/: planning and execution orchestration.api/: MCP and supporting integration adapters.storage/: timeline, task, and device configuration persistence.packages/cloud-platform/: cloud scheduling, device pooling, plugins, and the Python cloud SDK as thedevice-cloud-platformworkspace member.apps/cloud-api/: deployable authenticated Cloud Control Plane with PostgreSQL/SQLite persistence, scheduling, leases, and health endpoints.apps/device-host-agent/: outbound Host Agent that synchronizes configured devices and executes leased tasks through the existing Runtime/workflow.
Python Workspace
The repository uses a uv workspace with one committed lockfile. From the repository root, synchronize every Python member with:
uv sync --locked --all-packages
Run the complete local test suite in a workspace environment:
uv run --all-packages pytest -m "not integration"
Select one member when running package-specific commands:
uv run --package device-agent-runtime python -c "import runtime"
uv run --package device-cloud-platform python -c "import cloud"
uv run --package device-cloud-api device-cloud-api --help
uv run --package device-host-agent device-host-agent --help
uv build --package device-agent-runtime
uv build --package device-cloud-platform
Runtime is an in-process execution library, not a standalone HTTP service. The
Host Agent console at http://127.0.0.1:8765/tasks is the authenticated
operator view for the tasks that actually execute on that Host, including
per-step screenshots, OCR observations, and UI-tree results. The Cloud Console
remains the fleet-level view for dispatch status and Cloud-proxy planner history.
Project Direction
The durable roadmap is in docs/ROADMAP.md. The architecture invariants future changes must preserve are in docs/CONSTITUTION.md.
Operator Guides
- Cloud Control Plane deployment: run local SQLite or deployed PostgreSQL, configure credentials and Runtime AI planning, and perform orderly shutdown or rollback.
- macOS migration and real iPhone setup: install Xcode, Appium/XCUITest, sign WebDriverAgent, verify a real device, and run a connected Host Agent.