hypha-debugger 0.1.4__tar.gz → 0.1.6__tar.gz

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/PKG-INFO

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

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger/__init__.py

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

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger/__main__.py

@@ -42,9 +42,9 @@ def main():
         help="Human-readable service name (default: Python Debugger)",
     )
     parser.add_argument(
-        "--no-token",
+        "--require-token",
         action="store_true",
-        help="Disable token requirement (URL-secret mode)",
+        help="Require a JWT token for remote access (default: URL-secret mode, no token needed)",
     )
     args = parser.parse_args()
 
@@ -55,7 +55,7 @@ def main():
             token=args.token,
             service_id=args.service_id,
             service_name=args.service_name,
-            require_token=not args.no_token,
+            require_token=args.require_token,
         )
 
         print()

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger/debugger.py

@@ -14,30 +14,30 @@ from hypha_debugger.services.inspect_vars import (
     list_variables,
     get_stack_trace,
 )
-from hypha_debugger.services.filesystem import list_files, read_file
+from hypha_debugger.services.filesystem import list_files, read_file, write_file
+from hypha_debugger.services.source import get_source, get_skill_md
 
 logger = logging.getLogger("hypha_debugger")
 
 
 def _build_service_url(server_url: str, service_id: str) -> str:
-    """Build a stable, predictable HTTP service URL.
+    """Build the HTTP service URL from server URL and full service ID.
 
     Strips the clientId prefix so the URL uses only the bare service name.
-    Callers append ?_mode=last to resolve the most recent instance.
 
     Args:
         server_url: e.g. "https://hypha.aicell.io"
-        service_id: e.g. "ws-xxx/clientId:py-debugger"
+        service_id: e.g. "ws-xxx/clientId:py-debugger-abc123"
 
     Returns:
-        e.g. "https://hypha.aicell.io/ws-xxx/services/py-debugger"
+        e.g. "https://hypha.aicell.io/ws-xxx/services/py-debugger-abc123"
     """
     base = server_url.rstrip("/")
     # service_id format: "workspace/clientId:svcName"
     parts = service_id.split("/", 1)
     if len(parts) == 2:
         workspace, svc_part = parts
-        # Strip clientId: "abc123:py-debugger" → "py-debugger"
+        # Strip clientId: "abc123:py-debugger-xyz" → "py-debugger-xyz"
         if ":" in svc_part:
             svc_name = svc_part.split(":", 1)[1]
         else:
@@ -46,76 +46,87 @@ def _build_service_url(server_url: str, service_id: str) -> str:
     return f"{base}/services/{service_id}"
 
 
-def _build_instruction_block(
-    service_url: str,
-    token: str,
-    require_token: bool = True,
-) -> str:
+def _build_instruction_block(service_url: str, token: str = "") -> str:
     """Build the instruction block with copy-paste commands for remote access.
 
