hypha-debugger 0.1.11__tar.gz → 0.2.0__tar.gz

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypha-debugger
-Version: 0.1.11
+Version: 0.2.0
 Summary: Injectable debugger for Python processes and AI agents, powered by Hypha RPC
 Author: Amun AI AB
 License: MIT

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/hypha_debugger/__init__.py

@@ -12,5 +12,5 @@ Usage (sync):
 
 from hypha_debugger.debugger import start_debugger, start_debugger_sync, DebugSession
 
-__version__ = "0.1.10"
+__version__ = "0.2.0"
 __all__ = ["start_debugger", "start_debugger_sync", "DebugSession", "__version__"]

hypha_debugger-0.2.0/hypha_debugger/cli.py

@@ -0,0 +1,426 @@
+"""``hyd`` — client CLI for the Hypha remote debugger.
+
+Lets an agent (or a human) run remote shell commands with almost no per-call
+overhead: connection profiles (URL + token) are stored once on disk, and each
+call is just ``hyd sh 'cmd'`` (or the bare ``hyd 'cmd'``).
+
+The remote is STATELESS. The "current session" — which profile is active and the
+current directory — is held in **environment variables** (``HYD_PROFILE`` and
+``HYD_CWD``), NOT on disk. Because env vars are per-shell, every terminal is
+naturally isolated: switching terminals does not carry the active profile/cwd.
+
+  - ``profiles.json`` (disk, mode 0600) — the machines only: {profiles: {name: {service_url, token?, workspace?}}}
+  - ``HYD_PROFILE`` (env) — the active profile for this shell
+  - ``HYD_CWD``     (env) — the current remote directory for this shell
+
+Commands that change the current state (``use``, ``cd``, ``profile add --use``)
+print shell ``export`` lines (safe to ``eval``); ``eval "$(hyd shell-init)"``
+installs a wrapper that applies them automatically and keeps ``HYD_CWD`` in sync
+after every ``hyd sh``. See any debugger's ``GET <url>/get_skill_md``.
+"""
+
+import json
+import os
+import shlex
+import sys
+import urllib.error
+import urllib.request
+
+__all__ = ["main"]
+
+
+class CliError(Exception):
+    pass
+
+
+# ---- config (profile DEFINITIONS only — never current-state) -------------
+def _config_dir() -> str:
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        d = os.path.join(xdg, "hypha-debugger")
+    else:
+        legacy = os.path.expanduser("~/.hypha-debugger")
+        d = legacy if os.path.isdir(legacy) else os.path.expanduser("~/.config/hypha-debugger")
+    os.makedirs(d, exist_ok=True)
+    return d
+
+
+def _profiles_path() -> str:
+    return os.path.join(_config_dir(), "profiles.json")
+
+
+def _load_profiles() -> dict:
+    try:
+        with open(_profiles_path()) as f:
+            return json.load(f).get("profiles", {})
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def _save_profiles(profiles: dict) -> None:
+    path = _profiles_path()
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump({"profiles": profiles}, f, indent=2)
+    os.replace(tmp, path)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+# ---- current state = environment variables -------------------------------
+def _env_profile() -> str:
+    return os.environ.get("HYD_PROFILE", "")
+
+
+def _env_cwd() -> str:
+    return os.environ.get("HYD_CWD", "")
+
+
+def _emit_state(exports: dict, human: str = "") -> None:
+    """Apply env changes. Under the shell wrapper (`$HYD_STATE_FILE` set) write
+    export lines to that file for the parent shell to source; otherwise print
+    eval-safe output (a `# comment` for humans + the `export` lines)."""
+    lines = [f"export {k}={shlex.quote(str(v))}" for k, v in exports.items()]
+    sf = os.environ.get("HYD_STATE_FILE")
+    if sf:
+        with open(sf, "a") as f:
+            f.write("\n".join(lines) + "\n")
+        if human:
+            sys.stderr.write(human + "\n")
+    else:
+        if human:
+            print("# " + human)
+        for line in lines:
+            print(line)
+
+
+def _write_cwd(new_cwd: str) -> None:
+    """After `hyd sh`, persist the new cwd to the shell (only via the wrapper's
+    state file — never to stdout, which carries the command output)."""
+    sf = os.environ.get("HYD_STATE_FILE")
+    if sf and new_cwd:
+        with open(sf, "a") as f:
+            f.write(f"export HYD_CWD={shlex.quote(new_cwd)}\n")
+
+
+# ---- resolution ----------------------------------------------------------
+def _normalize_url(url: str) -> str:
+    url = url.strip().rstrip("/")
+    for suffix in ("/get_skill_md", "/get_page_info"):
+        if url.endswith(suffix):
+            url = url[: -len(suffix)]
+    return url.rstrip("/")
+
+
+def _resolve_profile(explicit: str = "") -> tuple:
+    """Return (name, profile_dict). Priority: -p flag > $HYD_PROFILE > sole profile."""
+    profiles = _load_profiles()
+    if not profiles:
+        raise CliError("no profiles configured. Run: hyd profile add <name> <service_url> --use")
+    name = explicit or _env_profile()
+    if not name:
+        if len(profiles) == 1:
+            name = next(iter(profiles))
+        else:
+            raise CliError(
+                "no active profile. Set one: `export HYD_PROFILE=<name>` (or `eval \"$(hyd use <name>)\"`, "
+                f"or pass `-p <name>`). Profiles: {', '.join(profiles)}"
+            )
+    if name not in profiles:
+        raise CliError(f"unknown profile '{name}'. Profiles: {', '.join(profiles) or '(none)'}")
+    return name, profiles[name]
+
+
+# ---- transport -----------------------------------------------------------
+def _call_remote(profile: dict, fn: str, params: dict, http_timeout: int = 75) -> dict:
+    url = _normalize_url(profile["service_url"]) + f"/{fn}?_mode=last"
+    req = urllib.request.Request(url, data=json.dumps(params).encode(), method="POST")
+    req.add_header("Content-Type", "application/json")
+    if profile.get("token"):
+        req.add_header("Authorization", "Bearer " + profile["token"])
+    try:
+        with urllib.request.urlopen(req, timeout=http_timeout) as resp:
+            raw = resp.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace") if e.fp else ""
+        raise CliError(f"remote HTTP {e.code} calling {fn}: {body[:400]}")
+    except urllib.error.URLError as e:
+        raise CliError(f"cannot reach {url}: {e.reason}")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {"stdout": raw, "exit_code": 0, "cwd": params.get("cwd", "")}
+    if isinstance(data, dict) and "detail" in data and "stdout" not in data and "exit_code" not in data:
+        raise CliError(f"gateway error: {data['detail']} (is the debugger still connected?)")
+    return data
+
+
+# ---- run -----------------------------------------------------------------
+def _extract_opts(args: list) -> tuple:
+    """Pull -p/--profile, -t/--timeout, --cwd out of args; return (opts, rest)."""
+    opts = {"profile": "", "timeout": None, "cwd": ""}
+    rest = []
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-p", "--profile") and i + 1 < len(args):
+            opts["profile"] = args[i + 1]; i += 2; continue
+        if a in ("-t", "--timeout") and i + 1 < len(args):
+            opts["timeout"] = int(args[i + 1]); i += 2; continue
+        if a == "--cwd" and i + 1 < len(args):
+            opts["cwd"] = args[i + 1]; i += 2; continue
+        rest.append(a); i += 1
+    return opts, rest
+
+
+def cmd_sh(args: list, bare: bool = False) -> int:
+    if bare:
+        opts, command_parts = {"profile": "", "timeout": None, "cwd": ""}, args
+    else:
+        opts, command_parts = _extract_opts(args)
+    command = " ".join(command_parts).strip()
+    if not command:
+        raise CliError("nothing to run. Usage: hyd sh '<command>'")
+    _name, profile = _resolve_profile(opts["profile"])
+    cwd = opts["cwd"] or _env_cwd()
+    timeout = opts["timeout"] if opts["timeout"] is not None else 30
+    data = _call_remote(
+        profile, "execute_bash",
+        {"command": command, "cwd": cwd, "timeout": timeout},
+        http_timeout=(timeout or 60) + 15,
+    )
+    out = data.get("stdout", "")
+    if out:
+        sys.stdout.write(out if out.endswith("\n") else out + "\n")
+    if data.get("error"):
+        sys.stderr.write(f"hyd: {data['error']}\n")
+    _write_cwd(data.get("cwd", cwd))  # keep cwd in sync (via the shell wrapper)
+    return int(data.get("exit_code", 0) or 0)
+
+
+def cmd_py(args: list) -> int:
+    opts, code_parts = _extract_opts(args)
+    code = " ".join(code_parts).strip()
+    if not code:
+        raise CliError("nothing to run. Usage: hyd py '<python code>'")
+    _name, profile = _resolve_profile(opts["profile"])
+    data = _call_remote(profile, "execute_code", {"code": code})
+    if isinstance(data, dict):
+        if data.get("stdout"):
+            sys.stdout.write(data["stdout"])
+        for key in ("result", "value"):
+            if data.get(key) is not None:
+                print(data[key]); break
+        if data.get("error"):
+            sys.stderr.write(f"hyd: {data['error']}\n"); return 1
+    else:
+        print(data)
+    return 0
+
+
+# ---- profiles ------------------------------------------------------------
+def cmd_profile(args: list) -> int:
+    if not args:
+        return cmd_profile_list([])
+    sub, rest = args[0], args[1:]
+    if sub == "add":
+        return cmd_profile_add(rest)
+    if sub in ("list", "ls"):
+        return cmd_profile_list(rest)
+    if sub == "show":
+        return cmd_profile_show(rest)
+    if sub in ("rm", "remove", "delete"):
+        return cmd_profile_rm(rest)
+    raise CliError(f"unknown 'profile' subcommand: {sub}")
+
+
+def cmd_profile_add(args: list) -> int:
+    use = "--use" in args
+    args = [a for a in args if a != "--use"]
+    opts, pos = {}, []
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("--token", "--workspace") and i + 1 < len(args):
+            opts[a.lstrip("-")] = args[i + 1]; i += 2; continue
+        pos.append(a); i += 1
+    if len(pos) < 2:
+        raise CliError("usage: hyd profile add <name> <service_url> [--token T] [--workspace W] [--use]")
+    name, url = pos[0], _normalize_url(pos[1])
+    profiles = _load_profiles()
+    entry = profiles.get(name, {})
+    entry["service_url"] = url
+    if opts.get("token"):
+        entry["token"] = opts["token"]
+    if opts.get("workspace"):
+        entry["workspace"] = opts["workspace"]
+    profiles[name] = entry
+    _save_profiles(profiles)
+    if use:
+        _emit_state({"HYD_PROFILE": name}, human=f"profile '{name}' -> {url} (now active)")
+    else:
+        # No current-state change → just confirm (eval-safe comment).
+        print(f"# profile '{name}' -> {url}   (activate: export HYD_PROFILE={name})")
+    return 0
+
+
+def cmd_profile_list(_args: list) -> int:
+    profiles = _load_profiles()
+    if not profiles:
+        print("no profiles. Add one: hyd profile add <name> <service_url> --use")
+        return 0
+    active = _env_profile()
+    for name, p in profiles.items():
+        mark = "*" if name == active else " "
+        tok = " (token)" if p.get("token") else ""
+        print(f"{mark} {name}  {p.get('service_url', '')}{tok}")
+    return 0
+
+
+def cmd_profile_show(args: list) -> int:
+    if not args:
+        raise CliError("usage: hyd profile show <name>")
+    p = _load_profiles().get(args[0])
+    if not p:
+        raise CliError(f"unknown profile '{args[0]}'")
+    shown = dict(p)
+    if shown.get("token"):
+        shown["token"] = shown["token"][:6] + "…"
+    print(json.dumps({args[0]: shown}, indent=2))
+    return 0
+
+
+def cmd_profile_rm(args: list) -> int:
+    if not args:
+        raise CliError("usage: hyd profile rm <name>")
+    profiles = _load_profiles()
+    if args[0] not in profiles:
+        raise CliError(f"unknown profile '{args[0]}'")
+    del profiles[args[0]]
+    _save_profiles(profiles)
+    print(f"# removed profile '{args[0]}'")
+    return 0
+
+
+# ---- current state commands (emit env exports) ---------------------------
+def cmd_use(args: list) -> int:
+    if not args:
+        raise CliError("usage: hyd use <profile>")
+    name = args[0]
+    if name not in _load_profiles():
+        raise CliError(f"unknown profile '{name}'. Add it: hyd profile add {name} <service_url>")
+    _emit_state({"HYD_PROFILE": name}, human=f"active profile -> {name}")
+    return 0
+
+
+def cmd_cd(args: list) -> int:
+    target = args[0] if args else ""
+    _emit_state({"HYD_CWD": target}, human=f"cwd -> {target or '(remote default)'}")
+    return 0
+
+
+def cmd_pwd(_args: list) -> int:
+    print(_env_cwd() or "(remote default)")
+    return 0
+
+
+def cmd_status(_args: list) -> int:
+    try:
+        name, profile = _resolve_profile()
+    except CliError as e:
+        print(e); return 1
+    print(f"profile: {name}   cwd: {_env_cwd() or '(remote default)'}   (HYD_PROFILE/HYD_CWD)")
+    print(f"url: {_normalize_url(profile['service_url'])}")
+    try:
+        info = _call_remote(profile, "get_process_info", {})
+        print(f"connected: pid={info.get('pid')} host={info.get('hostname')} py={info.get('python_version')}")
+    except CliError as e:
+        print(f"UNREACHABLE: {e}"); return 1
+    return 0
+
+
+def cmd_shell_init(_args: list) -> int:
+    print(
+        "# hyd shell integration — add to your shell rc:  eval \"$(hyd shell-init)\"\n"
+        "# Wraps hyd so `use`/`cd`/`profile add --use` update this shell's env and\n"
+        "# `hyd sh` keeps HYD_CWD in sync. State lives in env vars (per-terminal), not on disk.\n"
+        "hyd() {\n"
+        "  local __f; __f=\"$(mktemp)\"\n"
+        "  HYD_STATE_FILE=\"$__f\" command hyd \"$@\"; local __rc=$?\n"
+        "  [ -s \"$__f\" ] && . \"$__f\"\n"
+        "  rm -f \"$__f\"\n"
+        "  return $__rc\n"
+        "}"
+    )
+    return 0
+
+
+def _print_help() -> int:
+    print(
+        """hyd — Hypha remote debugger CLI (run remote shell commands with minimal overhead)
+
+USAGE
+  hyd sh '<command>'            Run a shell command on the active profile (cwd via HYD_CWD)
+  hyd '<command>'              Same (bare form; anything not a subcommand runs as a command)
+  hyd py '<python>'            Run Python via the debugger's execute_code
+  hyd -p <profile> sh '...'    Run against a specific profile (overrides HYD_PROFILE)
+
+PROFILES (machines — stored on disk)
+  hyd profile add <name> <service_url> [--token T] [--workspace W] [--use]
+  hyd profile list | show <name> | rm <name>
+
+CURRENT STATE (env vars, per-terminal — NOT on disk)
+  export HYD_PROFILE=<name>    Select the active profile for this shell
+  export HYD_CWD=<dir>         Set the current remote directory for this shell
+  hyd use <name>              Prints `export HYD_PROFILE=<name>` (eval it, or use the wrapper)
+  hyd cd <dir> | pwd          Prints `export HYD_CWD=<dir>` / shows HYD_CWD
+  hyd shell-init              Wrapper so use/cd/sh update this shell's env automatically
+  hyd status                  Show active profile + cwd and ping the remote
+
+Profiles: $XDG_CONFIG_HOME/hypha-debugger (or ~/.hypha-debugger). Setup docs:
+GET <service_url>/get_skill_md."""
+    )
+    return 0
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        return _print_help()
+    cmd = argv[0]
+    try:
+        if cmd in ("help", "-h", "--help"):
+            return _print_help()
+        if cmd in ("version", "--version"):
+            from hypha_debugger import __version__
+            print(f"hyd (hypha-debugger) {__version__}")
+            return 0
+        if cmd in ("sh", "run", "exec"):
+            return cmd_sh(argv[1:])
+        if cmd == "py":
+            return cmd_py(argv[1:])
+        if cmd in ("profile", "profiles"):
+            return cmd_profile(argv[1:] if cmd == "profile" else ["list"] + argv[1:])
+        if cmd == "use":
+            return cmd_use(argv[1:])
+        if cmd == "cd":
+            return cmd_cd(argv[1:])
+        if cmd == "pwd":
+            return cmd_pwd(argv[1:])
+        if cmd == "status":
+            return cmd_status(argv[1:])
+        if cmd == "shell-init":
+            return cmd_shell_init(argv[1:])
+        # Bare fallback: the whole argv is a shell command.
+        return cmd_sh(argv, bare=True)
+    except CliError as e:
+        sys.stderr.write(f"hyd: {e}\n")
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/hypha_debugger/debugger.py

