Add environment self-check utility (agent-s_doctor) for pre-run and post-failure diagnostics

[TryAwesome]

Self-check System Implementation

This PR introduces a new environment self-check utility to help contributors self-check utility (agent-s_doctor) for pre-run and post-failure diagnostics

Key Updates

• New self_check.py in the project root
  Performs unified checks for Python version, dependencies, log directory permissions, and OS-specific tools/permissions on macOS, Linux, and Windows.
• Updated setup.py
  Registers the script via py_modules and adds a CLI entry point:

  entry_points={
      'console_scripts': [
          'agent-s_doctor = self_check:main',
      ],
  },
  

  After installation, users can simply run:

  agent-s_doctor
  

  to perform an environment health check.
• README.md enhancement
  Added a “Self-check” section explaining how to use the tool, including:
  • --json → outputs machine-readable diagnostics, convenient for CI/CD integration
  • --skip-screenshot → skips GUI-related checks for headless or SSH environments

Why This Matters

Many contributors run Agent S in the base environment with unsupported Python versions (outside 3.9–3.12) or without proper permissions/tools, causing runtime errors.
This self-check script detects such issues upfront and provides clear guidance to resolve them.
It also verifies required API keys (OPENAI_API_KEY, SILICONFLOW_KEY, HF_TOKEN) and suggests export commands when missing.

---

Note:
Currently, I have only tested the self-check functionality on macOS, where it works as expected.
Linux and Windows compatibility has not yet been tested, but the implementation should be cross-platform in principle. Also, I did nothing with grounding.py, it looked changed just because I forget to sync your change several hours ago, then I made a copy paste form the latest type. Below is the example of the self_check example, for the reason that I use grounding modal form other cloud company, it shows warn with HF_TOKEN.

Summary by CodeRabbit

• New Features

  • Introduces a command-line self-check tool to verify environment readiness (Python version, dependencies, API keys, permissions, logs directory, optional screenshot test).
  • Supports JSON output for automation and a headless mode to skip screenshots.
  • Provides clear pass/fail results, guidance, and CI-friendly exit codes.

• Documentation

  • Added a “Self-check (Recommended)” section under Grounding Models with usage instructions, including JSON output and headless options.

[coderabbitai[bot]]

Walkthrough

Adds a new self-check CLI utility for environment validation, integrates it into packaging as agent-s_doctor, updates README with usage, and makes a no-op code change in grounding.py.

Changes

Cohort / File(s)	Summary of Changes
Documentation README.md	Adds “Self-check (Recommended)” section describing agent-s_doctor, JSON output, and headless usage.
Self-check Utility (CLI) self_check.py	New CLI tool to validate Python version, dependencies, logs dir writability, API keys, OS-specific capabilities, and screenshot capture; supports --json and --skip-screenshot; standardized result structures and exit codes.
Packaging/Entry Points setup.py	Registers console script agent-s_doctor=self_check:main; includes self_check in py_modules.
Grounding Agent Minor Edit gui_agents/s3/agents/grounding.py	Semantically neutral change: return FAIL → return FAIL"" in done method (no functional impact).

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor User
    participant CLI as agent-s_doctor (self_check.main)
    participant Checks as collect_checks()
    participant Sys as OS/Env
    participant Render as Output (text/JSON)

    User->>CLI: Run agent-s_doctor [--json] [--skip-screenshot]
    CLI->>Checks: collect_checks(skip_screenshot)
    rect rgb(240,250,255)
        note over Checks: Core checks
        Checks->>Sys: Python version
        Checks->>Sys: Dependencies (dynamic import)
        Checks->>Sys: Logs directory access
        Checks->>Sys: API keys detection
    end
    rect rgb(245,240,255)
        note over Checks: OS-specific checks
        alt macOS
            Checks->>Sys: Accessibility / Screen Recording
        else Linux
            Checks->>Sys: scrot presence
        else Windows
            Checks->>Sys: pywinauto / pywin32
        end
    end
    opt Screenshot test
        Checks->>Sys: pyautogui screenshot
    end
    Checks-->>CLI: List[CheckResult]
    alt --json
        CLI->>Render: Serialize results as JSON
    else
        CLI->>Render: Print human-readable summary
    end
    CLI-->>User: Exit code 0 if no FAIL, else 1

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

A whisker-twitch, a tap-tap key,
I run the doctor cheerfully 🩺🐇
“Keys?” it asks. “Screens?” it probes—
Through logs and libs my warren roves.
Green lights blink—okie-dokie!
Now Agent S can brew its mochi.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the primary change by stating the addition of an environment self-check utility and even names the CLI entry point, making it clear and specific about the main feature introduced. It avoids unnecessary detail while capturing both the tool’s purpose and its diagnostic scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}