-    Returns a formatted string similar to the JS overlay instructions.
+    Returns a formatted string that can be pasted directly into an AI agent chat.
     """
-    auth_header = f' -H "Authorization: Bearer $TOKEN"' if require_token else ""
+    auth = f' -H "Authorization: Bearer $TOKEN"' if token else ""
     lines = [
         "# Hypha Remote Debugger — Python Process",
         "# A debugger is attached to a running Python process.",
-        "# You can remotely inspect variables, execute code, browse files,",
+        "# You can remotely execute code, read/write files, inspect variables,",
         "# and query process info via the HTTP API below.",
         "#",
-        "# Available functions: get_process_info, execute_code, get_variable,",
-        "#   list_variables, get_stack_trace, list_files, read_file, get_installed_packages",
+        "# Available functions:",
+        "#   get_process_info    - PID, Python version, CWD, platform, memory",
+        "#   execute_code        - Run arbitrary Python code (with timeout)",
+        "#   get_variable        - Inspect a variable by name",
+        "#   list_variables      - List variables in a namespace",
+        "#   get_stack_trace     - Stack traces of all threads",
+        "#   list_files          - List directory contents",
+        "#   read_file           - Read file content (with offset/limit)",
+        "#   write_file          - Write/append to a file",
+        "#   get_installed_packages - List pip packages",
+        "#   get_source           - Get debugger source code (for self-inspection)",
+        "#   get_skill_md         - Get full API docs as Markdown",
         "#",
-        "# All endpoints require ?_mode=last suffix. POST endpoints accept JSON body.",
+        "# POST endpoints accept JSON body with parameter names as keys.",
         "",
         f'SERVICE_URL="{service_url}"',
     ]
-    if require_token:
+    if token:
         lines.append(f'TOKEN="{token}"')
     lines += [
         "",
         "# Get process info (PID, Python version, CWD, memory):",
-        f'curl "$SERVICE_URL/get_process_info?_mode=last"{auth_header}',
+        f'curl "$SERVICE_URL/get_process_info"{auth}',
         "",
-        "# Execute Python code remotely:",
-        f"curl -X POST \"$SERVICE_URL/execute_code?_mode=last\""
-        f"{auth_header}"
-        " -H \"Content-Type: application/json\""
+        "# Execute Python code (timeout default 30s):",
+        f'curl -X POST "$SERVICE_URL/execute_code"{auth}'
+        ' -H "Content-Type: application/json"'
         " -d '{\"code\": \"import sys; sys.version\"}'",
         "",
-        "# Inspect a variable:",
-        f"curl -X POST \"$SERVICE_URL/get_variable?_mode=last\""
-        f"{auth_header}"
-        " -H \"Content-Type: application/json\""
-        " -d '{\"name\": \"my_var\"}'",
+        "# Write a file:",
+        f'curl -X POST "$SERVICE_URL/write_file"{auth}'
+        ' -H "Content-Type: application/json"'
+        " -d '{\"path\": \"hello.txt\", \"content\": \"Hello, world!\"}'",
         "",
         "# List files in working directory:",
-        f'curl "$SERVICE_URL/list_files?_mode=last"{auth_header}',
+        f'curl "$SERVICE_URL/list_files"{auth}',
+        "",
+        "# Read a file:",
+        f'curl -X POST "$SERVICE_URL/read_file"{auth}'
+        ' -H "Content-Type: application/json"'
+        " -d '{\"path\": \"hello.txt\"}'",
+        "",
+        "# Get full API documentation:",
+        f'curl "$SERVICE_URL/get_skill_md"{auth}',
     ]
     return "\n".join(lines)
 
 
 def _print_session_info(
     server_url: str,
-    service_id: str,
     service_url: str,
-    token: str,
-    require_token: bool = True,
+    token: str = "",
 ) -> None:
     """Print session information with remote access URLs."""
     print(f"[hypha-debugger] Connected to {server_url}")
-    print(f"[hypha-debugger] Service ID: {service_id}")
     print(f"[hypha-debugger] Service URL: {service_url}")
-    if require_token:
+    if token:
         print(f"[hypha-debugger] Token: {token}")
     print()
     sep = "=" * 60
-    print(f"{sep}")
-    print("  Copy the text below to your AI agent")
-    print(f"{sep}")
+    print(sep)
+    print("  WARNING: The URL below grants full access to this Python")
+    print("  process (execute code, read/write files). Only share it")
+    print("  with trusted agents or people.")
+    print(sep)
     print()
-    print(_build_instruction_block(service_url, token, require_token))
+    print(_build_instruction_block(service_url, token))
     print()
-    print(f"{sep}")
+    print(sep)
 
 
 @dataclass
@@ -135,17 +146,17 @@ class DebugSession:
 
     def print_instructions(self) -> str:
         """Print copy-paste instructions for remote access and return them."""
-        instructions = _build_instruction_block(
-            self.service_url, self.token, bool(self.token)
-        )
+        instructions = _build_instruction_block(self.service_url, self.token)
         sep = "=" * 60
-        print(f"{sep}")
-        print("  Copy the text below to your AI agent")
-        print(f"{sep}")
+        print(sep)
+        print("  WARNING: The URL below grants full access to this Python")
+        print("  process (execute code, read/write files). Only share it")
+        print("  with trusted agents or people.")
+        print(sep)
         print()
         print(instructions)
         print()
-        print(f"{sep}")
+        print(sep)
         return instructions
 
     async def serve_forever(self):
@@ -181,6 +192,27 @@ class DebugSession:
             self._thread.join(timeout=5)
 
 
+def _resolve_id_and_visibility(
+    service_id: str,
+    visibility: str,
+    require_token: bool,
+) -> tuple:
+    """Resolve effective service ID and visibility.
+
+    By default (require_token=False), generates a unique random service ID
+    and registers as unlisted. The URL itself acts as the secret.
+
+    Returns:
+        (effective_id, effective_visibility)
+    """
+    effective_id = service_id
+    # Always add a random suffix unless user provided a custom ID
+    if service_id == "py-debugger":
+        effective_id = f"py-debugger-{secrets.token_hex(16)}"
+    effective_visibility = visibility or ("protected" if require_token else "unlisted")
+    return effective_id, effective_visibility
+
+
 async def start_debugger(
     server_url: str,
     workspace: str = "",
@@ -188,35 +220,34 @@ async def start_debugger(
     service_id: str = "py-debugger",
     service_name: str = "Python Debugger",
     visibility: str = "",
-    require_token: bool = True,
+    require_token: bool = False,
 ) -> DebugSession:
     """Start the Hypha debugger (async).
 
     Connects to a Hypha server and registers a debug service that remote
     clients can use to inspect and interact with this Python process.
 
+    By default, the service is registered as "unlisted" with a unique random
+    service ID. The URL itself is unguessable — no token needed. Just keep
+    the URL secret.
+
     Args:
         server_url: Hypha server URL (required).
         workspace: Workspace name (auto-assigned if empty).
         token: Authentication token for connecting to Hypha.
-        service_id: Service ID to register as.
+        service_id: Service ID to register as. A random suffix is added by default.
         service_name: Human-readable service name.
         visibility: Service visibility override ("public", "protected", "unlisted").