@@ -9,6 +9,7 @@ from typing import Optional
 
 from hypha_debugger.services.info import get_process_info, get_installed_packages
 from hypha_debugger.services.execute import execute_code
+from hypha_debugger.services.shell import execute_bash
 from hypha_debugger.services.inspect_vars import (
     get_variable,
     list_variables,
@@ -47,32 +48,19 @@ def _build_service_url(server_url: str, service_id: str) -> str:
 
 
 def _build_instruction_block(service_url: str, token: str = "") -> str:
-    """Build the instruction block with copy-paste commands for remote access.
+    """One-sentence instruction to paste into an AI agent.
 
-    Returns a formatted string that can be pasted directly into an AI agent chat.
+    Says what it is and where the API is; the agent reads the URL
+    (get_skill_md) for everything else.
     """
-    auth = f' -H "Authorization: Bearer $TOKEN"' if token else ""
-    lines = [
-        "# Hypha Remote Debugger — Python Process",
-        "# A remote debugger is attached to a running Python process.",
-        "# You can execute code, read/write files, inspect variables, and more.",
-        "# Call get_skill_md for full API docs with all available functions.",
-        "",
-        f'SERVICE_URL="{service_url}"',
-    ]
-    if token:
-        lines.append(f'TOKEN="{token}"')
-    lines += [
-        "",
-        "# Execute Python code:",
-        f'curl -X POST "$SERVICE_URL/execute_code"{auth}'
-        ' -H "Content-Type: application/json"'
-        " -d '{\"code\": \"import sys; sys.version\"}'",
-        "",
-        "# Get full API docs (all functions, parameters, examples):",
-        f'curl "$SERVICE_URL/get_skill_md"{auth}',
-    ]
-    return "\n".join(lines)
+    auth = (
+        f" (auth header: Authorization: Bearer {token})" if token else ""
+    )
+    return (
+        "A Hypha debugger is attached to this live Python process — call its HTTP "
+        f"API at {service_url} to run code and inspect the process; GET "
+        f"{service_url}/get_skill_md for the full tool list and usage{auth}."
+    )
 
 
 def _print_session_info(
@@ -241,6 +229,7 @@ async def start_debugger(
         "get_process_info": get_process_info,
         "get_installed_packages": get_installed_packages,
         "execute_code": execute_code,
+        "execute_bash": execute_bash,
         "get_variable": get_variable,
         "list_variables": list_variables,
         "get_stack_trace": get_stack_trace,
@@ -324,6 +313,7 @@ def start_debugger_sync(
         "get_process_info": get_process_info,
         "get_installed_packages": get_installed_packages,
         "execute_code": execute_code,
+        "execute_bash": execute_bash,
         "get_variable": get_variable,
         "list_variables": list_variables,
         "get_stack_trace": get_stack_trace,

hypha_debugger-0.2.0/hypha_debugger/services/shell.py

@@ -0,0 +1,154 @@
+"""Stateless remote shell execution service.
+
+Unlike ``execute_code`` (a persistent Python REPL), ``execute_bash`` runs each
+command in a **fresh** ``bash -c`` — the remote holds NO per-connection state.
+The *client* (e.g. the ``hyd`` CLI) tracks the "current directory" and passes it
+in as ``cwd``; the call returns the directory AFTER the command (so a ``cd`` in
+the command is reflected back), letting the client emulate a persistent terminal
+while keeping the server stateless (scales, survives reconnects).
+"""
+
+import os
+import shlex
+import subprocess
+from typing import Any, Dict, Optional
+
+# Default timeout for a shell command (seconds).
+DEFAULT_TIMEOUT = 30
+# Cap the returned output so a runaway command can't return megabytes.
+MAX_OUTPUT_CHARS = 200_000
+
+# Unique markers we append to the command to read back the final cwd + exit code
+# without them colliding with normal output.
+_MARK_CWD = "__HYD_CWD_9f3a2b__:"
+_MARK_EC = "__HYD_EC_9f3a2b__:"
+
+
+def _run_bash(command: str, cwd: str, env: Optional[Dict[str, str]], timeout: int) -> Dict[str, Any]:
+    start_dir = cwd or os.getcwd()
+    exports = ""
+    if env:
+        exports = "".join(
+            f"export {k}={shlex.quote(str(v))}\n" for k, v in env.items()
+        )
+    # Wrapper: cd into the requested dir, run the command, then emit the final
+    # pwd + exit code on marker lines we strip out of the returned output.
+    wrapper = (
+        f"cd {shlex.quote(start_dir)} 2>/dev/null || cd \"$HOME\" 2>/dev/null || true\n"
+        f"{exports}"
+        f"{command}\n"
+        f"__hyd_ec=$?\n"
+        f'printf "\\n{_MARK_CWD}%s\\n{_MARK_EC}%s\\n" "$(pwd)" "$__hyd_ec"\n'
+    )
+
+    try:
+        proc = subprocess.run(
+            ["bash", "-c", wrapper],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,  # merge stderr for a terminal-like feel
+            timeout=timeout if timeout and timeout > 0 else None,
+            text=True,
+        )
+        raw = proc.stdout or ""
+    except subprocess.TimeoutExpired as e:
+        partial = e.stdout or ""
+        if isinstance(partial, bytes):
+            partial = partial.decode("utf-8", "replace")
+        return {
+            "stdout": _truncate(_strip_markers(partial)[0]),
+            "exit_code": 124,
+            "cwd": start_dir,
+            "error": f"Command timed out after {timeout}s",
+        }
+    except FileNotFoundError:
+        return {
+            "stdout": "",
+            "exit_code": 127,
+            "cwd": start_dir,
+            "error": "bash not found on the remote host",
+        }
+
+    output, final_cwd, exit_code = _parse(raw, start_dir)
+    # If the command called `exit`/`kill` etc., our epilogue never ran and the
+    # markers are absent — fall back to bash's real return code.
+    if _MARK_EC not in raw:
+        exit_code = proc.returncode
+    return {"stdout": _truncate(output), "exit_code": exit_code, "cwd": final_cwd}
+
+
+def _parse(raw: str, fallback_cwd: str):
+    """Split the trailing cwd/exit-code markers off the real output."""
+    cwd = fallback_cwd
+    ec = 0
+    idx = raw.rfind("\n" + _MARK_CWD)
+    if idx == -1:
+        idx = raw.rfind(_MARK_CWD)
+    if idx != -1:
+        tail = raw[idx:]
+        output = raw[:idx]
+        for line in tail.splitlines():
+            if _MARK_CWD in line:
+                cwd = line.split(_MARK_CWD, 1)[1].strip() or fallback_cwd
+            elif _MARK_EC in line:
+                try:
+                    ec = int(line.split(_MARK_EC, 1)[1].strip())
+                except ValueError:
+                    ec = 0
+    else:
+        output = raw
+    return output, cwd, ec
+
+
+def _strip_markers(raw: str):
+    output, cwd, ec = _parse(raw, "")
+    return output, cwd, ec
+
+
+def _truncate(text: str) -> str:
+    if len(text) > MAX_OUTPUT_CHARS:
+        return text[:MAX_OUTPUT_CHARS] + f"\n... [truncated at {MAX_OUTPUT_CHARS} chars]"
+    return text
+
+
+try:
+    from pydantic import Field
+    from hypha_rpc.utils.schema import schema_function
+
+    @schema_function
+    def execute_bash(
+        command: str = Field(..., description="Shell command to run (bash)."),
+        cwd: str = Field(
+            default="",
+            description=(
+                "Working directory to run in. The remote is STATELESS: pass the "
+                "current directory here and use the returned `cwd` for the next "
+                "call to emulate a persistent shell. Empty = the process cwd."
+            ),
+        ),
+        env: Optional[Dict[str, str]] = Field(
+            default=None,
+            description="Optional environment variables to export before the command.",
+        ),
+        timeout: int = Field(
+            default=DEFAULT_TIMEOUT,
+            description=f"Max seconds before the command is killed (default {DEFAULT_TIMEOUT}, 0 = no limit).",
+        ),
+    ) -> Dict[str, Any]:
+        """Run a shell command on the remote host and return its output.
+
+        Stateless: each call is a fresh shell. Returns {stdout (stderr merged in),
+        exit_code, cwd} where `cwd` is the directory AFTER the command — pass it
+        back as `cwd` next time so `cd` persists (this is what the `hyd` CLI does).
+        """
+        return _run_bash(command, cwd, env, timeout)
+
+except ImportError:
+
+    def execute_bash(
+        command: str,
+        cwd: str = "",
+        env: Optional[Dict[str, str]] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> Dict[str, Any]:
+        """Run a shell command on the remote host and return its output."""
+        return _run_bash(command, cwd, env, timeout)

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/hypha_debugger/services/source.py

@@ -48,6 +48,8 @@ except ImportError:
 _MODULES = {
     "debugger": "hypha_debugger.debugger",
     "services.execute": "hypha_debugger.services.execute",
+    "services.shell": "hypha_debugger.services.shell",
+    "cli": "hypha_debugger.cli",
     "services.filesystem": "hypha_debugger.services.filesystem",
     "services.info": "hypha_debugger.services.info",
     "services.inspect_vars": "hypha_debugger.services.inspect_vars",
@@ -94,6 +96,38 @@ to execute code, read/write files, inspect variables, and install packages.
 persistent Python REPL where variables, imports, and functions survive across
 calls. The other endpoints are convenience shortcuts.
 
+## Fast path — the `hyd` CLI (recommended for agents)
+
+For repeated shell work, don't hand-write authenticated curl calls — install the
+`hyd` client CLI once and run remote commands with almost no per-call overhead.
+It stores this connection as a named **profile** (URL + token) on disk, so later
+calls carry no auth or JSON boilerplate. Bootstrap yourself:
+
+```bash
+pip install hypha-debugger            # ships the `hyd` command
+hyd profile add main "<THIS_SERVICE_URL>"   # add --token <t> if the URL is token-protected
+export HYD_PROFILE=main               # select it (env var — per-terminal, not on disk)
+
+hyd sh 'uname -a && pwd'              # run a remote shell command
+hyd 'ls -la'                         # bare form: anything not a subcommand runs as a command
+hyd py 'import sys; sys.version'      # run Python via execute_code
+```
+
+Key ideas:
+- **The remote is stateless.** The "current directory" and "current profile" live
+  in the environment variables `HYD_CWD` and `HYD_PROFILE` (per shell), so different
+  terminals are isolated and nothing session-specific is written to disk. Set
+  `export HYD_CWD=/some/dir` to fix a working directory, or run
+  `eval "$(hyd shell-init)"` once so `cd`/`cwd` stay in sync automatically after each
+  `hyd sh`.
+- **Multiple machines**: add more profiles (`hyd profile add other "<url>" --token …`)
+  and switch with `export HYD_PROFILE=other` or a one-off `hyd -p other sh '…'`.
+- `hyd sh` streams stdout/stderr and exits with the remote command's exit code, so
+  it behaves like a local shell. Run `hyd` (no args) for full help.
+
+The raw HTTP API below still works (and powers the CLI) — use it directly if you
+can't install the CLI.
+
 ## Quick Start
 
 ```bash
@@ -128,6 +162,19 @@ captured as the return value via AST parsing.
 - Variables, functions, and imports persist across calls.
 - Example: `"x = 1\\nx + 1"` returns `{ok: true, result: 2}`.
 
+### execute_bash(command, cwd?, env?, timeout?) — remote shell (STATELESS)
+Run a shell command on the remote host. Each call is a fresh shell (no server
+state). To emulate a persistent terminal, pass the current directory as `cwd` and
+reuse the returned `cwd` on the next call — this is exactly what the `hyd` CLI
+above does for you.
+- **command** (str, required): bash command line.
+- **cwd** (str, default `""`): directory to run in (`""` = the process cwd).
+- **env** (object, optional): env vars to export before the command.
+- **timeout** (int, default `30`): seconds; 0 = no limit.
+- **Returns**: `{stdout, exit_code, cwd}` — `stdout` has stderr merged in; `cwd` is
+  the directory AFTER the command (so `cd` is reflected).
+- Example: `curl -X POST "$SERVICE_URL/execute_bash" -d '{"command":"ls -la","cwd":"/tmp"}'`
+
 ### get_process_info()
 PID, CWD, Python version, hostname, platform, memory usage, CPU count.
 - **Example**: `curl "$SERVICE_URL/get_process_info"`

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/hypha_debugger.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypha-debugger
-Version: 0.1.11
+Version: 0.2.0
 Summary: Injectable debugger for Python processes and AI agents, powered by Hypha RPC
 Author: Amun AI AB
 License: MIT

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/hypha_debugger.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 hypha_debugger/__init__.py
 hypha_debugger/__main__.py
+hypha_debugger/cli.py
 hypha_debugger/debugger.py
 hypha_debugger.egg-info/PKG-INFO
 hypha_debugger.egg-info/SOURCES.txt
@@ -14,7 +15,10 @@ hypha_debugger/services/execute.py
 hypha_debugger/services/filesystem.py
 hypha_debugger/services/info.py
 hypha_debugger/services/inspect_vars.py
+hypha_debugger/services/shell.py
 hypha_debugger/services/source.py
 hypha_debugger/utils/__init__.py
 hypha_debugger/utils/env.py
-tests/test_services.py
+tests/test_cli.py
+tests/test_services.py
+tests/test_shell.py

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/hypha_debugger.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+hyd = hypha_debugger.cli:main
 hypha-debugger = hypha_debugger.__main__:main

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hypha-debugger"
-version = "0.1.11"
+version = "0.2.0"
 description = "Injectable debugger for Python processes and AI agents, powered by Hypha RPC"
 readme = "README.md"
 license = {text = "MIT"}
@@ -42,6 +42,7 @@ full = [
 
 [project.scripts]
 hypha-debugger = "hypha_debugger.__main__:main"
+hyd = "hypha_debugger.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["."]

hypha_debugger-0.2.0/tests/test_cli.py

@@ -0,0 +1,131 @@
+"""Tests for the `hyd` client CLI (profiles on disk, current state in env vars)."""
+
+import pytest
+
+from hypha_debugger import cli
+
+
+@pytest.fixture
+def cfg(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    for var in ("HYD_PROFILE", "HYD_CWD", "HYD_STATE_FILE"):
+        monkeypatch.delenv(var, raising=False)
+    return tmp_path
+
+
+def test_profile_add_normalizes_url(cfg):
+    assert cli.main(["profile", "add", "main", "https://h.io/services/x/get_skill_md"]) == 0
+    profs = cli._load_profiles()
+    assert profs["main"]["service_url"] == "https://h.io/services/x"
+
+
+def test_profile_add_with_token_and_list(cfg, capsys):
+    cli.main(["profile", "add", "main", "https://h.io/s/x", "--token", "secret"])
+    assert cli._load_profiles()["main"]["token"] == "secret"
+    cli.main(["profile", "list"])
+    out = capsys.readouterr().out
+    assert "main" in out and "(token)" in out
+
+
+def test_profile_rm(cfg):
+    cli.main(["profile", "add", "p", "https://h.io/s/x"])
+    cli.main(["profile", "rm", "p"])
+    assert "p" not in cli._load_profiles()
+
+
+def test_use_emits_export_no_disk_state(cfg, capsys):
+    cli.main(["profile", "add", "main", "https://h.io/s/x"])
+    cli.main(["use", "main"])
+    out = capsys.readouterr().out
+    assert "export HYD_PROFILE=main" in out
+    # No session/current-state file should exist on disk.
+    assert not (cfg / "hypha-debugger" / "sessions").exists()
+
+
+def test_cd_emits_export(cfg, capsys):
+    cli.main(["cd", "/var/log"])
+    assert "export HYD_CWD=/var/log" in capsys.readouterr().out
+
+
+def test_resolve_profile_from_env(cfg, monkeypatch):
+    cli.main(["profile", "add", "a", "https://a.io/s/1"])
+    cli.main(["profile", "add", "b", "https://b.io/s/2"])
+    monkeypatch.setenv("HYD_PROFILE", "b")
+    name, prof = cli._resolve_profile()
+    assert name == "b" and prof["service_url"].endswith("/s/2")
+
+
+def test_resolve_profile_flag_overrides_env(cfg, monkeypatch):
+    cli.main(["profile", "add", "a", "https://a.io/s/1"])
+    cli.main(["profile", "add", "b", "https://b.io/s/2"])
+    monkeypatch.setenv("HYD_PROFILE", "a")
+    name, _ = cli._resolve_profile("b")
+    assert name == "b"
+
+
+def test_resolve_sole_profile_when_unset(cfg):
+    cli.main(["profile", "add", "only", "https://o.io/s/1"])
+    name, _ = cli._resolve_profile()
+    assert name == "only"
+
+
+def test_sh_calls_execute_bash_and_returns_exit_code(cfg, monkeypatch):
+    cli.main(["profile", "add", "main", "https://h.io/s/x"])
+    monkeypatch.setenv("HYD_PROFILE", "main")
+    seen = {}
+
+    def fake(profile, fn, params, http_timeout=75):
+        seen["fn"] = fn
+        seen["params"] = params
+        return {"stdout": "hi\n", "exit_code": 7, "cwd": "/tmp"}
+
+    monkeypatch.setattr(cli, "_call_remote", fake)
+    rc = cli.main(["sh", "echo hi"])
+    assert rc == 7
+    assert seen["fn"] == "execute_bash"
+    assert seen["params"]["command"] == "echo hi"
+
+
+def test_sh_persists_cwd_via_state_file(cfg, monkeypatch, tmp_path):
+    cli.main(["profile", "add", "main", "https://h.io/s/x"])
+    monkeypatch.setenv("HYD_PROFILE", "main")
+    sf = tmp_path / "state.sh"
+    sf.write_text("")
+    monkeypatch.setenv("HYD_STATE_FILE", str(sf))
+    monkeypatch.setattr(cli, "_call_remote", lambda *a, **k: {"stdout": "", "exit_code": 0, "cwd": "/var"})
+    cli.main(["sh", "pwd"])
+    assert "export HYD_CWD=/var" in sf.read_text()
+
+
+def test_sh_uses_env_cwd(cfg, monkeypatch):
+    cli.main(["profile", "add", "main", "https://h.io/s/x"])
+    monkeypatch.setenv("HYD_PROFILE", "main")
+    monkeypatch.setenv("HYD_CWD", "/opt")
+    seen = {}
+    monkeypatch.setattr(cli, "_call_remote", lambda profile, fn, params, http_timeout=75: seen.update(params) or {"stdout": "", "exit_code": 0, "cwd": "/opt"})
+    cli.main(["sh", "pwd"])
+    assert seen["cwd"] == "/opt"
+
+
+def test_bare_fallback_runs_as_command(cfg, monkeypatch):
+    cli.main(["profile", "add", "main", "https://h.io/s/x"])
+    monkeypatch.setenv("HYD_PROFILE", "main")
+    seen = {}
+    monkeypatch.setattr(cli, "_call_remote", lambda profile, fn, params, http_timeout=75: seen.update(params) or {"stdout": "", "exit_code": 0, "cwd": ""})
+    cli.main(["ls", "-la"])
+    assert seen["command"] == "ls -la"
+
+
+def test_p_flag_selects_profile(cfg, monkeypatch):
+    cli.main(["profile", "add", "a", "https://a.io/s/1"])
+    cli.main(["profile", "add", "b", "https://b.io/s/2"])
+    monkeypatch.setenv("HYD_PROFILE", "a")
+    seen = {}
+
+    def fake(profile, fn, params, http_timeout=75):
+        seen["url"] = profile["service_url"]
+        return {"stdout": "", "exit_code": 0, "cwd": ""}
+
+    monkeypatch.setattr(cli, "_call_remote", fake)
+    cli.main(["sh", "-p", "b", "hostname"])
+    assert seen["url"].endswith("/s/2")

{hypha_debugger-0.1.11 → hypha_debugger-0.2.0}/tests/test_services.py

@@ -270,19 +270,17 @@ def test_write_file_invalid_mode():
 
 def test_instruction_block_no_token():
     from hypha_debugger.debugger import _build_instruction_block
-    block = _build_instruction_block("https://example.com/ws/services/py-debugger-abc")
-    assert "SERVICE_URL=" in block
-    assert "TOKEN=" not in block
-    assert "Authorization" not in block
-    assert "execute_code" in block
+    url = "https://example.com/ws/services/py-debugger-abc"
+    block = _build_instruction_block(url)
+    assert url in block
     assert "get_skill_md" in block
+    assert "Authorization" not in block  # no token -> no auth header
 
 
 def test_instruction_block_with_token():
     from hypha_debugger.debugger import _build_instruction_block
     block = _build_instruction_block("https://example.com/ws/services/py-debugger", "mytoken123")
-    assert 'TOKEN="mytoken123"' in block
-    assert "Authorization" in block
+    assert "Authorization: Bearer mytoken123" in block
 
 
 # --- source ---
@@ -341,6 +339,6 @@ def test_debug_session_print_instructions(capsys):
     captured = capsys.readouterr()
     assert "WARNING" in captured.out
     assert "trusted" in captured.out
-    assert "SERVICE_URL=" in captured.out
+    assert "get_skill_md" in captured.out
     assert isinstance(result, str)
-    assert "SERVICE_URL=" in result
+    assert "py-debugger-abc" in result

hypha_debugger-0.2.0/tests/test_shell.py

@@ -0,0 +1,50 @@
+"""Tests for the stateless remote shell service (no server required)."""
+
+import os
+
+from hypha_debugger.services.shell import execute_bash
+
+
+def test_basic_stdout():
+    r = execute_bash(command="echo hello")
+    assert r["exit_code"] == 0
+    assert "hello" in r["stdout"]
+
+
+def test_exit_code_propagates():
+    r = execute_bash(command="exit 3")
+    assert r["exit_code"] == 3
+
+
+def test_stderr_merged_into_stdout():
+    r = execute_bash(command="echo oops >&2")
+    assert "oops" in r["stdout"]
+
+
+def test_cwd_reflected_after_cd():
+    r = execute_bash(command="cd /tmp && pwd", cwd="")
+    assert r["exit_code"] == 0
+    assert os.path.realpath(r["cwd"]) == os.path.realpath("/tmp")
+
+
+def test_cwd_argument_used():
+    r = execute_bash(command="pwd", cwd="/tmp")
+    assert os.path.realpath(r["stdout"].strip()) == os.path.realpath("/tmp")
+
+
+def test_stateless_no_shared_process():
+    # First call cd's within its own shell; the second (no cwd) must NOT inherit it.
+    execute_bash(command="cd /tmp", cwd="")
+    r = execute_bash(command="pwd", cwd="")
+    assert os.path.realpath(r["stdout"].strip()) == os.path.realpath(os.getcwd())
+
+
+def test_timeout_kills():
+    r = execute_bash(command="sleep 5", timeout=1)
+    assert r["exit_code"] == 124
+    assert "timed out" in (r.get("error") or "").lower()
+
+
+def test_env_exported():
+    r = execute_bash(command="echo $FOO", env={"FOO": "bar"})
+    assert "bar" in r["stdout"]