diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 089945ca4f..0000000000 --- a/AGENTS.md +++ /dev/null @@ -1,213 +0,0 @@ -# AGENTS.md - -`AGENTS.md` is the canonical instruction source for agent behavior in this repository. -If any other entrypoint file conflicts with `AGENTS.md`, `AGENTS.md` wins. - -Derived entrypoint files: -- `CLAUDE.md` is generated from this file. -- `GEMINI.md` is generated from this file. -- `.github/copilot-instructions.md` may summarize this file for Copilot-specific discovery. - -## Project Purpose - -This repo transitions ALAS from a legacy script application into an LLM-augmented automation system. -The long-term goal is deterministic tool-first automation with LLM/vision used only for recovery. - -See: -- `docs/NORTH_STAR.md` -- `docs/ARCHITECTURE.md` -- `docs/ROADMAP.md` - -## Non-Negotiables - -- Never modify `upstream_alas/` directly for feature work. -- Never create additional git repos or submodules inside this repo. -- Treat `alas_wrapped/` as the runnable source of truth for customized behavior. -- Use deterministic tools first; use LLM/vision only for recovery and unexpected states. -- Do not commit runtime artifacts or secrets (for example: screenshots, ad-hoc runtime logs, local tokens). -- Keep `alas_wrapped/config/PatrickCustom.json` under version control and let hooks keep it in commit flow. -- If required docs for the current task have not been read, stop and read them before editing. - -## Required Reading - -Read these at session start: -1. `docs/NORTH_STAR.md` -2. `docs/ARCHITECTURE.md` -3. `docs/ROADMAP.md` - -Task-triggered required reads: -- MCP/tooling work: - - `docs/agent_tooling/README.md` - - `agent_orchestrator/alas_mcp_server.py` -- State machine or navigation behavior: - - `docs/state_machine/README.md` -- Environment/bootstrap changes: - - `docs/dev/environment_setup.md` -- Recovery agent or durable execution work: - - `docs/plans/recovery_agent_architecture.md` - - `docs/plans/durable_agent_architecture_design.md` -- Local VLM or vision integration work: - - `docs/plans/local_vlm_setup.md` -- State machine visualization work: - - `docs/plans/interactive_state_viz_plan.md` - - `docs/state_machine/STATE_MACHINE_VISUALIZATION.md` - -## Repository Model - -``` -ALAS/ [primary git repository] -├── upstream_alas/ [upstream sync submodule] -├── alas_wrapped/ [runnable ALAS + local customizations] -│ └── tools/ [tools that import ALAS internals] -├── agent_orchestrator/ [MCP server + standalone orchestration tools] -├── docs/ [project documentation] -└── .githooks/ [repo-tracked git hooks] -``` - -Directory ownership: -- `upstream_alas/`: sync source only. -- `alas_wrapped/`: runtime source of truth. -- `alas_wrapped/tools/`: ALAS-internal imports only. -- `agent_orchestrator/`: standalone modern tooling and MCP. - -Placement rule: -- If code imports `module.*` or ALAS internals, place it under `alas_wrapped/tools/`. -- Otherwise place it under `agent_orchestrator/`. - -## Upstream Sync Workflow - -One-way model: -1. Update submodule: - - `git submodule update --remote -- upstream_alas` -2. Compare upstream changes. -3. Apply needed changes manually into `alas_wrapped/`. -4. Preserve local customizations and MCP hooks. -5. Validate wrapped behavior before commit. - -## Runtime, Logs, and Launch - -Core configs: -- `alas_wrapped/config/PatrickCustom.json` -- `alas_wrapped/config/deploy.yaml` -- `alas_wrapped/config/alas.json` - -Known local environment: -- `Alas.Emulator.Serial`: `127.0.0.1:21503` -- `Alas.EmulatorInfo.Emulator`: `MEmuPlayer` - -## Emulator Environment (MEmu) - -**Prerequisite:** The MEmu Multiple Instance Manager (`MEmuConsole.exe`) is always running with admin permissions. This is the control plane for all emulator instances. - -### Key Commands (memuc.exe) - -The `memuc` CLI at `C:\Program Files\Microvirt\MEmu\memuc.exe` controls emulator instances: - -```bash -# Start/stop VMs -memuc start -n MEmu # Start by name -memuc start -i 0 # Start by index -memuc stop -n MEmu # Stop by name -memuc stopall # Stop all VMs - -# Check status -memuc listvms # List all VMs with index, status, PID -memuc listvms --running # List only running VMs -memuc isvmrunning -n MEmu # Check specific VM - -# VM lifecycle -memuc reboot -i 0 # Reboot VM -memuc clone -i 0 # Clone a VM -``` - -### Common Workflow - -1. **MEmuConsole.exe is already running** (admin) - the user ensures this -2. Use `memuc` commands to start/stop emulator instances as needed -3. Once started, ADB connects via `127.0.0.1:21503` -4. MCP server ADB tools (`adb_screenshot`, `adb_tap`, etc.) can then interact with the emulator - -### Python Integration - -Direct subprocess calls are sufficient - no special libraries required: - -```python -import subprocess - -# Start emulator -subprocess.run(["memuc", "start", "-n", "MEmu"], check=True) - -# Check status -result = subprocess.run(["memuc", "isvmrunning", "-n", "MEmu"], - capture_output=True, text=True) -``` - -Launch wrapped bot: -```bash -cd alas_wrapped -PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe gui.py --run PatrickCustom -``` - -MCP server purpose: -- Exposes deterministic ALAS/ADB tools via MCP for supervisor agents. -- Avoids runtime startup penalties by keeping ALAS loaded in a persistent process. - -Run MCP server: -```bash -cd agent_orchestrator -uv run alas_mcp_server.py --config alas -``` - -Log parser purpose: -- Fast forensic analysis of task timelines, warnings/errors, and tracebacks. -- Preferred over manual full-log scanning for debugging regressions. - -Recommended parser usage: -```bash -python3 agent_orchestrator/log_parser.py alas_wrapped/log/YYYY-MM-DD_PatrickCustom.txt --timeline --errors --trace -python3 agent_orchestrator/log_parser.py alas_wrapped/log/YYYY-MM-DD_PatrickCustom.txt --summary -``` - -## MCP Tool Surface - -Canonical callable names in `agent_orchestrator/alas_mcp_server.py`: -- `adb_screenshot` -- `adb_tap` -- `adb_swipe` -- `alas_get_current_state` -- `alas_goto` -- `alas_list_tools` -- `alas_call_tool` -- `alas_login_ensure_main` - -## Tool Contract For New Tools - -Return state using: -```python -{ - "success": bool, - "data": object | None, - "error": str | None, - "observed_state": str | None, - "expected_state": str -} -``` - -## Change Discipline - -- Keep changes focused and local to the request. -- Update docs when behavior changes: - - `CHANGELOG.md` for user-visible behavior changes. - - `docs/agent_tooling/README.md` for tool changes. - - `docs/ARCHITECTURE.md` for architecture changes. - - `docs/monorepo/MONOREPO_SYNC_NOTES.md` for process changes. - - `docs/ROADMAP.md` when milestone status changes. - -## Required Git Workflow - -- Any non-trivial code or behavior change must end with a commit and PR. -- Use a feature branch for non-trivial work. -- Keep commits scoped and descriptive. -- If runtime cannot execute git operations, provide exact commands for operator execution. -- The local hook flow stages `alas_wrapped/config/PatrickCustom.json` on pre-commit so it is included in the same commit. -- Pre-push validates that `PatrickCustom.json` is clean to prevent accidental drift. diff --git a/CLAUDE.md b/CLAUDE.md index 10d858bd6c..f0cfbc2bbf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,16 @@ # CLAUDE.md This file is the single canonical instruction source for all agents working in this repository. -If any instruction file conflicts with this one, this file wins. - -## Entrypoint Files - -- `AGENTS.md` exists for Codex discovery and must mirror critical rules from this file. -- `GEMINI.md` exists for Gemini entry and must mirror critical rules from this file. -- `.github/copilot-instructions.md` exists for Copilot entry and must mirror critical rules from this file. ## Non-Negotiables +- **Dual-use constraint**: `alas_wrapped/` stays a fully working ALAS install forever for daily gameplay; bot changes must never break `gui.py --run PatrickCustom`. +- **Extract, don't wrap**: ALAS is reference only (state machine, page graph, priorities, assets). Build clean standalone tools in `agent_orchestrator/` (our "bot" repo equivalent), using Python 3.10+, with no runtime imports from `alas_wrapped/`. +- **Two-tier model**: Tier 1 (hot path): fast deterministic programmatic tools (OCR, element match, navigation). Tier 2 (recovery only): VLM screenshot analysis + manual control when screen unknown or tool fails. +- **Strict Tool Contract**: Every MCP tool must return `{success, data, error, observed_state, expected_state}`. +- **TDD + Live Emulator**: Every feature must be tested directly against the emulator (ground truth, no hallucination). - Never modify `upstream_alas/` directly. - Never create additional git repos or submodules inside this repo. -- Treat `alas_wrapped/` as the runnable source of truth for customized ALAS behavior. -- Use deterministic tools first; use LLM/vision only for recovery. - Do not commit runtime artifacts or secrets (for example: `alas_wrapped/alas_admin_token`, screenshots, ad-hoc runtime logs). - If a required doc for the current task has not been read, stop and ask before editing. @@ -24,7 +20,7 @@ If any instruction file conflicts with this one, this file wins. - Replace ALAS with an LLM-augmented system. - Deterministic tools for normal operation. - LLM + vision for recovery when tools fail or unexpected state appears. -- Shared tool interfaces across development and production orchestration. +- Shared tool interfaces across development and production orchestration (Single-harness principle). ## Required Reading @@ -33,156 +29,37 @@ Read these in order at session start: 2. `docs/ARCHITECTURE.md` 3. `docs/ROADMAP.md` -Task-triggered required reads: -- MCP/tool implementation work: - - `docs/agent_tooling/README.md` - - `agent_orchestrator/alas_mcp_server.py` -- State machine or navigation behavior: - - `docs/state_machine/README.md` -- Environment/bootstrap changes: - - `docs/dev/environment_setup.md` - -Fail-closed rule: -- If the task implies one of the sections above and the required file has not been read yet, stop and request confirmation before continuing. - ## Repository Model ``` ALAS/ [primary git repository] ├── upstream_alas/ [read-only upstream submodule] ├── alas_wrapped/ [runnable ALAS + local customizations] -│ └── tools/ [tools that import ALAS internals] -├── agent_orchestrator/ [MCP server + standalone orchestration tools] +├── agent_orchestrator/ [azurlane-agent: MCP server + standalone orchestration tools] ├── docs/ [project documentation] └── scripts/ [developer scripts] ``` Directory ownership: - `upstream_alas/`: sync source only. -- `alas_wrapped/`: runtime source of truth. -- `alas_wrapped/tools/`: ALAS-internal imports only. -- `agent_orchestrator/`: standalone modern tooling and MCP. +- `alas_wrapped/`: runtime source of truth for normal gameplay. +- `agent_orchestrator/`: standalone modern tooling and MCP for the bot. Placement rule: -- If code imports `module.*` or ALAS internals, place it under `alas_wrapped/tools/`. -- Otherwise place it under `agent_orchestrator/`. - -## Upstream Sync Workflow - -One-way model: -1. Update submodule: - - `git submodule update --remote -- upstream_alas` -2. Compare upstream changes. -3. Apply necessary changes into `alas_wrapped/` manually. -4. Preserve local customizations and MCP hooks. -5. Validate behavior in wrapped runtime before commit. +- `agent_orchestrator/` must not import `module.*` or ALAS internals. ## Runtime, Config, and Launch Core config files: - `alas_wrapped/config/PatrickCustom.json` -- `alas_wrapped/config/deploy.yaml` -- `alas_wrapped/config/alas.json` Known environment values for this setup: - `Alas.Emulator.Serial`: `127.0.0.1:21513` -- `Alas.EmulatorInfo.Emulator`: `MEmuPlayer` - -## Emulator Environment (MEmu) - -**Prerequisite:** The MEmu Multiple Instance Manager (`MEmuConsole.exe`) is always running with admin permissions. This is the control plane for all emulator instances. - -### Key Commands (memuc.exe) - -The `memuc` CLI at `C:\Program Files\Microvirt\MEmu\memuc.exe` controls emulator instances: - -```bash -# Start/stop VMs -memuc start -n MEmu # Start by name -memuc start -i 0 # Start by index -memuc stop -n MEmu # Stop by name -memuc stopall # Stop all VMs - -# Check status -memuc listvms # List all VMs with index, status, PID -memuc listvms --running # List only running VMs -memuc isvmrunning -n MEmu # Check specific VM - -# VM lifecycle -memuc reboot -i 0 # Reboot VM -memuc clone -i 0 # Clone a VM -``` - -### Common Workflow - -1. **MEmuConsole.exe is already running** (admin) - the user ensures this -2. Use `memuc` commands to start/stop emulator instances as needed -3. Once started, ADB connects via `127.0.0.1:21503` -4. MCP server ADB tools (`adb_screenshot`, `adb_tap`, etc.) can then interact with the emulator - -### Python Integration - -Direct subprocess calls are sufficient - no special libraries required: - -```python -import subprocess - -# Start emulator -subprocess.run(["memuc", "start", "-n", "MEmu"], check=True) - -# Check status -result = subprocess.run(["memuc", "isvmrunning", "-n", "MEmu"], - capture_output=True, text=True) -``` - -Wrapped runtime setup: -```bash -cd alas_wrapped -uv venv --python=3.9 .venv -uv pip install --python .venv/Scripts/python.exe -r requirements.txt --overrides overrides.txt -``` - -Launch wrapped bot (preferred explicit path): -```bash -cd alas_wrapped -PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe gui.py --run PatrickCustom -``` - -Convenience launch: -```bash -cd alas_wrapped -alas.bat -``` - -MCP server: -```bash -cd agent_orchestrator -uv run alas_mcp_server.py --config alas -``` - -Log parser: -```bash -python agent_orchestrator/log_parser.py ../alas_wrapped/log/*.txt -``` - -## MCP Tool Surface - -Canonical callable names in `agent_orchestrator/alas_mcp_server.py`: -- `adb_screenshot` -- `adb_tap` -- `adb_swipe` -- `alas_get_current_state` -- `alas_goto` -- `alas_list_tools` -- `alas_call_tool` - -Notes: -- Some docs may use dotted labels (for example `adb.screenshot`), but callable names here are underscore-based. -- `adb_screenshot` returns image content with `mimeType: image/png` and base64 payload. +- `Alas.EmulatorInfo.Emulator`: `MEmuPlayer` (Fallback; LDPlayer is primary target) ## Tool Contract for New Tools -Return state in this envelope: +All MCP tools must return state in this envelope to support the orchestrator decision loop: ```python { "success": bool, @@ -193,38 +70,8 @@ Return state in this envelope: } ``` -## Change Discipline - -- Keep changes focused and local to the request. -- Update docs when behavior changes: - - `CHANGELOG.md` for user-visible behavior changes. - - `docs/agent_tooling/README.md` for new or changed tools. - - `docs/ARCHITECTURE.md` for architecture changes. - - `docs/monorepo/MONOREPO_SYNC_NOTES.md` for process changes. - - `docs/ROADMAP.md` when milestone status changes. - -Workflow modes: -- Upstream sync mode: `upstream_alas/` -> `alas_wrapped/`. -- Experimental mode: validate in scratch, then port minimal working changes back to `alas_wrapped/`. - ## Required Git Workflow - Any non-trivial code or behavior change must end with a commit and PR. - Use a feature branch for non-trivial work. - Keep commits scoped and descriptive. -- Open or update a PR with summary, rationale, and affected areas. -- If changelog/docs are impacted, include them in the same PR. -- If the current runtime cannot execute git operations, provide exact commands for the human operator to run. - -## Cross References - -- `docs/NORTH_STAR.md` -- `docs/ARCHITECTURE.md` -- `docs/ROADMAP.md` -- `docs/agent_tooling/README.md` -- `docs/monorepo/MONOREPO_SYNC_NOTES.md` -- `docs/state_machine/README.md` -- `docs/dev/environment_setup.md` -- `docs/DOCUMENTATION_GOVERNANCE.md` -- `agent_orchestrator/alas_mcp_server.py` -- `agent_orchestrator/log_parser.py` diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index d82e68ee23..0000000000 --- a/GEMINI.md +++ /dev/null @@ -1,168 +0,0 @@ - - -# AGENTS.md - -`AGENTS.md` is the canonical instruction source for agent behavior in this repository. -If any other entrypoint file conflicts with `AGENTS.md`, `AGENTS.md` wins. - -Derived entrypoint files: -- `CLAUDE.md` is generated from this file. -- `GEMINI.md` is generated from this file. -- `.github/copilot-instructions.md` may summarize this file for Copilot-specific discovery. - -## Project Purpose - -This repo transitions ALAS from a legacy script application into an LLM-augmented automation system. -The long-term goal is deterministic tool-first automation with LLM/vision used only for recovery. - -See: -- `docs/NORTH_STAR.md` -- `docs/ARCHITECTURE.md` -- `docs/ROADMAP.md` - -## Non-Negotiables - -- Never modify `upstream_alas/` directly for feature work. -- Never create additional git repos or submodules inside this repo. -- Treat `alas_wrapped/` as the runnable source of truth for customized behavior. -- Use deterministic tools first; use LLM/vision only for recovery and unexpected states. -- Do not commit runtime artifacts or secrets (for example: screenshots, ad-hoc runtime logs, local tokens). -- Keep `alas_wrapped/config/PatrickCustom.json` under version control and let hooks keep it in commit flow. -- If required docs for the current task have not been read, stop and read them before editing. - -## Required Reading - -Read these at session start: -1. `docs/NORTH_STAR.md` -2. `docs/ARCHITECTURE.md` -3. `docs/ROADMAP.md` - -Task-triggered required reads: -- MCP/tooling work: - - `docs/agent_tooling/README.md` - - `agent_orchestrator/alas_mcp_server.py` -- State machine or navigation behavior: - - `docs/state_machine/README.md` -- Environment/bootstrap changes: - - `docs/dev/environment_setup.md` -- Recovery agent or durable execution work: - - `docs/plans/recovery_agent_architecture.md` - - `docs/plans/durable_agent_architecture_design.md` -- Local VLM or vision integration work: - - `docs/plans/local_vlm_setup.md` -- State machine visualization work: - - `docs/plans/interactive_state_viz_plan.md` - - `docs/state_machine/STATE_MACHINE_VISUALIZATION.md` - -## Repository Model - -``` -ALAS/ [primary git repository] -├── upstream_alas/ [upstream sync submodule] -├── alas_wrapped/ [runnable ALAS + local customizations] -│ └── tools/ [tools that import ALAS internals] -├── agent_orchestrator/ [MCP server + standalone orchestration tools] -├── docs/ [project documentation] -└── .githooks/ [repo-tracked git hooks] -``` - -Directory ownership: -- `upstream_alas/`: sync source only. -- `alas_wrapped/`: runtime source of truth. -- `alas_wrapped/tools/`: ALAS-internal imports only. -- `agent_orchestrator/`: standalone modern tooling and MCP. - -Placement rule: -- If code imports `module.*` or ALAS internals, place it under `alas_wrapped/tools/`. -- Otherwise place it under `agent_orchestrator/`. - -## Upstream Sync Workflow - -One-way model: -1. Update submodule: - - `git submodule update --remote -- upstream_alas` -2. Compare upstream changes. -3. Apply needed changes manually into `alas_wrapped/`. -4. Preserve local customizations and MCP hooks. -5. Validate wrapped behavior before commit. - -## Runtime, Logs, and Launch - -Core configs: -- `alas_wrapped/config/PatrickCustom.json` -- `alas_wrapped/config/deploy.yaml` -- `alas_wrapped/config/alas.json` - -Known local environment: -- `Alas.Emulator.Serial`: `127.0.0.1:21503` -- `Alas.EmulatorInfo.Emulator`: `MEmuPlayer` - -Launch wrapped bot: -```bash -cd alas_wrapped -PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe gui.py --run PatrickCustom -``` - -MCP server purpose: -- Exposes deterministic ALAS/ADB tools via MCP for supervisor agents. -- Avoids runtime startup penalties by keeping ALAS loaded in a persistent process. - -Run MCP server: -```bash -cd agent_orchestrator -uv run alas_mcp_server.py --config alas -``` - -Log parser purpose: -- Fast forensic analysis of task timelines, warnings/errors, and tracebacks. -- Preferred over manual full-log scanning for debugging regressions. - -Recommended parser usage: -```bash -python3 agent_orchestrator/log_parser.py alas_wrapped/log/YYYY-MM-DD_PatrickCustom.txt --timeline --errors --trace -python3 agent_orchestrator/log_parser.py alas_wrapped/log/YYYY-MM-DD_PatrickCustom.txt --summary -``` - -## MCP Tool Surface - -Canonical callable names in `agent_orchestrator/alas_mcp_server.py`: -- `adb_screenshot` -- `adb_tap` -- `adb_swipe` -- `alas_get_current_state` -- `alas_goto` -- `alas_list_tools` -- `alas_call_tool` -- `alas_login_ensure_main` - -## Tool Contract For New Tools - -Return state using: -```python -{ - "success": bool, - "data": object | None, - "error": str | None, - "observed_state": str | None, - "expected_state": str -} -``` - -## Change Discipline - -- Keep changes focused and local to the request. -- Update docs when behavior changes: - - `CHANGELOG.md` for user-visible behavior changes. - - `docs/agent_tooling/README.md` for tool changes. - - `docs/ARCHITECTURE.md` for architecture changes. - - `docs/monorepo/MONOREPO_SYNC_NOTES.md` for process changes. - - `docs/ROADMAP.md` when milestone status changes. - -## Required Git Workflow - -- Any non-trivial code or behavior change must end with a commit and PR. -- Use a feature branch for non-trivial work. -- Keep commits scoped and descriptive. -- If runtime cannot execute git operations, provide exact commands for operator execution. -- The local hook flow stages `alas_wrapped/config/PatrickCustom.json` on pre-commit so it is included in the same commit. -- Pre-push validates that `PatrickCustom.json` is clean to prevent accidental drift. diff --git a/agent_orchestrator/maa_test.py b/agent_orchestrator/maa_test.py new file mode 100644 index 0000000000..cd820fa431 --- /dev/null +++ b/agent_orchestrator/maa_test.py @@ -0,0 +1,18 @@ +import asyncio +import logging +import maa_mcp.main +from maa_mcp.core import mcp + +logging.basicConfig(level=logging.DEBUG) + +async def test_maa(): + print("Testing MaaMCP tools...") + try: + tools = await mcp.list_tools() + for t in tools: + print(f" - {t.name}: {t.description}") + except Exception as e: + print(f"Error: {e}") + +if __name__ == "__main__": + asyncio.run(test_maa()) diff --git a/agent_orchestrator/maa_test_connect.py b/agent_orchestrator/maa_test_connect.py new file mode 100644 index 0000000000..b8a3d31a2f --- /dev/null +++ b/agent_orchestrator/maa_test_connect.py @@ -0,0 +1,39 @@ +import asyncio +import logging +import json +import maa_mcp.main +from maa_mcp.core import mcp +import tempfile +import os + +logging.basicConfig(level=logging.DEBUG) + +async def test_connect(): + print("Testing MaaMCP connection to MEmu or LDPlayer...") + try: + # Step 1: Find ADB devices + devices = await mcp.call_tool("find_adb_device_list") + print(f"Found devices: {devices}") + + # Step 2: Try to connect to the first available device or specific port + target_device = "127.0.0.1:21513" # MEmu default port in our config + if devices and isinstance(devices, list): + for d in devices: + if "21513" in str(d): + target_device = d + break + + print(f"Connecting to: {target_device}") + controller_id = await mcp.call_tool("connect_adb_device", {"device_name": target_device}) + print(f"Controller ID: {controller_id}") + + if controller_id: + # Step 3: Test screenshot + screenshot_path = await mcp.call_tool("screencap", {"controller_id": controller_id}) + print(f"Screenshot saved to: {screenshot_path}") + + except Exception as e: + print(f"Error: {e}") + +if __name__ == "__main__": + asyncio.run(test_connect()) diff --git a/agent_orchestrator/maa_test_connect2.py b/agent_orchestrator/maa_test_connect2.py new file mode 100644 index 0000000000..29345c68de --- /dev/null +++ b/agent_orchestrator/maa_test_connect2.py @@ -0,0 +1,67 @@ +import asyncio +import logging +import maa_mcp.main +from maa_mcp.core import mcp + +logging.basicConfig(level=logging.DEBUG) + +async def test_connect(): + print("Testing MaaMCP connection to MEmu or LDPlayer...") + try: + # Step 1: Find ADB devices + devices_result = await mcp.call_tool("find_adb_device_list") + + # In FastMCP, call_tool returns a ToolResult object or sequence + devices = [] + if hasattr(devices_result, 'structured_content'): + data = getattr(devices_result, 'structured_content') + if isinstance(data, dict) and 'result' in data: + devices = data['result'] + elif isinstance(devices_result, list): + # Try to parse from string if it's returning text + for item in devices_result: + if hasattr(item, 'text'): + try: + import json + parsed = json.loads(item.text) + if 'result' in parsed: + devices = parsed['result'] + except: + pass + + print(f"Found devices list: {devices}") + + target_device = "127.0.0.1:21513" # MEmu default port in our config + if devices and isinstance(devices, list) and len(devices) > 0: + for d in devices: + if "21513" in str(d): + target_device = d + break + + print(f"Connecting to: {target_device}") + + # Connect + conn_result = await mcp.call_tool("connect_adb_device", {"device_name": target_device}) + + controller_id = None + if hasattr(conn_result, 'structured_content'): + data = getattr(conn_result, 'structured_content') + if isinstance(data, dict) and 'result' in data: + controller_id = data['result'] + + print(f"Controller ID: {controller_id}") + + if controller_id: + # Step 3: Test screenshot + screenshot_path = await mcp.call_tool("screencap", {"controller_id": controller_id}) + print(f"Screenshot saved result: {screenshot_path}") + + # Step 4: Test OCR + ocr_result = await mcp.call_tool("ocr", {"controller_id": controller_id}) + print(f"OCR result: {ocr_result}") + + except Exception as e: + print(f"Error: {e}") + +if __name__ == "__main__": + asyncio.run(test_connect()) diff --git a/agent_orchestrator/pyproject.toml b/agent_orchestrator/pyproject.toml index 2a6fc6cf93..63ca8aa52f 100644 --- a/agent_orchestrator/pyproject.toml +++ b/agent_orchestrator/pyproject.toml @@ -31,6 +31,7 @@ dependencies = [ "pyzmq>=27.1.0", "packaging>=26.0", "rich>=13.0.0", + "maa-mcp>=1.0.3", ] [build-system] diff --git a/docs/BEHAVIORAL_CATALOG.md b/docs/BEHAVIORAL_CATALOG.md new file mode 100644 index 0000000000..c57b04e36b --- /dev/null +++ b/docs/BEHAVIORAL_CATALOG.md @@ -0,0 +1,71 @@ +# Behavioral Catalog + +This catalog documents "what" the ALAS bot does, breaking down Azur Lane automation into implementation-agnostic requirements. +It serves as the specification for building deterministic element-powered tools in the `agent_orchestrator` repository. + +## Principles +1. **Semantic over Coordinate**: Define tasks by what button/text is pressed (e.g., `tap_element("commissions")`), not by screen coordinates. +2. **State Context**: Identify what resources/timers/elements are relevant to OCR/monitor on a given screen. +3. **Expected State Contract**: Every task must have a clear `expected_state` upon success. + +## Core Workflows (from PatrickCustom.json) + +### Domain: Login & Bootstrap +- **Goal**: Navigate from a closed game or initial loading screen to the main lobby (`page_main`). +- **Steps**: + 1. Detect game launch / loading screen. + 2. Handle server selection if necessary. + 3. Wait for "Touch to Start" or equivalent element. + 4. Dismiss daily login rewards, announcements, and event popups until `page_main` is reached. +- **Relevant Elements**: `["Touch to Start", "X" (close buttons on popups), "Confirm", "Main Lobby Icon"]` +- **Expected State**: `page_main` + +### Domain: Resource Tracking (Persistent State) +- **Goal**: Continuously scan and cache values for key resources. +- **Relevant Elements (OCR targets)**: + - `Oil Balance` + - `Coin Balance` + - `Gem Balance` + - `Action Points (AP)` +- **Expected State**: Updated `{oil: int, coins: int, gems: int, ap: int}` cache. + +### Domain: Commissions +- **Goal**: Collect finished commissions and start new ones based on priority (e.g., cube > gem > oil). +- **Steps**: + 1. Navigate to Commissions page. + 2. Check for completed commissions ("Collect All" / individual "Collect"). + 3. Evaluate available commissions and select based on priority rules. + 4. Assign ships (auto-fill) and start. +- **Relevant Elements**: `["Commissions", "Collect All", "Start", "Auto-Fill"]` +- **Expected State**: All completed commissions collected, new commissions started up to the limit. + +### Domain: Daily Rewards & Mail +- **Goal**: Collect daily mission rewards and mail. +- **Steps**: + 1. Navigate to Missions/Tasks page. + 2. Tap "Collect All". + 3. Navigate to Mail. + 4. Tap "Collect All" (if mail box is not full / resource limits allow). +- **Relevant Elements**: `["Missions", "Mail", "Collect All"]` +- **Expected State**: Dailies claimed, Mail rewards claimed. + +### Domain: Combat / Event Farming +- **Goal**: Execute standard map/event combat loops. +- **Steps**: + 1. Navigate to target map/event stage. + 2. Verify fleet selection and sufficient oil/morale. + 3. Start Auto-Search or manually engage mob/boss nodes. + 4. Detect combat end, claim rewards, handle new ship drops (lock or retire). +- **Relevant Elements**: `["Go", "Auto-Search", "Confirm", "Victory", "Confirm/Lock/Retire"]` +- **Expected State**: Combat loop completed, returned to map selection or main lobby. + +### Domain: Dorm +- **Goal**: Manage ship morale, food, and training. +- **Steps**: + 1. Navigate to Dorm. + 2. Check food supply, refill if below threshold. + 3. Check for heart/coin bubbles over ships and tap to collect. +- **Relevant Elements**: `["Dorm", "Snacks/Food Refill", "Collect bubbles"]` +- **Expected State**: Dorm food refilled, affection/coins collected. + +*(To be expanded as more tasks from PatrickCustom.json are integrated)* diff --git a/docs/DOC_GUIDE.md b/docs/DOC_GUIDE.md new file mode 100644 index 0000000000..c5fe664b5f --- /dev/null +++ b/docs/DOC_GUIDE.md @@ -0,0 +1,34 @@ +# Documentation Governance Guide + +This playbook outlines the rules for naming, organizing, and maintaining documentation within this project. + +## Single Source of Truth + +- `CLAUDE.md` is the single canonical instruction source for all agents working in this repository. +- `NORTH_STAR.md` is immutable policy for the project vision. Edits should be surgical (no wholesale rewrites). +- Do not create redundant agent instruction files (e.g., `AGENTS.md`, `GEMINI.md`). + +## Organization + +Documentation is stored in the `docs/` directory. + +### Categories +- `plans/`: Implementation plans, architecture designs, and recovery agent specifications. +- `state_machine/`: ALAS state machine mappings and visualizations. +- `dev/`: Environment setup and developer onboarding. + +### Naming Conventions +- Use `UPPERCASE.md` for project-wide policy and governance documents (e.g., `NORTH_STAR.md`, `ARCHITECTURE.md`, `ROADMAP.md`, `DOC_GUIDE.md`). +- Use `snake_case.md` or `lowercase.md` for feature-specific plans and guides (e.g., `interactive_state_viz_plan.md`, `environment_setup.md`). + +## Maintenance Rules + +1. **Prune Stale Documents:** If a document is out of date or superceded by a new architectural decision (e.g., repo split), delete it or move it to an `archive/` folder. Don't leave dangling references. +2. **Update on Change:** Whenever code behavior, architecture, or tool contracts change, update the corresponding documentation (e.g., `ARCHITECTURE.md`, `ROADMAP.md`). +3. **Cross-Referencing:** Use relative links to connect related documentation, but ensure links remain valid when moving files. + +## Behavioral Catalog (BEHAVIORAL_CATALOG.md) + +This is the critical bridge document that extracts "what" ALAS does (every task, screen sequence, decision, edge case) into implementation-agnostic requirements. +- Document tasks domain by domain (e.g., login, commissions, dailies). +- This catalog serves as the specification for building deterministic element-powered tools in the `agent_orchestrator` repository.