forgexa-cli 1.20.3__tar.gz → 1.20.5__tar.gz

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.20.3
+Version: 1.20.5
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT
@@ -108,6 +108,9 @@ forgexa board --project <project-id>
 | `forgexa daemon start -d` | Start daemon in background |
 | `forgexa daemon status` | Show your daemon statuses |
 | `forgexa daemon stop` | Stop local daemon |
+| `forgexa check` | Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent) |
+| `forgexa check --quick` | Same, but discovery only — no live task, no API calls |
+| `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
@@ -188,6 +191,40 @@ forgexa runtimes list
 forgexa runtimes list --all
 ```
 
+### Agent Health Check
+
+Before starting the daemon (or when tasks keep failing on this machine), verify that every
+installed agent CLI is genuinely usable — not just present on `PATH`. `forgexa check` reuses the
+exact discovery and execution code the daemon uses in production, so a `PASS` means the agent
+really works (auth, quota, and sandbox problems only ever surface on a real invocation).
+
+```bash
+# Discover installed agents, then run one real, minimal task through each to confirm it works
+forgexa check
+
+# Fast pass: discovery only, no live task, no API calls
+forgexa check --quick
+
+# Check a single agent
+forgexa check --agent claude
+```
+
+Example output:
+
+```
+Agent Availability Report
+----------------------------------------------------------------------
+  ✓  claude     v2.1.14 (Claude Code)
+  ✗  codex      not installed
+       'codex' not found on PATH, or found but 'codex --version' failed / did not
+       report a version. Install (or reinstall) the agent CLI and make sure it is
+       on PATH, then re-run 'forgexa check'.
+  ✓  kimi       v0.27.0
+----------------------------------------------------------------------
+2/3 agent(s) available for real platform tasks.
+```
+
+
 ### Supported AI Agents
 
 The daemon automatically discovers these agents if installed on your system:

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/README.md

@@ -76,6 +76,9 @@ forgexa board --project <project-id>
 | `forgexa daemon start -d` | Start daemon in background |
 | `forgexa daemon status` | Show your daemon statuses |
 | `forgexa daemon stop` | Stop local daemon |
+| `forgexa check` | Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent) |
+| `forgexa check --quick` | Same, but discovery only — no live task, no API calls |
+| `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
@@ -156,6 +159,40 @@ forgexa runtimes list
 forgexa runtimes list --all
 ```
 
+### Agent Health Check
+
+Before starting the daemon (or when tasks keep failing on this machine), verify that every
+installed agent CLI is genuinely usable — not just present on `PATH`. `forgexa check` reuses the
+exact discovery and execution code the daemon uses in production, so a `PASS` means the agent
+really works (auth, quota, and sandbox problems only ever surface on a real invocation).
+
+```bash
+# Discover installed agents, then run one real, minimal task through each to confirm it works
+forgexa check
+
+# Fast pass: discovery only, no live task, no API calls
+forgexa check --quick
+
+# Check a single agent
+forgexa check --agent claude
+```
+
+Example output:
+
+```
+Agent Availability Report
+----------------------------------------------------------------------
+  ✓  claude     v2.1.14 (Claude Code)
+  ✗  codex      not installed
+       'codex' not found on PATH, or found but 'codex --version' failed / did not
+       report a version. Install (or reinstall) the agent CLI and make sure it is
+       on PATH, then re-run 'forgexa check'.
+  ✓  kimi       v0.27.0
+----------------------------------------------------------------------
+2/3 agent(s) available for real platform tasks.
+```
+
+
 ### Supported AI Agents
 
 The daemon automatically discovers these agents if installed on your system:

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/forgexa_cli/__init__.py

@@ -1,2 +1,2 @@
 """forgexa-cli — Forgexa command-line client."""
-__version__ = "1.20.3"
+__version__ = "1.20.5"

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/forgexa_cli/daemon.py

@@ -555,7 +555,7 @@ except (ImportError, ModuleNotFoundError):
 # DAEMON_VERSION is the protocol/logic version of the daemon code.
 # Kept in sync with pyproject.toml version via bump-version.sh.
 # CLIENT_TYPE identifies which packaging/distribution this daemon runs in.
-DAEMON_VERSION = "1.20.3"
+DAEMON_VERSION = "1.20.5"
 
 
 def _detect_client_type() -> str:
