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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypha-debugger
-Version: 0.1.0
+Version: 0.1.4
 Summary: Injectable debugger for Python processes and AI agents, powered by Hypha RPC
 Author: Amun AI AB
 License: MIT
@@ -185,6 +185,20 @@ Inject into any Python process to enable remote code execution, variable inspect
 pip install hypha-debugger
 ```
 
+**CLI (simplest — just run and get instructions):**
+
+```bash
+hypha-debugger
+```
+
+Or with options:
+
+```bash
+hypha-debugger --server-url https://hypha.aicell.io --service-id my-debugger
+hypha-debugger --no-token  # URL-secret mode, no auth needed
+python -m hypha_debugger   # alternative
+```
+
 **Async:**
 
 ```python
@@ -193,8 +207,7 @@ from hypha_debugger import start_debugger
 
 async def main():
     session = await start_debugger(server_url="https://hypha.aicell.io")
-    print(session.service_url)  # HTTP endpoint
-    print(session.token)        # JWT token
+    session.print_instructions()  # print instructions anytime
     await session.serve_forever()
 
 asyncio.run(main())
@@ -206,20 +219,30 @@ asyncio.run(main())
 from hypha_debugger import start_debugger_sync
 
 session = start_debugger_sync(server_url="https://hypha.aicell.io")
-# Debugger runs in background, main thread continues
-print(session.service_url)
+session.print_instructions()  # print instructions anytime
 ```
 
 ### What You Get
 
+The debugger prints copy-paste instructions on startup:
+
 ```
 [hypha-debugger] Connected to https://hypha.aicell.io
-[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger
-[hypha-debugger] Token: eyJ...
-[hypha-debugger] Test it:
-  curl 'https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger/get_process_info' -H 'Authorization: Bearer eyJ...'
+[hypha-debugger] Service ID: ws-xxx/clientId:py-debugger
+[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/py-debugger
+
+SERVICE_URL="https://hypha.aicell.io/ws-xxx/services/py-debugger"
+TOKEN="eyJ..."
+
+# Quick test:
+curl "$SERVICE_URL/get_process_info?_mode=last" -H "Authorization: Bearer $TOKEN"
+
+# Execute code:
+curl -X POST "$SERVICE_URL/execute_code?_mode=last" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"code": "import sys; sys.version"}'
 ```
 
+Call `session.print_instructions()` anytime to reprint them.
+
 ### Service Functions (Python)
 
 | Function | Description |

{hypha_debugger-0.1.0 → hypha_debugger-0.1.4}/README.md

@@ -157,6 +157,20 @@ Inject into any Python process to enable remote code execution, variable inspect
 pip install hypha-debugger
 ```
 
+**CLI (simplest — just run and get instructions):**
+
+```bash
+hypha-debugger
+```
+
+Or with options:
+
+```bash
+hypha-debugger --server-url https://hypha.aicell.io --service-id my-debugger
+hypha-debugger --no-token  # URL-secret mode, no auth needed
+python -m hypha_debugger   # alternative
+```
+
 **Async:**
 
 ```python
@@ -165,8 +179,7 @@ from hypha_debugger import start_debugger
 
 async def main():
     session = await start_debugger(server_url="https://hypha.aicell.io")
-    print(session.service_url)  # HTTP endpoint
-    print(session.token)        # JWT token
+    session.print_instructions()  # print instructions anytime
     await session.serve_forever()
 
 asyncio.run(main())
@@ -178,20 +191,30 @@ asyncio.run(main())
 from hypha_debugger import start_debugger_sync
 
 session = start_debugger_sync(server_url="https://hypha.aicell.io")
-# Debugger runs in background, main thread continues
-print(session.service_url)
+session.print_instructions()  # print instructions anytime
 ```
 
 ### What You Get
 
+The debugger prints copy-paste instructions on startup:
+
 ```
 [hypha-debugger] Connected to https://hypha.aicell.io
-[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger
-[hypha-debugger] Token: eyJ...
-[hypha-debugger] Test it:
-  curl 'https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger/get_process_info' -H 'Authorization: Bearer eyJ...'
+[hypha-debugger] Service ID: ws-xxx/clientId:py-debugger
+[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/py-debugger
+
+SERVICE_URL="https://hypha.aicell.io/ws-xxx/services/py-debugger"
+TOKEN="eyJ..."
+
+# Quick test:
+curl "$SERVICE_URL/get_process_info?_mode=last" -H "Authorization: Bearer $TOKEN"
+
+# Execute code:
+curl -X POST "$SERVICE_URL/execute_code?_mode=last" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"code": "import sys; sys.version"}'
 ```
 
+Call `session.print_instructions()` anytime to reprint them.
+
 ### Service Functions (Python)
 
 | Function | Description |

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

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

hypha_debugger-0.1.4/hypha_debugger/__main__.py

@@ -0,0 +1,86 @@
+"""CLI entry point: python -m hypha_debugger
+
+Starts a debugger session and prints instructions for remote access.
+"""
+
+import argparse
+import asyncio
+import signal
+import sys
+
+from hypha_debugger.debugger import start_debugger
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="hypha-debugger",
+        description="Start a Hypha debugger session for this Python process.",
+    )
+    parser.add_argument(
+        "--server-url",
+        default="https://hypha.aicell.io",
+        help="Hypha server URL (default: https://hypha.aicell.io)",
+    )
+    parser.add_argument(
+        "--workspace",
+        default="",
+        help="Workspace name (auto-assigned if omitted)",
+    )
+    parser.add_argument(
+        "--token",
+        default="",
+        help="Authentication token for connecting to Hypha",
+    )
+    parser.add_argument(
+        "--service-id",
+        default="py-debugger",
+        help="Service ID to register as (default: py-debugger)",
+    )
+    parser.add_argument(
+        "--service-name",
+        default="Python Debugger",
+        help="Human-readable service name (default: Python Debugger)",
+    )
+    parser.add_argument(
+        "--no-token",
+        action="store_true",
+        help="Disable token requirement (URL-secret mode)",
+    )
+    args = parser.parse_args()
+
+    async def run():
+        session = await start_debugger(
+            server_url=args.server_url,
+            workspace=args.workspace,
+            token=args.token,
+            service_id=args.service_id,
+            service_name=args.service_name,
+            require_token=not args.no_token,
+        )
+
+        print()
+        print("[hypha-debugger] Debugger is running. Press Ctrl+C to stop.")
+        print()
+
+        # Handle graceful shutdown
+        stop = asyncio.Event()
+
+        def _signal_handler():
+            stop.set()
+
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, _signal_handler)
+
+        await stop.wait()
+        print("\n[hypha-debugger] Shutting down...")
+        await session.destroy()
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

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

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+import secrets
 import threading
 from dataclasses import dataclass, field
 from typing import Optional