-            Defaults to "protected" when require_token=True, "unlisted" when False.
-        require_token: Whether remote callers must supply a JWT token (default True).
-            When False, the service is registered as "unlisted" and the service ID
-            gets a random suffix — the URL itself acts as the secret, no token needed.
+        require_token: Whether to generate a JWT token for remote callers (default False).
 
     Returns:
         A DebugSession with service_id, workspace, server, service_url, and token.
     """
     from hypha_rpc import connect_to_server
 
-    # Resolve effective service_id and visibility based on require_token.
-    effective_id = service_id
-    if not require_token and service_id == "py-debugger":
-        effective_id = f"py-debugger-{secrets.token_hex(8)}"
-    effective_visibility = visibility or ("protected" if require_token else "unlisted")
+    effective_id, effective_visibility = _resolve_id_and_visibility(
+        service_id, visibility, require_token
+    )
 
     connect_config = {"server_url": server_url}
     if workspace:
@@ -246,13 +277,16 @@ async def start_debugger(
         "get_stack_trace": get_stack_trace,
         "list_files": list_files,
         "read_file": read_file,
+        "write_file": write_file,
+        "get_source": get_source,
+        "get_skill_md": get_skill_md,
     }
 
     svc_info = await server.register_service(service)
     actual_id = svc_info.get("id", effective_id) if isinstance(svc_info, dict) else effective_id
     ws = server.config.get("workspace", workspace) if hasattr(server.config, "get") else getattr(server.config, "workspace", workspace)
 
-    # Generate a token for remote access (24h expiry); skip in no-token mode.
+    # Generate a token for remote access (24h expiry) only if requested.
     session_token = ""
     if require_token:
         session_token = await server.generate_token({"expires_in": 86400})
@@ -266,7 +300,7 @@ async def start_debugger(
         ws,
         actual_id,
     )
-    _print_session_info(server_url, actual_id, service_url, session_token, require_token)
+    _print_session_info(server_url, service_url, session_token)
 
     return DebugSession(
         service_id=actual_id,
@@ -285,7 +319,7 @@ def start_debugger_sync(
     service_id: str = "py-debugger",
     service_name: str = "Python Debugger",
     visibility: str = "",
-    require_token: bool = True,
+    require_token: bool = False,
 ) -> DebugSession:
     """Start the Hypha debugger (sync).
 
