# AGENTS

## Purpose
This file defines how agents and contributors should work in this repository.
It is a codebase playbook, not a product roadmap.

## Repository Map
- `server/app.py`: FastAPI routes, auth checks, response envelope, exception handling.
- `server/services.py`: screenshot/OCR/input/window/exec behavior and safety enforcement.
- `server/models.py`: request schemas and validation rules.
- `server/config.py`: environment loading and runtime settings.
- `tests/`: unit and API contract tests (monkeypatched where host behavior is nondeterministic).
- `docs/API.md`: public API request/response reference.
- `skill/SKILL.md`: operational method for agent usage of the API.

## Local Workflow
- Install dependencies: `pip install -r requirements.txt`
- Run server: `python -m server.app`
- Run tests: `pytest -q`
- Basic health check: `GET /health` with `x-clickthrough-token` when token auth is enabled.

## Non-Negotiable Contracts
- Keep the response envelope shape stable:
  - `ok`, `request_id`, `time_ms`, `data`, `error`
- Preserve one-action-per-request semantics in `/interact`.
- Keep coordinate behavior in global desktop coordinates unless an explicit versioned change is introduced.
- All new request fields must be represented in `server/models.py` with explicit validation constraints.

## Safety and Security Rules
- Do not weaken `x-clickthrough-token` validation.
- Do not weaken `/exec` secret validation (`x-clickthrough-exec-secret`).
- Preserve `dry_run` behavior for non-destructive execution paths.
- Preserve allowed-region enforcement for pointer-target actions.
- Keep `/exec` constraints explicit:
  - shell allowlist
  - timeout limits
  - output truncation limits

## Testing Expectations
- Add tests for each new behavior in services/models/routes.
- Cover success and failure paths, especially validation and ambiguity branches.
- Prefer deterministic tests with monkeypatches over host/UI-dependent flakiness.
- If API behavior changes, update tests in the same change.

## Documentation Policy
- When API behavior changes, update `docs/API.md` in the same change.
- Keep examples aligned with current schema in `docs/API.md` and `examples/quickstart.py`.
- Keep `skill/SKILL.md` aligned with current safe usage flow.