@@ -19,33 +20,102 @@ logger = logging.getLogger("hypha_debugger")
 
 
 def _build_service_url(server_url: str, service_id: str) -> str:
-    """Build the HTTP base URL for a registered service.
+    """Build a stable, predictable HTTP service URL.
+
+    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"
 
     Returns:
-        e.g. "https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger"
+        e.g. "https://hypha.aicell.io/ws-xxx/services/py-debugger"
     """
     base = server_url.rstrip("/")
     # service_id format: "workspace/clientId:svcName"
     parts = service_id.split("/", 1)
     if len(parts) == 2:
         workspace, svc_part = parts
-        return f"{base}/{workspace}/services/{svc_part}"
+        # Strip clientId: "abc123:py-debugger" → "py-debugger"
+        if ":" in svc_part:
+            svc_name = svc_part.split(":", 1)[1]
+        else:
+            svc_name = svc_part
+        return f"{base}/{workspace}/services/{svc_name}"
     return f"{base}/services/{service_id}"
 
 
-def _print_session_info(server_url: str, service_id: str, service_url: str, token: str) -> None:
+def _build_instruction_block(
+    service_url: str,
+    token: str,
+    require_token: bool = True,
+) -> str:
+    """Build the instruction block with copy-paste commands for remote access.
+
+    Returns a formatted string similar to the JS overlay instructions.
+    """
+    auth_header = f' -H "Authorization: Bearer $TOKEN"' if require_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,",
+        "# 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",
+        "#",
+        "# All endpoints require ?_mode=last suffix. POST endpoints accept JSON body.",
+        "",
+        f'SERVICE_URL="{service_url}"',
+    ]
+    if require_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}',
+        "",
+        "# Execute Python code remotely:",
+        f"curl -X POST \"$SERVICE_URL/execute_code?_mode=last\""
+        f"{auth_header}"
+        " -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\"}'",
+        "",
+        "# List files in working directory:",
+        f'curl "$SERVICE_URL/list_files?_mode=last"{auth_header}',
+    ]
+    return "\n".join(lines)
+
+
+def _print_session_info(
+    server_url: str,
+    service_id: str,
+    service_url: str,
+    token: str,
+    require_token: bool = True,
+) -> 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}")
-    print(f"[hypha-debugger] Token: {token}")
+    if require_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()
-    print(f"[hypha-debugger] Test it:")
-    print(f"  curl '{service_url}/get_process_info' -H 'Authorization: Bearer {token}'")
+    print(_build_instruction_block(service_url, token, require_token))
+    print()
+    print(f"{sep}")
 
 
 @dataclass
@@ -63,6 +133,21 @@ class DebugSession:
     )
     _thread: Optional[threading.Thread] = field(default=None, repr=False)
 
+    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)
+        )
+        sep = "=" * 60
+        print(f"{sep}")
+        print("  Copy the text below to your AI agent")
+        print(f"{sep}")
+        print()
+        print(instructions)
+        print()
+        print(f"{sep}")
+        return instructions
+
     async def serve_forever(self):
         """Block until disconnected (async)."""
         try:
@@ -102,7 +187,8 @@ async def start_debugger(
     token: str = "",
     service_id: str = "py-debugger",
     service_name: str = "Python Debugger",
-    visibility: str = "public",
+    visibility: str = "",
+    require_token: bool = True,
 ) -> DebugSession:
     """Start the Hypha debugger (async).
 