@@ -300,11 +334,9 @@ def start_debugger_sync(
     """
     from hypha_rpc.sync import connect_to_server
 
-    # Resolve effective service_id and visibility based on require_token.
-    effective_id = service_id
-    if not require_token and service_id == "py-debugger":
-        effective_id = f"py-debugger-{secrets.token_hex(8)}"
-    effective_visibility = visibility or ("protected" if require_token else "unlisted")
+    effective_id, effective_visibility = _resolve_id_and_visibility(
+        service_id, visibility, require_token
+    )
 
     server = connect_to_server({"server_url": server_url, **({"workspace": workspace} if workspace else {}), **({"token": token} if token else {})})
 
@@ -328,13 +360,16 @@ def start_debugger_sync(
         "get_stack_trace": get_stack_trace,
         "list_files": list_files,
         "read_file": read_file,
+        "write_file": write_file,
+        "get_source": get_source,
+        "get_skill_md": get_skill_md,
     }
 
     svc_info = server.register_service(service)
     actual_id = svc_info.get("id", effective_id) if isinstance(svc_info, dict) else effective_id
     ws = server.config.get("workspace", workspace) if hasattr(server.config, "get") else getattr(server.config, "workspace", workspace)
 
-    # Generate a token for remote access (24h expiry); skip in no-token mode.
+    # Generate a token for remote access (24h expiry) only if requested.
     session_token = ""
     if require_token:
         session_token = server.generate_token({"expires_in": 86400})
@@ -348,7 +383,7 @@ def start_debugger_sync(
         ws,
         actual_id,
     )
-    _print_session_info(server_url, actual_id, service_url, session_token, require_token)
+    _print_session_info(server_url, service_url, session_token)
 
     return DebugSession(
         service_id=actual_id,

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger/services/execute.py

@@ -1,8 +1,13 @@
-"""Arbitrary code execution service."""
+"""Arbitrary code execution service with timeout support."""
 
 import sys
 import io
+import signal
 import traceback
+import threading
+
+# Default timeout for code execution (seconds). 0 = no timeout.
+DEFAULT_TIMEOUT = 30
 
 try:
     from pydantic import Field
@@ -15,19 +20,28 @@ try:
             default="__main__",
             description='Namespace to execute in. Default: "__main__" (the main module namespace).',
         ),
+        timeout: int = Field(
+            default=DEFAULT_TIMEOUT,
+            description="Timeout in seconds. 0 for no timeout. Default: 30.",
+        ),
     ) -> dict:
-        """Execute Python code in the debugger process and return stdout, stderr, and the result of the last expression."""
-        return _execute_impl(code, namespace)
+        """Execute Python code in the debugger process and return stdout, stderr, and the result.
+
+        Supports both expressions (returns the value) and statements.
+        Code runs in the target namespace so you can define functions, import modules, etc.
+        A timeout (default 30s) prevents infinite loops from hanging the debugger.
+        """
+        return _execute_impl(code, namespace, timeout)
 
 except ImportError:
 
-    def execute_code(code: str, namespace: str = "__main__") -> dict:
+    def execute_code(code: str, namespace: str = "__main__", timeout: int = DEFAULT_TIMEOUT) -> dict:
         """Execute Python code in the debugger process."""
-        return _execute_impl(code, namespace)
+        return _execute_impl(code, namespace, timeout)
 
 
-def _execute_impl(code: str, namespace: str = "__main__") -> dict:
-    """Implementation of code execution."""
+def _execute_impl(code: str, namespace: str = "__main__", timeout: int = DEFAULT_TIMEOUT) -> dict:
+    """Implementation of code execution with optional timeout."""
     # Get the target namespace
     if namespace == "__main__":
         ns = vars(sys.modules.get("__main__", {}))
@@ -42,18 +56,30 @@ def _execute_impl(code: str, namespace: str = "__main__") -> dict:
 
     result = None
     error = None
+    timed_out = False
 
     try:
         sys.stdout = stdout_capture
         sys.stderr = stderr_capture
 
-        # Try as expression first (to capture return value)
-        try:
-            result = eval(code, ns)
-        except SyntaxError:
-            # Not an expression, execute as statements
-            exec(code, ns)
-            result = None
+        if timeout > 0 and threading.current_thread() is threading.main_thread():
+            # Use SIGALRM for timeout on the main thread (Unix only)
+            def _timeout_handler(signum, frame):
+                raise TimeoutError(f"Code execution timed out after {timeout}s")
+
+            old_handler = signal.signal(signal.SIGALRM, _timeout_handler)
+            signal.alarm(timeout)
+            try:
+                result = _run_code(code, ns)
+            except TimeoutError as e:
+                error = str(e)
+                timed_out = True
+            finally:
+                signal.alarm(0)
+                signal.signal(signal.SIGALRM, old_handler)
+        else:
+            # No timeout or not on main thread — run directly
+            result = _run_code(code, ns)
     except Exception:
         error = traceback.format_exc()
     finally:
@@ -74,10 +100,21 @@ def _execute_impl(code: str, namespace: str = "__main__") -> dict:
     }
     if error:
         response["error"] = error
+    if timed_out:
+        response["timed_out"] = True
 
     return response
 
 
+def _run_code(code: str, ns: dict):
+    """Try as expression first (to capture return value), fall back to exec."""
+    try:
+        return eval(code, ns)
+    except SyntaxError:
+        exec(code, ns)
+        return None
+
+
 def _safe_serialize(obj, depth=0, max_depth=3):
     """Safely serialize an object for RPC transport."""
     if depth > max_depth:

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger/services/filesystem.py

@@ -1,4 +1,4 @@
-"""File system browsing service (sandboxed to CWD)."""
+"""File system browsing and writing service (sandboxed to CWD)."""
 
 import os
 
@@ -27,13 +27,44 @@ try:
             default=500,
             description="Maximum number of lines to read. Default: 500.",
         ),
+        offset: int = Field(
+            default=0,
+            description="Number of lines to skip from the beginning. Default: 0.",
+        ),
         encoding: str = Field(
             default="utf-8",
             description="File encoding. Default: utf-8.",
         ),
     ) -> dict:
-        """Read a file relative to the process CWD. Returns the content as a string."""
-        return _read_file_impl(path, max_lines, encoding)
+        """Read a file relative to the process CWD. Returns the content as a string.
+
+        Use offset and max_lines to paginate through large files.
+        """
+        return _read_file_impl(path, max_lines, offset, encoding)
+
+    @schema_function
+    def write_file(
+        path: str = Field(..., description="File path relative to CWD."),
+        content: str = Field(..., description="Content to write to the file."),
+        mode: str = Field(
+            default="w",
+            description='Write mode: "w" to overwrite, "a" to append. Default: "w".',
+        ),
+        create_dirs: bool = Field(
+            default=True,
+            description="Create parent directories if they don't exist. Default: true.",
+        ),
+        encoding: str = Field(
+            default="utf-8",
+            description="File encoding. Default: utf-8.",
+        ),
+    ) -> dict:
+        """Write content to a file relative to the process CWD.
+
+        Creates parent directories automatically. Use mode="a" to append.
+        Sandboxed: cannot write outside the process CWD.
+        """
+        return _write_file_impl(path, content, mode, create_dirs, encoding)
 
 except ImportError:
 
@@ -42,10 +73,17 @@ except ImportError:
         return _list_files_impl(path, pattern)
 
     def read_file(
-        path: str = "", max_lines: int = 500, encoding: str = "utf-8"
+        path: str = "", max_lines: int = 500, offset: int = 0, encoding: str = "utf-8"
     ) -> dict:
         """Read a file relative to CWD."""
-        return _read_file_impl(path, max_lines, encoding)
+        return _read_file_impl(path, max_lines, offset, encoding)
+
+    def write_file(
+        path: str = "", content: str = "", mode: str = "w",
+        create_dirs: bool = True, encoding: str = "utf-8"
+    ) -> dict:
+        """Write content to a file relative to CWD."""
+        return _write_file_impl(path, content, mode, create_dirs, encoding)
 
 
 def _resolve_safe(path: str) -> str:
@@ -105,7 +143,7 @@ def _entry_info(name: str, full_path: str) -> dict:
     return info
 
 
-def _read_file_impl(path: str, max_lines: int, encoding: str) -> dict:
+def _read_file_impl(path: str, max_lines: int, offset: int, encoding: str) -> dict:
     try:
         resolved = _resolve_safe(path)
     except PermissionError as e:
@@ -118,7 +156,9 @@ def _read_file_impl(path: str, max_lines: int, encoding: str) -> dict:
         with open(resolved, "r", encoding=encoding, errors="replace") as f:
             lines = []
             for i, line in enumerate(f):
-                if i >= max_lines:
+                if i < offset:
+                    continue
+                if len(lines) >= max_lines:
                     break
                 lines.append(line)
         content = "".join(lines)
@@ -126,7 +166,35 @@ def _read_file_impl(path: str, max_lines: int, encoding: str) -> dict:
             "path": os.path.relpath(resolved, os.getcwd()),
             "content": content,
             "lines_read": len(lines),
+            "offset": offset,
             "truncated": len(lines) >= max_lines,
         }
     except Exception as e:
         return {"error": f"Failed to read file: {e}"}
+
+
+def _write_file_impl(
+    path: str, content: str, mode: str, create_dirs: bool, encoding: str
+) -> dict:
+    if mode not in ("w", "a"):
+        return {"error": f'Invalid mode: {mode}. Use "w" or "a".'}
+
+    try:
+        resolved = _resolve_safe(path)
+    except PermissionError as e:
+        return {"error": str(e)}
+
+    try:
+        if create_dirs:
+            os.makedirs(os.path.dirname(resolved), exist_ok=True)
+
+        with open(resolved, mode, encoding=encoding) as f:
+            f.write(content)
+
+        return {
+            "path": os.path.relpath(resolved, os.getcwd()),
+            "bytes_written": len(content.encode(encoding)),
+            "mode": mode,
+        }
+    except Exception as e:
+        return {"error": f"Failed to write file: {e}"}

hypha_debugger-0.1.6/hypha_debugger/services/source.py

@@ -0,0 +1,187 @@
+"""Source code and skill documentation service."""
+
+import inspect
+import os
+
+try:
+    from pydantic import Field
+    from hypha_rpc.utils.schema import schema_function
+
+    @schema_function
+    def get_source(
+        module: str = Field(
+            default="",
+            description=(
+                'Module path relative to hypha_debugger, e.g. "services.execute". '
+                'Empty string returns a list of available modules.'
+            ),
+        ),
+    ) -> dict:
+        """Get the source code of hypha-debugger modules.
+
+        Use this to understand exactly what functions are available, their
+        parameters, and how they work. Pass an empty string to list modules.
+        """
+        return _get_source_impl(module)
+
+    @schema_function
+    def get_skill_md() -> str:
+        """Get full API documentation for all debugger service functions.
+
+        Returns a Markdown document describing every available function,
+        its parameters, return values, and curl usage examples. Suitable
+        for pasting into an AI agent context.
+        """
+        return _get_skill_md_impl()
+
+except ImportError:
+
+    def get_source(module: str = "") -> dict:
+        """Get the source code of hypha-debugger modules."""
+        return _get_source_impl(module)
+
+    def get_skill_md() -> str:
+        """Get full API documentation for all debugger service functions."""
+        return _get_skill_md_impl()
+
+
+_MODULES = {
+    "debugger": "hypha_debugger.debugger",
+    "services.execute": "hypha_debugger.services.execute",
+    "services.filesystem": "hypha_debugger.services.filesystem",
+    "services.info": "hypha_debugger.services.info",
+    "services.inspect_vars": "hypha_debugger.services.inspect_vars",
+    "services.source": "hypha_debugger.services.source",
+    "utils.env": "hypha_debugger.utils.env",
+}
+
+
+def _get_source_impl(module: str) -> dict:
+    if not module:
+        return {
+            "modules": list(_MODULES.keys()),
+            "hint": 'Pass a module name, e.g. get_source(module="services.execute")',
+        }
+
+    full_name = _MODULES.get(module)
+    if not full_name:
+        return {
+            "error": f"Unknown module: {module}",
+            "available": list(_MODULES.keys()),
+        }
+
+    try:
+        mod = __import__(full_name, fromlist=["_"])
+        source = inspect.getsource(mod)
+        return {
+            "module": module,
+            "full_name": full_name,
+            "source": source,
+            "lines": source.count("\n") + 1,
+        }
+    except Exception as e:
+        return {"error": f"Failed to get source: {e}"}
+
+
+def _get_skill_md_impl() -> str:
+    return """# Hypha Remote Debugger — Python Process API
+
+## Overview
+A debugger is attached to a running Python process. You can remotely execute code,
+read/write files, inspect variables, and query process info via the HTTP API.
+
+## Functions
+
+### get_process_info()
+Get information about the current Python process.
+- **Returns**: `{pid, cwd, python_version, hostname, platform, memory_mb, cpu_count, ...}`
+- **Example**: `curl "$SERVICE_URL/get_process_info"`
+
+### execute_code(code, namespace?, timeout?)
+Execute arbitrary Python code in the process.
+- **code** (string, required): Python code to execute.
+- **namespace** (string, default `"__main__"`): Module namespace to execute in.
+- **timeout** (int, default `30`): Timeout in seconds. 0 for no timeout.
+- **Returns**: `{stdout, stderr, result, result_type, error?, timed_out?}`
+- Tries `eval()` first (returns value), falls back to `exec()` (returns None).
+- **Example**:
+  ```bash
+  curl -X POST "$SERVICE_URL/execute_code" \\
+    -H "Content-Type: application/json" \\
+    -d '{"code": "import sys; sys.version"}'
+  ```
+
+### get_variable(name, namespace?)
+Inspect a variable by name.
+- **name** (string, required): Variable name.
+- **namespace** (string, default `"__main__"`): Module namespace.
+- **Returns**: `{name, type, repr, length?, shape?, dtype?, keys?}`
+
+### list_variables(namespace?, filter?, include_private?)
+List variables in a namespace.
+- **namespace** (string, default `"__main__"`): Module namespace.
+- **filter** (string): Substring filter for names.
+- **include_private** (bool, default `false`): Include `_`-prefixed names.
+- **Returns**: List of `{name, type, repr}`.
+
+### get_stack_trace()
+Get stack traces of all threads.
+- **Returns**: List of `{thread_id, thread_name, stack}`.
+- **Example**: `curl "$SERVICE_URL/get_stack_trace"`
+
+### list_files(path?, pattern?)
+List files and directories (sandboxed to CWD).
+- **path** (string, default `"."`): Directory path relative to CWD.
+- **pattern** (string): Glob filter, e.g. `"*.py"`.
+- **Returns**: `{path, entries: [{name, type, size?}], total}`
+- **Example**: `curl "$SERVICE_URL/list_files"`
+
+### read_file(path, max_lines?, offset?, encoding?)
+Read a file (sandboxed to CWD).
+- **path** (string, required): File path relative to CWD.
+- **max_lines** (int, default `500`): Max lines to read.
+- **offset** (int, default `0`): Lines to skip from beginning.
+- **Returns**: `{path, content, lines_read, offset, truncated}`
+- **Example**:
+  ```bash
+  curl -X POST "$SERVICE_URL/read_file" \\
+    -H "Content-Type: application/json" \\
+    -d '{"path": "main.py"}'
+  ```
+
+### write_file(path, content, mode?, create_dirs?, encoding?)
+Write content to a file (sandboxed to CWD).
+- **path** (string, required): File path relative to CWD.
+- **content** (string, required): Content to write.
+- **mode** (string, default `"w"`): `"w"` to overwrite, `"a"` to append.
+- **create_dirs** (bool, default `true`): Create parent directories.
+- **Returns**: `{path, bytes_written, mode}`
+- **Example**:
+  ```bash
+  curl -X POST "$SERVICE_URL/write_file" \\
+    -H "Content-Type: application/json" \\
+    -d '{"path": "hello.txt", "content": "Hello!"}'
+  ```
+
+### get_installed_packages(filter?)
+List installed pip packages.
+- **filter** (string): Substring filter for package names.
+- **Returns**: List of `{name, version}`.
+- **Example**: `curl "$SERVICE_URL/get_installed_packages"`
+
+### get_source(module?)
+Get the source code of debugger modules.
+- **module** (string): Module path, e.g. `"services.execute"`. Empty to list modules.
+- **Returns**: `{module, source, lines}` or `{modules, hint}`.
+
+### get_skill_md()
+Get this API documentation as Markdown.
+- **Returns**: This document as a string.
+- **Example**: `curl "$SERVICE_URL/get_skill_md"`
+
+## Notes
+- All file operations are sandboxed to the process CWD.
+- POST endpoints accept JSON body with parameter names as keys.
+- GET endpoints take no parameters (or use query params).
+- Code execution has a default 30s timeout to prevent hangs.
+"""

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger.egg-info/PKG-INFO

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

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/hypha_debugger.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ hypha_debugger/services/execute.py
 hypha_debugger/services/filesystem.py
 hypha_debugger/services/info.py
 hypha_debugger/services/inspect_vars.py
+hypha_debugger/services/source.py
 hypha_debugger/utils/__init__.py
 hypha_debugger/utils/env.py
 tests/test_services.py

{hypha_debugger-0.1.4 → hypha_debugger-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hypha-debugger"
-version = "0.1.4"
+version = "0.1.6"
 description = "Injectable debugger for Python processes and AI agents, powered by Hypha RPC"
 readme = "README.md"
 license = {text = "MIT"}

hypha_debugger-0.1.6/tests/test_services.py

@@ -0,0 +1,284 @@
+"""Basic tests for service functions (no server required)."""
+
+import os
+import sys
+import tempfile
+
+from hypha_debugger.services.info import get_process_info, get_installed_packages
+from hypha_debugger.services.execute import execute_code
+from hypha_debugger.services.inspect_vars import get_variable, list_variables, get_stack_trace
+from hypha_debugger.services.filesystem import list_files, read_file, write_file
+
+
+def test_get_process_info():
+    info = get_process_info()
+    assert info["pid"] == os.getpid()
+    assert info["python_version"] == sys.version
+    assert "cwd" in info
+    assert "hostname" in info
+    assert "platform" in info
+
+
+def test_get_installed_packages():
+    pkgs = get_installed_packages()
+    assert isinstance(pkgs, list)
+    assert len(pkgs) > 0
+    # Should find hypha-debugger itself
+    names = [p["name"].lower() for p in pkgs]
+    assert "hypha-debugger" in names
+
+
+def test_get_installed_packages_filter():
+    pkgs = get_installed_packages("hypha")
+    names = [p["name"].lower() for p in pkgs]
+    assert all("hypha" in n for n in names)
+
+
+# --- execute_code ---
+
+def test_execute_code_expression():
+    result = execute_code("1 + 2")
+    assert result["result"] == 3
+    assert result["result_type"] == "int"
+    assert result.get("error") is None
+
+
+def test_execute_code_statement():
+    result = execute_code("x = 42\nprint(x)")
+    assert "42" in result["stdout"]
+    assert result.get("error") is None
+
+
+def test_execute_code_error():
+    result = execute_code("1 / 0")
+    assert "error" in result
+    assert "ZeroDivisionError" in result["error"]
+
+
+def test_execute_code_import():
+    # Multi-statement uses exec (no return value), so test via stdout
+    result = execute_code("import json; print(json.dumps({'a': 1}))")
+    assert '{"a": 1}' in result["stdout"]
+    assert result.get("error") is None
+
+
+def test_execute_code_multiline():
+    code = """
+def greet(name):
+    return f"Hello, {name}!"
+greet("World")
+"""
+    result = execute_code(code)
+    assert result.get("error") is None
+    # eval/exec may or may not capture the last expression depending on implementation
+    # but at least no error
+
+
+def test_execute_code_timeout():
+    """Test that timeout parameter works (execution should not hang)."""
+    result = execute_code("'done'", timeout=5)
+    assert result["result"] == "done"
+    assert result.get("error") is None
+
+
+def test_execute_code_stdout_capture():
+    result = execute_code("print('hello'); print('world')")
+    assert "hello" in result["stdout"]
+    assert "world" in result["stdout"]
+
+
+# --- inspect_vars ---
+
+def test_get_variable():
+    result = get_variable("sys", namespace="hypha_debugger.services.inspect_vars")
+    assert result["name"] == "sys"
+    assert result["type"] == "module"
+
+
+def test_get_variable_not_found():
+    result = get_variable("nonexistent_variable_xyz")
+    assert "error" in result
+
+
+def test_list_variables():
+    result = list_variables(namespace="hypha_debugger.services.info")
+    names = [v["name"] for v in result]
+    assert "get_process_info" in names
+
+
+def test_get_stack_trace():
+    traces = get_stack_trace()
+    assert isinstance(traces, list)
+    assert len(traces) > 0
+    assert "thread_id" in traces[0]
+    assert "thread_name" in traces[0]
+    assert "stack" in traces[0]
+
+
+# --- filesystem ---
+
+def test_list_files():
+    result = list_files(".")
+    assert "entries" in result
+    assert "total" in result
+    names = [e["name"] for e in result["entries"]]
+    assert any("hypha_debugger" in n for n in names) or len(names) > 0
+
+
+def test_list_files_pattern():
+    result = list_files(".", pattern="*.toml")
+    names = [e["name"] for e in result["entries"]]
+    assert "pyproject.toml" in names
+
+
+def test_read_file():
+    result = read_file("pyproject.toml")
+    if "error" not in result:
+        assert "content" in result
+        assert "hypha-debugger" in result["content"]
+
+
+def test_read_file_with_offset():
+    result = read_file("pyproject.toml", offset=1, max_lines=2)
+    assert result.get("error") is None
+    assert result["offset"] == 1
+    assert result["lines_read"] <= 2
+
+
+def test_read_file_sandbox():
+    result = read_file("../../etc/passwd")
+    assert "error" in result
+    assert "Access denied" in result["error"] or "Not a file" in result["error"]
+
+
+def test_write_file():
+    old_cwd = os.getcwd()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.chdir(tmpdir)
+        try:
+            result = write_file("test_output.txt", "hello world")
+            assert result.get("error") is None
+            assert result["bytes_written"] == 11
+            assert result["mode"] == "w"
+
+            # Verify written content
+            read_result = read_file("test_output.txt")
+            assert read_result["content"] == "hello world"
+        finally:
+            os.chdir(old_cwd)
+
+
+def test_write_file_append():
+    old_cwd = os.getcwd()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.chdir(tmpdir)
+        try:
+            write_file("append_test.txt", "first\n")
+            write_file("append_test.txt", "second\n", mode="a")
+            read_result = read_file("append_test.txt")
+            assert "first" in read_result["content"]
+            assert "second" in read_result["content"]
+        finally:
+            os.chdir(old_cwd)
+
+
+def test_write_file_create_dirs():
+    old_cwd = os.getcwd()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.chdir(tmpdir)
+        try:
+            result = write_file("sub/dir/test.txt", "nested content")
+            assert result.get("error") is None
+            assert os.path.isfile(os.path.join(tmpdir, "sub", "dir", "test.txt"))
+        finally:
+            os.chdir(old_cwd)
+
+
+def test_write_file_sandbox():
+    result = write_file("../../etc/evil.txt", "pwned")
+    assert "error" in result
+    assert "Access denied" in result["error"]
+
+
+def test_write_file_invalid_mode():
+    result = write_file("test.txt", "content", mode="x")
+    assert "error" in result
+    assert "Invalid mode" in result["error"]
+
+
+# --- instruction block ---
+
+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
+    assert "write_file" in block
+
+
+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
+
+
+# --- source ---
+
+def test_get_source_list_modules():
+    from hypha_debugger.services.source import get_source
+    result = get_source("")
+    assert "modules" in result
+    assert "services.execute" in result["modules"]
+    assert "services.filesystem" in result["modules"]
+    assert "debugger" in result["modules"]
+
+
+def test_get_source_module():
+    from hypha_debugger.services.source import get_source
+    result = get_source("services.execute")
+    assert "source" in result
+    assert "execute_code" in result["source"]
+    assert result["lines"] > 10
+
+
+def test_get_source_unknown():
+    from hypha_debugger.services.source import get_source
+    result = get_source("nonexistent")
+    assert "error" in result
+    assert "available" in result
+
+
+def test_get_skill_md():
+    from hypha_debugger.services.source import get_skill_md
+    md = get_skill_md()
+    assert isinstance(md, str)
+    assert "execute_code" in md
+    assert "write_file" in md
+    assert "get_source" in md
+    assert "get_skill_md" in md
+    assert "SERVICE_URL" in md
+
+
+def test_instruction_block_includes_new_functions():
+    from hypha_debugger.debugger import _build_instruction_block
+    block = _build_instruction_block("https://example.com/ws/services/py-debugger-abc")
+    assert "get_source" in block
+    assert "get_skill_md" in block
+
+
+def test_debug_session_print_instructions(capsys):
+    from hypha_debugger.debugger import DebugSession
+    session = DebugSession(
+        service_id="test", workspace="test", server=None,
+        service_url="https://example.com/ws/services/py-debugger-abc",
+    )
+    result = session.print_instructions()
+    captured = capsys.readouterr()
+    assert "WARNING" in captured.out
+    assert "trusted" in captured.out
+    assert "SERVICE_URL=" in captured.out
+    assert isinstance(result, str)
+    assert "SERVICE_URL=" in result

hypha_debugger-0.1.4/tests/test_services.py

@@ -1,77 +0,0 @@
-"""Basic tests for service functions (no server required)."""
-
-import os
-import sys
-
-from hypha_debugger.services.info import get_process_info
-from hypha_debugger.services.execute import execute_code
-from hypha_debugger.services.inspect_vars import get_variable, list_variables
-from hypha_debugger.services.filesystem import list_files, read_file
-
-
-def test_get_process_info():
-    info = get_process_info()
-    assert info["pid"] == os.getpid()
-    assert info["python_version"] == sys.version
-    assert "cwd" in info
-    assert "hostname" in info
-    assert "platform" in info
-
-
-def test_execute_code_expression():
-    result = execute_code("1 + 2")
-    assert result["result"] == 3
-    assert result["result_type"] == "int"
-    assert result.get("error") is None
-
-
-def test_execute_code_statement():
-    result = execute_code("x = 42\nprint(x)")
-    assert "42" in result["stdout"]
-    assert result.get("error") is None
-
-
-def test_execute_code_error():
-    result = execute_code("1 / 0")
-    assert "error" in result
-    assert "ZeroDivisionError" in result["error"]
-
-
-def test_get_variable():
-    result = get_variable("sys", namespace="hypha_debugger.services.inspect_vars")
-    assert result["name"] == "sys"
-    assert result["type"] == "module"
-
-
-def test_get_variable_not_found():
-    result = get_variable("nonexistent_variable_xyz")
-    assert "error" in result
-
-
-def test_list_variables():
-    result = list_variables(namespace="hypha_debugger.services.info")
-    names = [v["name"] for v in result]
-    assert "get_process_info" in names
-
-
-def test_list_files():
-    result = list_files(".")
-    assert "entries" in result
-    assert "total" in result
-    # Should find the pyproject.toml
-    names = [e["name"] for e in result["entries"]]
-    assert any("hypha_debugger" in n for n in names) or len(names) > 0
-
-
-def test_read_file():
-    # Read the pyproject.toml
-    result = read_file("pyproject.toml")
-    if "error" not in result:
-        assert "content" in result
-        assert "hypha-debugger" in result["content"]
-
-
-def test_read_file_sandbox():
-    result = read_file("../../etc/passwd")
-    assert "error" in result
-    assert "Access denied" in result["error"] or "Not a file" in result["error"]