@@ -773,6 +773,33 @@ class DiscoveredAgent:
     compatibility_level: str
 
 
+def _prepare_agent_command(command: list[str]) -> list[str]:
+    """Make Windows script launchers executable through their shell hosts."""
+    if sys.platform != "win32" or not command:
+        return command
+
+    suffix = Path(command[0]).suffix.lower()
+    if suffix in {".cmd", ".bat"}:
+        return [
+            os.environ.get("COMSPEC", "cmd.exe"),
+            "/d",
+            "/s",
+            "/c",
+            subprocess.list2cmdline(command),
+        ]
+    if suffix == ".ps1":
+        return [
+            "powershell.exe",
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            *command,
+        ]
+    return command
+
+
 @dataclass
 class TaskInfo:
     task_id: str
@@ -1593,21 +1620,10 @@ class AgentDiscovery:
         import re
         try:
             parts = detect_cmd.split()
-            # On Windows, agent CLIs installed via npm create .cmd wrapper scripts
-            # (e.g. %APPDATA%\npm\copilot.cmd). Python's asyncio.create_subprocess_exec
-            # calls CreateProcess which cannot execute .cmd/.bat files directly —
-            # they need cmd.exe as the interpreter. Detect and wrap automatically.
-            if sys.platform == "win32":
-                resolved = shutil.which(parts[0])
-                if resolved:
-                    ext = Path(resolved).suffix.lower()
-                    if ext in ('.cmd', '.bat'):
-                        parts = ['cmd', '/c', resolved] + parts[1:]
-                    elif ext == '.ps1':
-                        parts = [
-                            'powershell', '-NoProfile', '-NonInteractive',
-                            '-Command', resolved,
-                        ] + parts[1:]
+            resolved = shutil.which(parts[0])
+            if resolved:
+                parts[0] = resolved
+            parts = _prepare_agent_command(parts)
             proc = await asyncio.create_subprocess_exec(
                 *parts,
                 stdin=asyncio.subprocess.DEVNULL,
@@ -3920,6 +3936,22 @@ class ProcessManager:
             or any(p in error_text for p in ProcessManager.AGENT_UNAVAILABLE_PATTERNS)
         )
 
