forgexa-cli 1.20.4__tar.gz → 1.21.0__tar.gz

{forgexa_cli-1.20.4 → forgexa_cli-1.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.20.4
+Version: 1.21.0
 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
@@ -113,6 +113,7 @@ forgexa board --project <project-id>
 | `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 version --status` | Show auto-upgrade status (mode, active/last success/last failure) |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
 | `forgexa upgrade --target-version <version>` | Upgrade or roll forward to a specific release |
 
@@ -136,12 +137,39 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### Automatic Background Upgrade
+
+By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.
+
+```bash
+# Back to notify-only: check and print a footer notice, but never install automatically
+forgexa config set auto-upgrade notify
+
+# Disable update checks entirely
+forgexa config set auto-upgrade off
+
+# Re-enable silent background installs (the default)
+forgexa config set auto-upgrade silent
+```
+
+| Mode | Check | Silent background install | Footer notice |
+|------|-------|----------------------------|----------------|
+| `silent` (default) | ✅ | ✅ | ✅ (one-time "updated to vX" notice next run) |
+| `notify` | ✅ | ❌ | ✅ |
+| `off` | ❌ | ❌ | ❌ |
+
+A silent install only ever runs for a safe, already-detected install source (pip/pipx — the same sources `forgexa upgrade` supports), never while a local daemon is running (it's skipped and retried on a later invocation instead), never in CI or a non-interactive/`--format json` session, and gives up automatically after 2 consecutive failures for the same target version. Check `forgexa version --status` to see the current mode and the last install attempt's outcome, or `~/.forgexa/upgrade.log` for the raw install output.
+
+`FORGEXA_AUTO_UPGRADE=<silent|notify|off>` overrides the config file for the current shell session; the legacy `FORGEXA_NO_UPDATE_CHECK=1` remains a supported alias for `off`.
+
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `FORGEXA_SERVER_URL` | `http://localhost:8000` | `Server base URL |
 | `FORGEXA_TOKEN` | — | Bearer token (overrides `~/.forgexa/token`) |
+| `FORGEXA_AUTO_UPGRADE` | — | Override `auto_upgrade` (`silent`\|`notify`\|`off`) for this session |
+| `FORGEXA_NO_UPDATE_CHECK` | — | Legacy alias for `FORGEXA_AUTO_UPGRADE=off` |
 
 ## Output Format
 

{forgexa_cli-1.20.4 → forgexa_cli-1.21.0}/README.md

@@ -81,6 +81,7 @@ forgexa board --project <project-id>
 | `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 version --status` | Show auto-upgrade status (mode, active/last success/last failure) |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
 | `forgexa upgrade --target-version <version>` | Upgrade or roll forward to a specific release |
 
@@ -104,12 +105,39 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### Automatic Background Upgrade
+
+By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.
+
+```bash
+# Back to notify-only: check and print a footer notice, but never install automatically
+forgexa config set auto-upgrade notify
+
+# Disable update checks entirely
+forgexa config set auto-upgrade off
+
+# Re-enable silent background installs (the default)
+forgexa config set auto-upgrade silent
+```
+
+| Mode | Check | Silent background install | Footer notice |
+|------|-------|----------------------------|----------------|
+| `silent` (default) | ✅ | ✅ | ✅ (one-time "updated to vX" notice next run) |
+| `notify` | ✅ | ❌ | ✅ |
+| `off` | ❌ | ❌ | ❌ |
+
+A silent install only ever runs for a safe, already-detected install source (pip/pipx — the same sources `forgexa upgrade` supports), never while a local daemon is running (it's skipped and retried on a later invocation instead), never in CI or a non-interactive/`--format json` session, and gives up automatically after 2 consecutive failures for the same target version. Check `forgexa version --status` to see the current mode and the last install attempt's outcome, or `~/.forgexa/upgrade.log` for the raw install output.
+
+`FORGEXA_AUTO_UPGRADE=<silent|notify|off>` overrides the config file for the current shell session; the legacy `FORGEXA_NO_UPDATE_CHECK=1` remains a supported alias for `off`.
+
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `FORGEXA_SERVER_URL` | `http://localhost:8000` | `Server base URL |
 | `FORGEXA_TOKEN` | — | Bearer token (overrides `~/.forgexa/token`) |
+| `FORGEXA_AUTO_UPGRADE` | — | Override `auto_upgrade` (`silent`\|`notify`\|`off`) for this session |
+| `FORGEXA_NO_UPDATE_CHECK` | — | Legacy alias for `FORGEXA_AUTO_UPGRADE=off` |
 
 ## Output Format
 

{forgexa_cli-1.20.4 → forgexa_cli-1.21.0}/forgexa_cli/__init__.py

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

forgexa_cli-1.21.0/forgexa_cli/autoupgrade.py

@@ -0,0 +1,219 @@
+"""Auto-upgrade infrastructure for forgexa-cli.
+
+Holds the pieces that are reusable/testable in isolation: resolving the
+effective ``auto_upgrade`` mode (env var > ``~/.forgexa/config`` > built-in
+default), and the on-disk state/lock files used to coordinate silent
+background installs across concurrent CLI invocations.
+
+The actual "check + maybe install" orchestration lives in ``main.py`` (it
+needs to call ``_build_upgrade_plan()``, daemon helpers, etc. which live
+there); this module only provides the primitives.
+
+See docs/designs/cli-auto-upgrade-design.md for the full design and rationale.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+# ── auto_upgrade mode resolution ──────────────────────────────────────────────
+
+VALID_MODES = ("silent", "notify", "off")
+DEFAULT_MODE = "silent"
+
+# Failure/staleness tuning (see docs/designs/cli-auto-upgrade-design.md §4.7).
+FAILURE_BACKOFF_LIMIT = 2
+ACTIVE_INSTALL_STALE_SECONDS = 30 * 60
+LOCK_STALE_SECONDS = 30 * 60
+
+
+def resolve_auto_upgrade_mode(config: dict) -> str:
+    """Resolve the effective ``auto_upgrade`` mode.
+
+    Precedence: ``FORGEXA_NO_UPDATE_CHECK`` (legacy total kill-switch, wins
+    over everything) > ``FORGEXA_AUTO_UPGRADE`` env var >
+    ``~/.forgexa/config``'s ``auto_upgrade`` key > built-in default
+    (``"notify"``).
+    """
+    if os.environ.get("FORGEXA_NO_UPDATE_CHECK"):
+        return "off"
+    env = os.environ.get("FORGEXA_AUTO_UPGRADE", "").strip().lower()
+    if env in VALID_MODES:
+        return env
+    configured = str(config.get("auto_upgrade") or "").strip().lower()
+    if configured in VALID_MODES:
+        return configured
+    return DEFAULT_MODE
+
+
+def describe_auto_upgrade_source(config: dict) -> str:
+    """Human-readable description of where the effective mode came from.
+
+    Mirrors the precedence order in ``resolve_auto_upgrade_mode`` for
+    display purposes (``forgexa config show``).
+    """
+    if os.environ.get("FORGEXA_NO_UPDATE_CHECK"):
+        return "FORGEXA_NO_UPDATE_CHECK env var"
+    env = os.environ.get("FORGEXA_AUTO_UPGRADE", "").strip().lower()
+    if env in VALID_MODES:
+        return "FORGEXA_AUTO_UPGRADE env var"
+    configured = str(config.get("auto_upgrade") or "").strip().lower()
+    if configured in VALID_MODES:
+        return "~/.forgexa/config"
+    return "built-in default"
+
+
+# ── State file (~/.forgexa/upgrade-state.json) ────────────────────────────────
+#
+# Tracks the outcome of silent background install attempts:
+#   active       — an install currently in progress: {version, started_at}
+#   last_failure — most recent failure: {version, failed_at, attempts}
+#   last_success — most recent success: {version, installed_at, notified}
+
+
+def _state_path() -> Path:
+    return Path.home() / ".forgexa" / "upgrade-state.json"
+
+
+def empty_state() -> dict:
+    return {"active": None, "last_failure": None, "last_success": None}
+
+
+def read_state() -> dict:
+    """Return the upgrade state dict. Never raises; missing/corrupt -> empty shape."""
+    try:
+        data = json.loads(_state_path().read_text())
+        if isinstance(data, dict):
+            state = empty_state()
+            state.update({k: data.get(k) for k in state if k in data})
+            return state
+    except Exception:
+        pass
+    return empty_state()
+
+
+def write_state(state: dict) -> None:
+    """Atomically write the upgrade state. Never raises."""
+    try:
+        path = _state_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(state, indent=2))
+        tmp.replace(path)
+        path.chmod(0o600)
+    except Exception:
+        pass
+
+
+def failure_attempts_for(state: dict, target_version: str) -> int:
+    """How many consecutive failures are recorded for `target_version`.
+
+    Resets to 0 as soon as a different (e.g. newer) target version is being
+    considered, so a fixed release doesn't stay permanently backed off.
+    """
+    failure = state.get("last_failure") or {}
+    if failure.get("version") == target_version:
+        return int(failure.get("attempts") or 0)
+    return 0
+
+
+def has_fresh_active_install(state: dict, target_version: str) -> bool:
+    """Whether an install for `target_version` is already in progress and not stale."""
+    active = state.get("active") or {}
+    if active.get("version") != target_version:
+        return False
+    started_at = active.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return False
+    return (time.time() - started_at) < ACTIVE_INSTALL_STALE_SECONDS
+
+
+# ── Lock file (~/.forgexa/upgrade.lock) ────────────────────────────────────────
+#
+# Prevents two concurrent CLI invocations from both starting a background
+# install. Content is `{version, pid, started_at}`; staleness is judged by
+# age first, and by whether `pid` is still alive as a secondary signal.
+
+
+def _lock_path() -> Path:
+    return Path.home() / ".forgexa" / "upgrade.lock"
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _lock_is_stale(path: Path) -> bool:
+    try:
+        payload = json.loads(path.read_text())
+    except Exception:
+        return True  # Unparseable lock content — safe to reclaim.
+
+    pid = payload.get("pid")
+    if isinstance(pid, int) and not _pid_alive(pid):
+        return True
+
+    started_at = payload.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return True
+    return (time.time() - started_at) >= LOCK_STALE_SECONDS
+
+
+def _write_lock_atomically(path: Path, target_version: str) -> bool:
+    payload = json.dumps(
+        {"version": target_version, "pid": os.getpid(), "started_at": time.time()}
+    ).encode("utf-8")
+    try:
+        fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except OSError:
+        return False
+    try:
+        os.write(fd, payload)
+    finally:
+        os.close(fd)
+    return True
+
+
+def try_acquire_lock(target_version: str) -> bool:
+    """Attempt to atomically create the upgrade lock file.
+
+    Returns True on success (caller must call ``release_lock()`` when done),
+    or False if another (non-stale) install is already in progress. A stale
+    lock is reclaimed automatically. Never raises.
+    """
+    path = _lock_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return False
+
+    if _write_lock_atomically(path, target_version):
+        return True
+
+    if not path.exists() or not _lock_is_stale(path):
+        return False
+
+    # Stale lock — reclaim it. A concurrent racer may win this instead; that's
+    # fine, at most one of us proceeds and the other simply skips this round.
+    try:
+        path.unlink()
+    except OSError:
+        pass
+    return _write_lock_atomically(path, target_version)
+
+
+def release_lock() -> None:
+    try:
+        _lock_path().unlink(missing_ok=True)
+    except OSError:
+        pass

{forgexa_cli-1.20.4 → forgexa_cli-1.21.0}/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.4"
+DAEMON_VERSION = "1.21.0"
 
 
 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)