gpu4agents 0.5.0__py3-none-any.whl

gpu4agents/__init__.py

@@ -0,0 +1,5 @@
+"""GPU for Agents: GPUs your agent rents on its own, billed only while they work."""
+
+__version__ = "0.5.0"
+
+__all__ = ["__version__"]

gpu4agents/__main__.py

@@ -0,0 +1,4 @@
+from .cli.main import main
+
+if __name__ == "__main__":
+    main()

gpu4agents/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent integrations: the local MCP server, the bundled skill and their installer."""

gpu4agents/agent/install.py

@@ -0,0 +1,173 @@
+"""`gpu agent install`: put the skill and the MCP server where agents look for them.
+
+One skill copy, in ``.claude/skills/gpu/`` (or ``~/.claude/skills/gpu/``),
+serves both Claude Code and Cursor, which also reads Claude's skill
+directories. The MCP server is registered per client:
+
+- claude:  ``.mcp.json`` in the project; with --global, ``claude mcp add -s user``
+- cursor:  ``.cursor/mcp.json`` in the project, or ``~/.cursor/mcp.json``
+- desktop: Claude Desktop's ``claude_desktop_config.json``, pinned to this
+  project, plus a zip of the skill to upload in Settings
+
+Existing config files are merged, never replaced: only the ``gpu`` server
+entry is written.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+from typing import Any, Optional
+
+from ..core.errors import ConfigError
+from ..core.paths import gpu_home
+
+SERVER_NAME = "gpu"
+SKILL_NAME = "gpu"
+TARGETS = ("claude", "cursor", "desktop")
+
+
+def skill_source() -> Path:
+    return Path(__file__).parent / "skill" / "SKILL.md"
+
+
+def skill_text() -> str:
+    return skill_source().read_text()
+
+
+def gpu_command(portable: bool) -> list[str]:
+    """How a client starts `gpu`.
+
+    A project file that may be committed says plain ``gpu`` when it is on
+    PATH; anything machine-local uses an absolute path, because GUI apps
+    (Claude Desktop, Cursor) do not get the shell's PATH.
+    """
+    found = shutil.which("gpu")
+    if found and portable:
+        return ["gpu"]
+    if found:
+        return [str(Path(found).resolve())]
+    return [sys.executable, "-m", "gpu4agents"]
+
+
+def desktop_config_path() -> Path:
+    system = platform.system()
+    if system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if system == "Windows":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "Claude" / "claude_desktop_config.json"
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return (Path(base) if base else Path.home() / ".config") / "Claude" / "claude_desktop_config.json"
+
+
+def merge_server(path: Path, entry: dict[str, Any]) -> str:
+    """Write ``mcpServers.gpu`` into a JSON config. Returns created/updated/unchanged."""
+    data: dict[str, Any] = {}
+    if path.is_file():
+        text = path.read_text().strip()
+        if text:
+            try:
+                data = json.loads(text)
+            except ValueError as exc:
+                raise ConfigError(f"{path} is not valid JSON ({exc}); fix it or add the gpu server by hand") from exc
+        if not isinstance(data, dict):
+            raise ConfigError(f"{path} does not hold a JSON object")
+    servers = data.setdefault("mcpServers", {})
+    if not isinstance(servers, dict):
+        raise ConfigError(f"{path}: mcpServers is not an object")
+    if servers.get(SERVER_NAME) == entry:
+        return "unchanged"
+    action = "updated" if SERVER_NAME in servers else "created"
+    servers[SERVER_NAME] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    return action
+
+
+def write_skill(directory: Path) -> str:
+    target = directory / SKILL_NAME / "SKILL.md"
+    text = skill_text()
+    if target.is_file() and target.read_text() == text:
+        return "unchanged"
+    action = "updated" if target.exists() else "created"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text)
+    return action
+
+
+def write_skill_zip(path: Path) -> str:
+    """The skill as Claude Desktop / claude.ai expect an upload: a folder in a zip."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr(f"{SKILL_NAME}/SKILL.md", skill_text())
+    return "created"
+
+
+def install(
+    targets: list[str],
+    project_dir: Path,
+    global_scope: bool = False,
+    run=subprocess.run,
+) -> dict[str, Any]:
+    """Install for each target. ``run`` is a seam for tests (``claude mcp add``)."""
+    unknown = [t for t in targets if t not in TARGETS]
+    if unknown:
+        raise ConfigError(f"unknown target {', '.join(unknown)} (choose from {', '.join(TARGETS)})")
+    project_dir = project_dir.resolve()
+    done: list[dict[str, Any]] = []
+    notes: list[str] = []
+
+    if "claude" in targets or "cursor" in targets:
+        skills = (Path.home() if global_scope else project_dir) / ".claude" / "skills"
+        done.append({"what": "skill (Claude Code, Cursor)", "path": str(skills / SKILL_NAME / "SKILL.md"), "action": write_skill(skills)})
+
+    if "claude" in targets:
+        if global_scope:
+            command = gpu_command(portable=False)
+            argv = ["claude", "mcp", "add", "--scope", "user", SERVER_NAME, "--", *command, "mcp"]
+            if shutil.which("claude"):
+                # `add` refuses an existing name; replace it so a reinstall picks up a new path.
+                run(["claude", "mcp", "remove", "--scope", "user", SERVER_NAME], capture_output=True, text=True)
+                proc = run(argv, capture_output=True, text=True)
+                if proc.returncode != 0:
+                    raise ConfigError(f"`{' '.join(argv)}` failed: {(proc.stderr or proc.stdout).strip()}")
+                done.append({"what": "MCP server (Claude Code, user scope)", "path": "claude mcp", "action": "created"})
+            else:
+                notes.append(f"claude CLI not found; register the server with: {' '.join(argv)}")
+        else:
+            command = gpu_command(portable=True)
+            entry = {"command": command[0], "args": [*command[1:], "mcp"]}
+            path = project_dir / ".mcp.json"
+            done.append({"what": "MCP server (Claude Code)", "path": str(path), "action": merge_server(path, entry)})
+            notes.append("Claude Code asks once to approve the project's .mcp.json servers")
+
+    if "cursor" in targets:
+        command = gpu_command(portable=not global_scope)
+        entry = {
+            "type": "stdio",
+            "command": command[0],
+            "args": [*command[1:], "mcp", "--project", "${workspaceFolder}"],
+        }
+        path = (Path.home() if global_scope else project_dir) / ".cursor" / "mcp.json"
+        done.append({"what": "MCP server (Cursor)", "path": str(path), "action": merge_server(path, entry)})
+
+    if "desktop" in targets:
+        command = gpu_command(portable=False)
+        entry = {"command": command[0], "args": [*command[1:], "mcp", "--project", str(project_dir)]}
+        path = desktop_config_path()
+        done.append({"what": "MCP server (Claude Desktop)", "path": str(path), "action": merge_server(path, entry)})
+        archive = gpu_home() / "gpu-skill.zip"
+        done.append({"what": "skill zip (Claude Desktop)", "path": str(archive), "action": write_skill_zip(archive)})
+        notes.append(f"Claude Desktop: restart it, then upload {archive} under Settings > Capabilities > Skills")
+        notes.append(
+            "Claude Desktop does not get your shell's environment: keep VAST_API_KEY in the "
+            "project .env or ~/.gpu/credentials"
+        )
+
+    return {"installed": done, "notes": notes}

gpu4agents/agent/jobs.py

@@ -0,0 +1,193 @@
+"""`gpu setup` in the background, for callers that cannot block for 15 minutes.
+
+An MCP tool call times out long before a first setup finishes, so the MCP
+server starts setup as a detached job and reports on it when asked again.
+The job outlives the server: a client that disconnects mid-setup leaves a
+machine that either finishes booting (and is then stopped by its watchdog
+when nobody uses it) or is destroyed by setup's own failure cleanup.
+
+Files, under the project's ``.gpu/jobs/``:
+
+- ``setup.json``  pid, argv and start time
+- ``setup.out``   the command's stdout (one JSON document with --json)
+- ``setup.err``   its stderr (progress is suppressed; errors land here)
+- ``setup.rc``    the exit code, written last, when the command ends
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+from ..core.paths import project_state_dir
+
+JOB_DIRNAME = "jobs"
+ERROR_TAIL_LINES = 40
+
+
+def _alive(pid: int) -> bool:
+    if os.name == "nt":  # signal 0 is CTRL_C_EVENT on Windows; trust the rc file
+        return True
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _tail(path: Path, lines: int) -> list[str]:
+    try:
+        text = path.read_text(errors="replace")
+    except OSError:
+        return []
+    return [line for line in text.splitlines() if line.strip()][-lines:]
+
+
+class Job:
+    """One named background command per project (only ``setup`` today)."""
+
+    def __init__(self, project_dir: Path, name: str = "setup") -> None:
+        self.dir = project_state_dir(Path(project_dir)) / JOB_DIRNAME
+        self.name = name
+        self.meta_path = self.dir / f"{name}.json"
+        self.out_path = self.dir / f"{name}.out"
+        self.err_path = self.dir / f"{name}.err"
+        self.rc_path = self.dir / f"{name}.rc"
+        self._proc: Optional[subprocess.Popen] = None
+
+    def meta(self) -> Optional[dict[str, Any]]:
+        try:
+            return json.loads(self.meta_path.read_text())
+        except (OSError, ValueError):
+            return None
+
+    def exit_code(self) -> Optional[int]:
+        try:
+            return int(self.rc_path.read_text().strip())
+        except (OSError, ValueError):
+            return None
+
+    def running(self) -> bool:
+        meta = self.meta()
+        if meta is None or self.exit_code() is not None:
+            return False
+        if self._proc is not None and self._proc.poll() is not None:
+            return False  # reaped here: our own child never lingers as a zombie
+        return _alive(int(meta["pid"]))
+
+    def start(self, argv: Sequence[str], cwd: Path) -> dict[str, Any]:
+        """Start ``argv`` detached. The caller checks ``running()`` first."""
+        self.dir.mkdir(parents=True, exist_ok=True)
+        for path in (self.out_path, self.err_path, self.rc_path):
+            path.unlink(missing_ok=True)
+        runner = [sys.executable, "-m", "gpu4agents.agent.jobs", str(self.dir), self.name, "--", *argv]
+        kwargs: dict[str, Any] = {}
+        if os.name == "nt":
+            kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
+                subprocess, "CREATE_NEW_PROCESS_GROUP", 0
+            )
+        else:
+            kwargs["start_new_session"] = True
+        self._proc = subprocess.Popen(
+            runner,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            **kwargs,
+        )
+        meta = {"pid": self._proc.pid, "argv": list(argv), "started_at": time.time()}
+        self.meta_path.write_text(json.dumps(meta))
+        return meta
+
+    def wait(self, seconds: float, poll: float = 2.0) -> bool:
+        """Wait up to ``seconds`` for the job to end. True when it has."""
+        deadline = time.monotonic() + max(0.0, seconds)
+        while self.running():
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(min(poll, max(0.05, deadline - time.monotonic())))
+        return True
+
+    def cancel(self, timeout: float = 120.0) -> bool:
+        """Interrupt a running job like Ctrl-C and wait for it to clean up.
+
+        ``gpu setup`` destroys the machine it was booting when interrupted, so
+        a cancelled setup leaves nothing billing. True when the job has ended.
+        """
+        meta = self.meta()
+        if meta is None or not self.running():
+            return True
+        pid = int(meta["pid"])
+        try:
+            if os.name == "nt":
+                os.kill(pid, signal.CTRL_BREAK_EVENT)
+            else:
+                os.killpg(pid, signal.SIGINT)  # the runner leads the group (start_new_session)
+        except (ProcessLookupError, PermissionError, OSError):
+            return not self.running()
+        return self.wait(timeout, poll=1.0)
+
+    def report(self) -> dict[str, Any]:
+        """``status`` is none, running, succeeded, failed or lost (died without a code)."""
+        meta = self.meta()
+        if meta is None:
+            return {"status": "none"}
+        started = float(meta.get("started_at") or 0)
+        report: dict[str, Any] = {
+            "pid": meta.get("pid"),
+            "started_at": started,
+            "elapsed_s": round(time.time() - started, 1) if started else None,
+        }
+        if self.running():
+            report["status"] = "running"
+            return report
+        code = self.exit_code()
+        if code is None:
+            report["status"] = "lost"
+        else:
+            report["status"] = "succeeded" if code == 0 else "failed"
+            report["exit_code"] = code
+            report["finished_at"] = self.rc_path.stat().st_mtime
+            report["elapsed_s"] = round(report["finished_at"] - started, 1) if started else None
+        try:
+            report["result"] = json.loads(self.out_path.read_text())
+        except (OSError, ValueError):
+            pass
+        if report["status"] != "succeeded":
+            report["stderr_tail"] = _tail(self.err_path, ERROR_TAIL_LINES)
+        return report
+
+
+def _main(argv: list[str]) -> int:
+    """``python -m gpu4agents.agent.jobs DIR NAME -- CMD...``: run CMD, record its exit code."""
+    directory, name = Path(argv[0]), argv[1]
+    command = argv[3:] if len(argv) > 2 and argv[2] == "--" else argv[2:]
+    # A cancel sends SIGINT to the whole group. The runner must outlive it to
+    # record the exit code, and must not kill the command while it cleans up.
+    # A Python handler (not SIG_IGN) resets to the default in the child on exec.
+    signal.signal(signal.SIGINT, lambda signum, frame: None)
+    with open(directory / f"{name}.out", "wb") as out, open(directory / f"{name}.err", "wb") as err:
+        try:
+            proc = subprocess.Popen(command, stdout=out, stderr=err, stdin=subprocess.DEVNULL)
+        except OSError as exc:
+            err.write(f"error: could not start {command[0]}: {exc}\n".encode())
+            code = 127
+        else:
+            code = proc.wait()
+    tmp = directory / f"{name}.rc.tmp"
+    tmp.write_text(str(code))
+    tmp.replace(directory / f"{name}.rc")
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv[1:]))