+    @staticmethod
+    def is_silent_idle_timeout(result: "TaskResult") -> bool:
+        """Return whether an agent was killed before producing any evidence.
+
+        A timeout after output or workspace changes can represent completed work
+        and must be handled by the normal recovery path. A completely silent
+        timeout instead means this specific CLI is stuck before it can begin,
+        so one alternate agent is safe to try.
+        """
+        return (
+            result.failure_code == "agent_idle_timeout"
+            and not result.stdout.strip()
+            and not result.stderr.strip()
+            and not result.files_changed
+        )
+
     @staticmethod
     def _detect_agent_output_failure(result: "TaskResult", agent_id: str) -> str | None:
         """Detect agent-level failures despite exit code 0.
@@ -4440,6 +4472,7 @@ class ProcessManager:
             "--no-session-persistence",
             "--dangerously-skip-permissions",
         ]
+        cmd = _prepare_agent_command(cmd)
 
         env = os.environ.copy()
         for key in (
@@ -4539,6 +4572,7 @@ class ProcessManager:
                 stdout=getattr(exc, "stdout", "")[-settings.AGENT_MAX_OUTPUT_SIZE:],
                 stderr=getattr(exc, "stderr", "")[-10000:],
                 error=_err,
+                failure_code="agent_idle_timeout" if isinstance(exc, _IdleTimeoutError) else "",
             )
         except Exception as exc:
             logger.exception("Claude stream error for task %s", task_id)
@@ -5160,6 +5194,7 @@ class ProcessManager:
                 _task_file = None
 
         cmd += ["-C", str(cwd), "-p", _effective_prompt]
+        cmd = _prepare_agent_command(cmd)
 
         # Log the exact invocation (redact prompt body) so operators can
         # reproduce failures manually and diagnose CLI version incompatibilities.
@@ -5345,6 +5380,7 @@ class ProcessManager:
                 stdout=getattr(exc, "stdout", "")[-settings.AGENT_MAX_OUTPUT_SIZE:],
                 stderr=getattr(exc, "stderr", "")[-10000:],
                 error=_err,
+                failure_code="agent_idle_timeout" if isinstance(exc, _IdleTimeoutError) else "",
             )
         except Exception as exc:
             logger.exception("Copilot stream error for task %s", task_id)
@@ -5383,6 +5419,7 @@ class ProcessManager:
         stream_stderr: bool = False,
     ) -> TaskResult:
         try:
+            cmd = _prepare_agent_command(cmd)
             proc = await asyncio.create_subprocess_exec(
                 *cmd,
                 stdout=asyncio.subprocess.PIPE,
@@ -5421,6 +5458,7 @@ class ProcessManager:
                 stdout=getattr(exc, "stdout", "")[-settings.AGENT_MAX_OUTPUT_SIZE:],
                 stderr=getattr(exc, "stderr", "")[-10000:],
                 error=_err,
+                failure_code="agent_idle_timeout" if isinstance(exc, _IdleTimeoutError) else "",
             )
         except Exception as exc:
             logger.exception("CLI stream error for task %s", task_id)
@@ -7786,12 +7824,21 @@ class RuntimeDaemon:
 
             tried_agents.add(agent.agent_id)
 
-            # ── Agent fallback: if agent hit rate limit or API is unavailable, try next agent ──
+            # ── Agent fallback: try another CLI after a backend failure or a fully silent hang ──
             # Guard: if the agent already produced file changes in the workspace, it DID
             # meaningful work — don't trigger fallback even if it crashed after completing.
             # Let the recovery logic (step 4.1) handle non-zero exit with committed work.
+            is_rate_limited = self.process_manager.is_rate_limited(result)
+            is_silent_idle_timeout = self.process_manager.is_silent_idle_timeout(result)
+            fallback_reason = (
+                "rate_limit"
+                if is_rate_limited
+                else "agent_idle_timeout"
+                if is_silent_idle_timeout
+                else ""
+            )
             _skip_fallback = False
-            if self.process_manager.is_rate_limited(result):
+            if fallback_reason:
                 _pre_fallback_git = await self.process_manager._collect_git_info(workspace_path)
                 _pre_fallback_committed = await self.process_manager._collect_git_info_vs_parent(
                     workspace_path,
@@ -7810,10 +7857,10 @@ class RuntimeDaemon:
                     )
                     _skip_fallback = True
 
-            if self.process_manager.is_rate_limited(result) and not _skip_fallback:
+            if fallback_reason and not _skip_fallback:
                 logger.warning(
-                    "Agent '%s' unavailable/rate-limited for task %s, attempting fallback",
-                    agent.agent_id, task.task_id,
+                    "Agent '%s' failed for task %s (%s), attempting fallback",
+                    agent.agent_id, task.task_id, fallback_reason,
                 )
                 fallback_agent = self._select_fallback_agent(
                     agent.agent_id, task.fallback_chain, tried_agents
@@ -7830,7 +7877,7 @@ class RuntimeDaemon:
                     await reporter.report_progress(
                         task.task_id, 10,
                         f"agent_fallback: retrying with {agent.agent_id}",
-                        output_lines=[f"[daemon] Agent unavailable/rate-limited, switching to {agent.agent_id}"],
+                        output_lines=[f"[daemon] Agent {fallback_reason}, switching to {agent.agent_id}"],
                     )
 
                     # Re-run with fallback agent
@@ -7877,6 +7924,9 @@ class RuntimeDaemon:
                             )
                             _line_buffer.clear()
 
+                    # A silent hang gets exactly one alternate-agent attempt.
+                    # Unlike quota failures, do not serially spend the full idle
+                    # timeout on every installed CLI when the host is offline.
                     if not self.process_manager.is_rate_limited(result):
                         break  # Success or non-retriable failure
 
@@ -8260,7 +8310,7 @@ class RuntimeDaemon:
             result.metrics["actual_agent"] = agent.agent_id
             if agent.agent_id != task.agent_type:
                 result.metrics["original_agent"] = task.agent_type
-                result.metrics["fallback_reason"] = "rate_limit"
+                result.metrics["fallback_reason"] = fallback_reason
             await reporter.report_progress(task.task_id, 100, "completed" if result.status == "success" else "failed")
             await reporter.report_complete(task.task_id, result)
 

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/forgexa_cli/main.py

@@ -24,6 +24,9 @@ Usage:
     forgexa daemon agents
     forgexa daemon restart
     forgexa daemon stop
+    forgexa check
+    forgexa check --quick
+    forgexa check --agent claude
     forgexa gates pending
     forgexa config show
     forgexa --help
@@ -1324,6 +1327,208 @@ def cmd_daemon_agents(args: argparse.Namespace) -> None:
     )
 
 
+# ── forgexa check ──
+# Verifies locally-installed agent CLIs are genuinely usable, using the exact
+# discovery (AgentDiscovery) and execution (ProcessManager.run_agent) code
+# paths the real daemon uses to run platform tasks. A binary being on PATH or
+# passing `--version` is not sufficient proof it works (auth, quota, sandbox,
+# and config problems only surface on a real invocation) — this command runs
+# one minimal real task per agent to confirm it end-to-end.
+
+_CHECK_TASK_PROMPT = (
+    "This is an automated Forgexa CLI health check, not a real task. "
+    "Do not read, create, or modify any files in this directory. "
+    "Simply reply with the single word: OK"
+)
+
+
+def _check_not_installed_reason(agent_id: str, registry: dict) -> str:
+    spec = registry.get(agent_id, {})
+    cmd = (spec.get("commands") or [agent_id])[0]
+    detect = spec.get("detect", f"{cmd} --version")
+    return (
+        f"'{cmd}' not found on PATH, or found but '{detect}' failed / did not "
+        "report a version. Install (or reinstall) the agent CLI and make sure "
+        "it is on PATH, then re-run 'forgexa check'."
+    )
+
+
+async def _live_check_agent(pm, agent, timeout: int) -> tuple[bool, str]:
+    """Run one real, minimal task through the agent CLI.
+
+    Uses ProcessManager.run_agent() — the exact same method the daemon calls
+    when the platform dispatches a real task — in an isolated scratch
+    directory so nothing in the user's real projects is touched.
+
+    Returns (available, reason). reason is empty on success.
+    """
+    import tempfile
+    from forgexa_cli.daemon import TaskInfo
+
+    workspace = Path(tempfile.mkdtemp(prefix="forgexa-check-"))
+    try:
+        subprocess.run(
+            ["git", "init", "-q"],
+            cwd=workspace, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            check=False,
+        )
+    except Exception:
+        pass
+
+    try:
+        task = TaskInfo(
+            task_id=f"check-{agent.agent_id}",
+            graph_id="forgexa-check",
+            node_type="review",
+            agent_type=agent.agent_id,
+            input_prompt=_CHECK_TASK_PROMPT,
+            input_data={},
+            timeout_seconds=timeout,
+            max_retries=0,
+            retry_count=0,
+            project={},
+            work_item={},
+        )
+        result = await pm.run_agent(agent, task, workspace)
+        if result.status == "success":
+            return True, ""
+        reason = (result.error or "").strip() or f"exited with code {result.exit_code}"
+        if reason.lower().startswith("exited with code") and (result.stderr or "").strip():
+            tail = result.stderr.strip().splitlines()[-1][:300]
+            reason = f"{reason}: {tail}"
+        return False, reason
+    except Exception as exc:
+        return False, f"health check crashed: {exc}"
+    finally:
+        shutil.rmtree(workspace, ignore_errors=True)
+
+
+async def _run_agent_check(agent_ids: list[str], quick: bool, timeout: int, narrate: bool) -> list[dict]:
+    import asyncio
+    from forgexa_cli.daemon import AgentDiscovery, ProcessManager
+
+    registry = AgentDiscovery.AGENT_REGISTRY
+    discovered = await AgentDiscovery().discover()
+    discovered_by_id = {a.agent_id: a for a in discovered}
+
+    results: list[dict] = []
+    live_jobs: dict[str, "asyncio.Task"] = {}
+    pm = ProcessManager()
+
+    for agent_id in agent_ids:
+        agent = discovered_by_id.get(agent_id)
+        results.append({
+            "agent_id": agent_id,
+            "installed": agent is not None,
+            "version": agent.version if agent else "",
+            "available": agent is not None,
+            "reason": "" if agent else _check_not_installed_reason(agent_id, registry),
+        })
+        if agent is not None and not quick:
+            live_jobs[agent_id] = asyncio.create_task(_live_check_agent(pm, agent, timeout))
+
+    if live_jobs:
+        if narrate:
+            print(
+                f"Running a live smoke-test task on {len(live_jobs)} installed agent(s) "
+                f"(per-agent timeout {timeout}s)..."
+            )
+            print()
+        for entry in results:
+            job = live_jobs.get(entry["agent_id"])
+            if job is None:
+                continue
+            ok, reason = await job
+            entry["available"] = ok
+            entry["reason"] = reason
+            if narrate:
+                print(f"  {'PASS' if ok else 'FAIL'}  {entry['agent_id']}")
+
+    return results
+
+
+def _print_check_report(results: list[dict], quick: bool) -> None:
+    fmt = _fmt()
+    if fmt == "json":
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+        return
+    if fmt == "quiet":
+        for r in results:
+            print(f"{r['agent_id']}\t{'available' if r['available'] else 'unavailable'}")
+        return
+
+    print()
+    print("Agent Availability Report")
+    print("-" * 70)
+    for r in results:
+        mark = "✓" if r["available"] else "✗"
+        label = f"v{r['version']}" if r.get("version") else "not installed"
+        print(f"  {mark}  {r['agent_id']:<10} {label}")
+        if r["reason"]:
+            print(f"       {r['reason']}")
+    print("-" * 70)
+
+    usable = sum(1 for r in results if r["available"])
+    total = len(results)
+    print(f"{usable}/{total} agent(s) available for real platform tasks.")
+    if quick:
+        print(
+            "(ran with --quick: discovery only, no live task executed — "
+            "run 'forgexa check' without --quick to confirm agents really work)"
+        )
+    if usable == 0:
+        print()
+        print("No usable agents on this machine — tasks dispatched here will fail.")
+        print("Install at least one supported agent CLI (Claude Code, Codex, OpenCode,")
+        print("Gemini CLI, Kimi Code, or GitHub Copilot CLI), then re-run: forgexa check")
+
+
+def cmd_check(args: argparse.Namespace) -> None:
+    """Verify locally-installed AI agent CLIs are genuinely usable for platform tasks.
+
+    Reuses the exact discovery (AgentDiscovery) and execution
+    (ProcessManager.run_agent) code paths the real daemon uses to run tasks,
+    so a PASS here means the agent actually works end-to-end — not just that
+    a binary happens to exist on PATH.
+    """
+    import asyncio
+
+    os.environ.setdefault("DAEMON_NO_CONSOLE_LOG", "1")
+    from forgexa_cli.daemon import AgentDiscovery
+
+    only_agent = getattr(args, "agent", None)
+    quick = bool(getattr(args, "quick", False))
+    timeout = getattr(args, "timeout", None) or 90
+
+    known_ids = list(AgentDiscovery.AGENT_REGISTRY.keys())
+    if only_agent:
+        if only_agent not in known_ids:
+            print(f"Unknown agent '{only_agent}'. Known agents: {', '.join(known_ids)}", file=sys.stderr)
+            sys.exit(1)
+        agent_ids = [only_agent]
+    else:
+        agent_ids = known_ids
+
+    narrate = _fmt() == "table"
+    if narrate:
+        print("Scanning for installed agent CLIs...")
+        if not quick:
+            print("Each installed agent will run one real, minimal task to confirm it works")
+            print(f"(this performs a live API call per agent; per-agent timeout: {timeout}s).")
+        print()
+
+    try:
+        results = asyncio.run(_run_agent_check(agent_ids, quick, timeout, narrate))
+    except Exception as exc:
+        print(f"Agent check failed unexpectedly: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    _print_check_report(results, quick=quick)
+
+    if not any(r["available"] for r in results):
+        sys.exit(1)
+
+
 def cmd_runtimes_list(args: argparse.Namespace) -> None:
     runtimes = _get_runtimes(include_all=getattr(args, "all", False))
     if not runtimes:
@@ -1737,6 +1942,21 @@ def main() -> None:
     )
     _agents_sc.add_argument("--all", action="store_true", help="Include all users' runtimes (admin only)")
 
+    # check
+    check_p = sub.add_parser(
+        "check",
+        help="Verify locally-installed agent CLIs are genuinely usable for platform tasks",
+    )
+    check_p.add_argument("--agent", default=None, help="Check only this agent (e.g. claude, codex, kimi)")
+    check_p.add_argument(
+        "--quick", action="store_true",
+        help="Discovery only — skip the live task execution test (no API calls)",
+    )
+    check_p.add_argument(
+        "--timeout", type=int, default=90, metavar="SECONDS",
+        help="Per-agent timeout for the live execution test (default: 90)",
+    )
+
     # runtimes
     rt_p = sub.add_parser("runtimes", help="Runtime management")
     rt_sub = rt_p.add_subparsers(dest="rt_cmd")
@@ -1857,6 +2077,7 @@ def main() -> None:
         "status":  cmd_daemon_status,
         "logs":    cmd_daemon_logs,
         "agents":  cmd_daemon_agents,
+        "check":   cmd_check,
         "runtimes": lambda a: {
             "list": cmd_runtimes_list,
         }.get(a.rt_cmd, lambda _: rt_p.print_help())(a),

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/forgexa_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.20.3
+Version: 1.20.5
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT
@@ -108,6 +108,9 @@ forgexa board --project <project-id>
 | `forgexa daemon start -d` | Start daemon in background |
 | `forgexa daemon status` | Show your daemon statuses |
 | `forgexa daemon stop` | Stop local daemon |
+| `forgexa check` | Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent) |
+| `forgexa check --quick` | Same, but discovery only — no live task, no API calls |
+| `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
@@ -188,6 +191,40 @@ forgexa runtimes list
 forgexa runtimes list --all
 ```
 
+### Agent Health Check
+
+Before starting the daemon (or when tasks keep failing on this machine), verify that every
+installed agent CLI is genuinely usable — not just present on `PATH`. `forgexa check` reuses the
+exact discovery and execution code the daemon uses in production, so a `PASS` means the agent
+really works (auth, quota, and sandbox problems only ever surface on a real invocation).
+
+```bash
+# Discover installed agents, then run one real, minimal task through each to confirm it works
+forgexa check
+
+# Fast pass: discovery only, no live task, no API calls
+forgexa check --quick
+
+# Check a single agent
+forgexa check --agent claude
+```
+
+Example output:
+
+```
+Agent Availability Report
+----------------------------------------------------------------------
+  ✓  claude     v2.1.14 (Claude Code)
+  ✗  codex      not installed
+       'codex' not found on PATH, or found but 'codex --version' failed / did not
+       report a version. Install (or reinstall) the agent CLI and make sure it is
+       on PATH, then re-run 'forgexa check'.
+  ✓  kimi       v0.27.0
+----------------------------------------------------------------------
+2/3 agent(s) available for real platform tasks.
+```
+
+
 ### Supported AI Agents
 
 The daemon automatically discovers these agents if installed on your system:

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/forgexa_cli.egg-info/SOURCES.txt

@@ -11,4 +11,5 @@ forgexa_cli.egg-info/dependency_links.txt
 forgexa_cli.egg-info/entry_points.txt
 forgexa_cli.egg-info/requires.txt
 forgexa_cli.egg-info/top_level.txt
-tests/test_auth_and_runtime_commands.py
+tests/test_auth_and_runtime_commands.py
+tests/test_check_command.py

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forgexa-cli"
-version = "1.20.3"
+version = "1.20.5"
 description = "Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform"
 requires-python = ">=3.9"
 license = "MIT"

{forgexa_cli-1.20.3 → forgexa_cli-1.20.5}/tests/test_auth_and_runtime_commands.py

@@ -59,6 +59,26 @@ def test_login_persists_refresh_token(tmp_path: Path, monkeypatch: pytest.Monkey
     assert (tmp_path / ".forgexa" / "token").read_text() == "access-1"
 
 
+@pytest.mark.parametrize("suffix", [".cmd", ".bat"])
+def test_windows_batch_agent_commands_use_cmd_exe(
+    suffix: str, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    launcher = r"C:\Windows\System32\cmd.exe"
+    command = [rf"C:\Users\agent\AppData\Roaming\npm\copilot{suffix}", "--version"]
+    monkeypatch.setattr(daemon.sys, "platform", "win32")
+    monkeypatch.setenv("COMSPEC", launcher)
+
+    result = daemon._prepare_agent_command(command)
+
+    assert result == [
+        launcher,
+        "/d",
+        "/s",
+        "/c",
+        daemon.subprocess.list2cmdline(command),
+    ]
+
+
 def test_get_retries_once_after_refresh_on_401(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,

forgexa_cli-1.20.5/tests/test_check_command.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from forgexa_cli import daemon, main
+
+
+def _small_registry() -> dict:
+    """A small subset of AGENT_REGISTRY, isolated from the real one so these
+    tests don't depend on (or break from) future registry additions."""
+    return {
+        "claude": {"commands": ["claude"], "detect": "claude --version"},
+        "kimi": {"commands": ["kimi"], "detect": "kimi --version"},
+        "codex": {"commands": ["codex"], "detect": "codex --version"},
+    }
+
+
+def _agent(agent_id: str, version: str = "1.0.0") -> daemon.DiscoveredAgent:
+    return daemon.DiscoveredAgent(
+        agent_id=agent_id,
+        command=agent_id,
+        version=version,
+        invoke_modes=["cli"],
+        compatibility_level="L2",
+    )
+
+
+def test_check_quick_reports_installed_and_missing_agents(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("claude"), _agent("kimi")]),
+    )
+    run_agent_mock = AsyncMock()
+    monkeypatch.setattr(daemon.ProcessManager, "run_agent", run_agent_mock)
+
+    main.cmd_check(SimpleNamespace(agent=None, quick=True, timeout=90))
+
+    # --quick must never invoke the live execution path.
+    run_agent_mock.assert_not_called()
+
+    out = capsys.readouterr().out
+    assert "✓  claude" in out
+    assert "✓  kimi" in out
+    assert "✗  codex" in out
+    assert "not installed" in out
+    assert "2/3 agent(s) available" in out
+
+
+def test_check_live_mode_passes_on_success(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("claude")]),
+    )
+    run_agent_mock = AsyncMock(
+        return_value=daemon.TaskResult(status="success", exit_code=0, stdout="OK", stderr="")
+    )
+    monkeypatch.setattr(daemon.ProcessManager, "run_agent", run_agent_mock)
+
+    main.cmd_check(SimpleNamespace(agent="claude", quick=False, timeout=5))
+
+    run_agent_mock.assert_awaited_once()
+    called_agent, called_task, _called_workspace = run_agent_mock.await_args.args
+    assert called_agent.agent_id == "claude"
+    assert called_task.input_prompt == main._CHECK_TASK_PROMPT
+    assert called_task.timeout_seconds == 5
+
+    out = capsys.readouterr().out
+    assert "PASS  claude" in out
+    assert "✓  claude" in out
+    assert "1/1 agent(s) available" in out
+
+
+def test_check_live_mode_reports_failure_reason_and_exits_nonzero(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("kimi")]),
+    )
+    monkeypatch.setattr(
+        daemon.ProcessManager, "run_agent",
+        AsyncMock(return_value=daemon.TaskResult(
+            status="failed", exit_code=-1, stdout="", stderr="",
+            error="Kimi authentication required: please run 'kimi' and log in.",
+        )),
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        main.cmd_check(SimpleNamespace(agent="kimi", quick=False, timeout=5))
+
+    assert exc_info.value.code == 1
+    out = capsys.readouterr().out
+    assert "✗  kimi" in out
+    assert "Kimi authentication required" in out
+    assert "0/1 agent(s) available" in out
+
+
+def test_check_unknown_agent_exits_with_error(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+
+    with pytest.raises(SystemExit) as exc_info:
+        main.cmd_check(SimpleNamespace(agent="bogus", quick=True, timeout=90))
+
+    assert exc_info.value.code == 1
+    err = capsys.readouterr().err
+    assert "Unknown agent 'bogus'" in err
+
+
+def test_check_json_output_is_parseable(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("claude", version="2.0.0")]),
+    )
+    monkeypatch.setattr(main, "_output_format", "json")
+
+    main.cmd_check(SimpleNamespace(agent="claude", quick=True, timeout=90))
+
+    out = capsys.readouterr().out
+    payload = json.loads(out)
+    assert payload == [{
+        "agent_id": "claude",
+        "installed": True,
+        "version": "2.0.0",
+        "available": True,
+        "reason": "",
+    }]