clickthrough/AGENTS.md

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.