@@ -112,16 +198,26 @@ async def start_debugger(
     Args:
         server_url: Hypha server URL (required).
         workspace: Workspace name (auto-assigned if empty).
-        token: Authentication token.
+        token: Authentication token for connecting to Hypha.
         service_id: Service ID to register as.
         service_name: Human-readable service name.
-        visibility: Service visibility ("public", "protected", "unlisted").
+        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.
 
     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")
+
     connect_config = {"server_url": server_url}
     if workspace:
         connect_config["workspace"] = workspace
@@ -132,14 +228,14 @@ async def start_debugger(
 
     service = {
         "name": service_name,
-        "id": service_id,
+        "id": effective_id,
         "type": "debugger",
         "description": (
             "Remote Python process debugger. Allows inspecting variables, "
             "executing code, browsing files, and getting process information."
         ),
         "config": {
-            "visibility": visibility,
+            "visibility": effective_visibility,
             "run_in_executor": True,
         },
         "get_process_info": get_process_info,
@@ -153,11 +249,13 @@ async def start_debugger(
     }
 
     svc_info = await server.register_service(service)
-    actual_id = svc_info.get("id", service_id) if isinstance(svc_info, dict) else service_id
+    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
-    session_token = await server.generate_token()
+    # Generate a token for remote access (24h expiry); skip in no-token mode.
+    session_token = ""
+    if require_token:
+        session_token = await server.generate_token({"expires_in": 86400})
 
     # Build the HTTP service URL
     service_url = _build_service_url(server_url, actual_id)
@@ -168,7 +266,7 @@ async def start_debugger(
         ws,
         actual_id,
     )
-    _print_session_info(server_url, actual_id, service_url, session_token)
+    _print_session_info(server_url, actual_id, service_url, session_token, require_token)
 
     return DebugSession(
         service_id=actual_id,
@@ -186,7 +284,8 @@ def start_debugger_sync(
     token: str = "",
     service_id: str = "py-debugger",
     service_name: str = "Python Debugger",
-    visibility: str = "public",
+    visibility: str = "",
+    require_token: bool = True,
 ) -> DebugSession:
     """Start the Hypha debugger (sync).
 
@@ -201,18 +300,24 @@ 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")
+
     server = connect_to_server({"server_url": server_url, **({"workspace": workspace} if workspace else {}), **({"token": token} if token else {})})
 
     service = {
         "name": service_name,
-        "id": service_id,
+        "id": effective_id,
         "type": "debugger",
         "description": (
             "Remote Python process debugger. Allows inspecting variables, "
             "executing code, browsing files, and getting process information."
         ),
         "config": {
-            "visibility": visibility,
+            "visibility": effective_visibility,
             "run_in_executor": True,
         },
         "get_process_info": get_process_info,
@@ -226,11 +331,13 @@ def start_debugger_sync(
     }
 
     svc_info = server.register_service(service)
-    actual_id = svc_info.get("id", service_id) if isinstance(svc_info, dict) else service_id
+    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
-    session_token = server.generate_token()
+    # Generate a token for remote access (24h expiry); skip in no-token mode.
+    session_token = ""
+    if require_token:
+        session_token = server.generate_token({"expires_in": 86400})
 
     # Build the HTTP service URL
     service_url = _build_service_url(server_url, actual_id)
@@ -241,7 +348,7 @@ def start_debugger_sync(
         ws,
         actual_id,
     )
-    _print_session_info(server_url, actual_id, service_url, session_token)
+    _print_session_info(server_url, actual_id, service_url, session_token, require_token)
 
     return DebugSession(
         service_id=actual_id,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypha-debugger
-Version: 0.1.0
+Version: 0.1.4
 Summary: Injectable debugger for Python processes and AI agents, powered by Hypha RPC
 Author: Amun AI AB
 License: MIT
@@ -185,6 +185,20 @@ Inject into any Python process to enable remote code execution, variable inspect
 pip install hypha-debugger
 ```
 
+**CLI (simplest — just run and get instructions):**
+
+```bash
+hypha-debugger
+```
+
+Or with options:
+
+```bash
+hypha-debugger --server-url https://hypha.aicell.io --service-id my-debugger
+hypha-debugger --no-token  # URL-secret mode, no auth needed
+python -m hypha_debugger   # alternative
+```
+
 **Async:**
 
 ```python
@@ -193,8 +207,7 @@ from hypha_debugger import start_debugger
 
 async def main():
     session = await start_debugger(server_url="https://hypha.aicell.io")
-    print(session.service_url)  # HTTP endpoint
-    print(session.token)        # JWT token
+    session.print_instructions()  # print instructions anytime
     await session.serve_forever()
 
 asyncio.run(main())
@@ -206,20 +219,30 @@ asyncio.run(main())
 from hypha_debugger import start_debugger_sync
 
 session = start_debugger_sync(server_url="https://hypha.aicell.io")
-# Debugger runs in background, main thread continues
-print(session.service_url)
+session.print_instructions()  # print instructions anytime
 ```
 
 ### What You Get
 
+The debugger prints copy-paste instructions on startup:
+
 ```
 [hypha-debugger] Connected to https://hypha.aicell.io
-[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger
-[hypha-debugger] Token: eyJ...
-[hypha-debugger] Test it:
-  curl 'https://hypha.aicell.io/ws-xxx/services/clientId:py-debugger/get_process_info' -H 'Authorization: Bearer eyJ...'
+[hypha-debugger] Service ID: ws-xxx/clientId:py-debugger
+[hypha-debugger] Service URL: https://hypha.aicell.io/ws-xxx/services/py-debugger
+
+SERVICE_URL="https://hypha.aicell.io/ws-xxx/services/py-debugger"
+TOKEN="eyJ..."
+
+# Quick test:
+curl "$SERVICE_URL/get_process_info?_mode=last" -H "Authorization: Bearer $TOKEN"
+
+# Execute code:
+curl -X POST "$SERVICE_URL/execute_code?_mode=last" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"code": "import sys; sys.version"}'
 ```
 
+Call `session.print_instructions()` anytime to reprint them.
+
 ### Service Functions (Python)
 
 | Function | Description |

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

@@ -1,10 +1,12 @@
 README.md
 pyproject.toml
 hypha_debugger/__init__.py
+hypha_debugger/__main__.py
 hypha_debugger/debugger.py
 hypha_debugger.egg-info/PKG-INFO
 hypha_debugger.egg-info/SOURCES.txt
 hypha_debugger.egg-info/dependency_links.txt
+hypha_debugger.egg-info/entry_points.txt
 hypha_debugger.egg-info/requires.txt
 hypha_debugger.egg-info/top_level.txt
 hypha_debugger/services/__init__.py

hypha_debugger-0.1.4/hypha_debugger.egg-info/entry_points.txt

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hypha-debugger"
-version = "0.1.0"
+version = "0.1.4"
 description = "Injectable debugger for Python processes and AI agents, powered by Hypha RPC"
 readme = "README.md"
 license = {text = "MIT"}
@@ -40,6 +40,9 @@ full = [
     "psutil>=5.9",
 ]
 
+[project.scripts]
+hypha-debugger = "hypha_debugger.__main__:main"
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["hypha_debugger*"]