synapse-sdk 1.0.0b5__py3-none-any.whl → 2025.12.3__py3-none-any.whl

synapse_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""
+Export / Import Guidelines
+--------------------------
+
+1. Do NOT import the top-level package directly.
+   - All imports must start from at least two levels below the root package.
+     (e.g., `project.module.submodule` is allowed,
+            `project` 또는 `project.module` 단일 import는 금지)
+
+2. Wildcard import (`from x import *`) is strictly prohibited.
+   - 모든 외부 노출(export)은 명시적인 이름 기반으로 관리해야 한다.
+   - `__all__` 리스트를 통해 공개할 API를 명확히 정의할 것.
+
+3. Public API 를 구성할 때:
+   - 하위 모듈에서 export할 항목만 `__all__`에 선언한다.
+   - 내부 구현용 함수/클래스는 `_` prefix 를 사용하거나 `__all__`에 포함하지 않는다.
+
+4. 모듈 간 의존성은 최단 경로만 허용한다.
+   - 불필요한 상위/평행 패키지 import 경로는 금지하여 순환 의존성(circular dependency)을 방지한다.
+"""
+
+from synapse_sdk.shared import worker_process_setup_hook
+
+__all__ = ['worker_process_setup_hook']

synapse_sdk/cli/code_server.py

@@ -2,7 +2,9 @@
 
 import os
 import shutil
+import socket
 import subprocess
+import webbrowser
 from pathlib import Path
 from typing import Optional
 from urllib.parse import quote
@@ -141,6 +143,169 @@ def detect_and_encrypt_plugin(workspace_path: str) -> Optional[dict]:
         return None
 
 
+def is_ssh_session() -> bool:
+    """Check if we're in an SSH session.
+
+    Returns:
+        bool: True if in SSH session, False otherwise
+    """
+    return bool(os.environ.get('SSH_CONNECTION') or os.environ.get('SSH_CLIENT'))
+
+
+def is_vscode_terminal() -> bool:
+    """Check if we're running in a VSCode terminal.
+
+    Returns:
+        bool: True if in VSCode terminal, False otherwise
+    """
+    return os.environ.get('TERM_PROGRAM') == 'vscode'
+
+
+def is_vscode_ssh_session() -> bool:
+    """Check if we're in a VSCode terminal over SSH.
+
+    Returns:
+        bool: True if in VSCode terminal via SSH, False otherwise
+    """
+    return is_vscode_terminal() and is_ssh_session()
+
+
+def get_ssh_tunnel_instructions(port: int) -> str:
+    """Get SSH tunnel setup instructions for VSCode users.
+
+    Args:
+        port: The port number code-server is running on
+
+    Returns:
+        str: Instructions for setting up SSH tunnel
+    """
+    ssh_client = os.environ.get('SSH_CLIENT', '').split()[0] if os.environ.get('SSH_CLIENT') else 'your_server'
+
+    instructions = f"""
+📡 VSCode SSH Tunnel Setup:
+
+Since you're using VSCode's integrated terminal over SSH, you can access code-server locally by:
+
+1. Using VSCode's built-in port forwarding:
+   • Open Command Palette (Cmd/Ctrl+Shift+P)
+   • Type "Forward a Port"
+   • Enter port: {port}
+   • VSCode will automatically forward the port
+
+2. Or manually forward the port in a new local terminal:
+   ssh -L {port}:localhost:{port} {ssh_client}
+
+3. Then open in your local browser:
+   http://localhost:{port}
+"""
+    return instructions
+
+
+def open_browser_smart(url: str) -> bool:
+    """Open browser with smart fallback handling.
+
+    Attempts to open a browser using multiple methods, with appropriate
+    handling for SSH sessions and headless environments.
+
+    Args:
+        url: URL to open
+
+    Returns:
+        bool: True if browser was opened successfully, False otherwise
+    """
+    # Don't even try to open browser in SSH sessions (except VSCode can handle it)
+    if is_ssh_session() and not is_vscode_terminal():
+        return False
+
+    # Try Python's webbrowser module first (cross-platform)
+    try:
+        if webbrowser.open(url):
+            return True
+    except Exception:
+        pass
+
+    # Try platform-specific commands
+    commands = []
+
+    # Check for macOS
+    if shutil.which('open'):
+        commands.append(['open', url])
+
+    # Check for Linux with display
+    if os.environ.get('DISPLAY'):
+        if shutil.which('xdg-open'):
+            commands.append(['xdg-open', url])
+        if shutil.which('gnome-open'):
+            commands.append(['gnome-open', url])
+        if shutil.which('kde-open'):
+            commands.append(['kde-open', url])
+
+    # Try each command
+    for cmd in commands:
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=2)
+            if result.returncode == 0:
+                return True
+        except Exception:
+            continue
+
+    return False
+
+
+def is_port_in_use(port: int) -> bool:
+    """Check if a port is already in use.
+
+    Args:
+        port: Port number to check
+
+    Returns:
+        bool: True if port is in use, False otherwise
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(('127.0.0.1', port))
+            return False
+        except socket.error:
+            return True
+
+
+def get_process_on_port(port: int) -> Optional[str]:
+    """Get the name of the process using a specific port.
+
+    Args:
+        port: Port number to check
+
+    Returns:
+        str: Process name if found, None otherwise
+    """
+    try:
+        # Use lsof to find the process
+        result = subprocess.run(['lsof', '-i', f':{port}', '-t'], capture_output=True, text=True, timeout=2)
+
+        if result.returncode == 0 and result.stdout.strip():
+            # Get the PID
+            pid = result.stdout.strip().split('\n')[0]
+
+            # Get process details
+            proc_result = subprocess.run(['ps', '-p', pid, '-o', 'comm='], capture_output=True, text=True, timeout=2)
+
+            if proc_result.returncode == 0:
+                process_name = proc_result.stdout.strip()
+                # Check if it's a code-server process
+                if 'node' in process_name or 'code-server' in process_name:
+                    # Try to get more details
+                    cmd_result = subprocess.run(
+                        ['ps', '-p', pid, '-o', 'args='], capture_output=True, text=True, timeout=2
+                    )
+                    if cmd_result.returncode == 0 and 'code-server' in cmd_result.stdout:
+                        return 'code-server'
+                return process_name
+    except Exception:
+        pass
+
+    return None
+
+
 def is_code_server_installed() -> bool:
     """Check if code-server is installed locally.
 
@@ -154,7 +319,7 @@ def get_code_server_port() -> int:
     """Get code-server port from config file.
 
     Returns:
-        int: Port number from config, defaults to 8880 if not found
+        int: Port number from config, defaults to 8070 if not found
     """
     config_path = Path.home() / '.config' / 'code-server' / 'config.yaml'
 
@@ -163,7 +328,7 @@ def get_code_server_port() -> int:
             with open(config_path, 'r') as f:
                 config = yaml.safe_load(f)
 
-            # Parse bind-addr which can be in format "127.0.0.1:8880" or just ":8880"
+            # Parse bind-addr which can be in format "127.0.0.1:8070" or just ":8070"
             bind_addr = config.get('bind-addr', '')
             if ':' in bind_addr:
                 port_str = bind_addr.split(':')[-1]
@@ -176,31 +341,133 @@ def get_code_server_port() -> int:
         pass
 
     # Default port if config not found or invalid
-    return 8880
+    return 8070
 
 
-def launch_local_code_server(workspace_path: str, open_browser: bool = True) -> None:
+def launch_local_code_server(workspace_path: str, open_browser: bool = True, custom_port: Optional[int] = None) -> None:
     """Launch local code-server instance.
 
     Args:
         workspace_path: Directory to open in code-server
         open_browser: Whether to open browser automatically
+        custom_port: Optional custom port to use instead of config/default
     """
     try:
-        # Get port from config
-        port = get_code_server_port()
+        # Use custom port if provided, otherwise get from config
+        port = custom_port if custom_port else get_code_server_port()
+
+        # Check if port is already in use
+        if is_port_in_use(port):
+            process_name = get_process_on_port(port)
+
+            if process_name == 'code-server':
+                # Code-server is already running
+                click.echo(f'⚠️  Code-server is already running on port {port}')
+
+                # Create URL with folder query parameter
+                encoded_path = quote(workspace_path)
+                url_with_folder = f'http://localhost:{port}/?folder={encoded_path}'
+
+                # Ask user what to do
+                questions = [
+                    inquirer.List(
+                        'action',
+                        message='What would you like to do?',
+                        choices=[
+                            ('Use existing code-server instance', 'use_existing'),
+                            ('Stop existing and start new instance', 'restart'),
+                            ('Cancel', 'cancel'),
+                        ],
+                    )
+                ]
+
+                try:
+                    answers = inquirer.prompt(questions)
+
+                    if not answers or answers['action'] == 'cancel':
+                        click.echo('Cancelled')
+                        return
+
+                    if answers['action'] == 'use_existing':
+                        click.echo('\n✅ Using existing code-server instance')
+                        click.echo(f'   URL: {url_with_folder}')
+
+                        # Optionally open browser
+                        if open_browser:
+                            if is_vscode_ssh_session():
+                                # Special handling for VSCode SSH sessions
+                                click.echo(get_ssh_tunnel_instructions(port))
+                                click.echo(f'🔗 Remote URL: {url_with_folder}')
+                                click.echo(f'\n✨ After port forwarding, access at: http://localhost:{port}')
+                            elif is_ssh_session():
+                                click.echo('📝 SSH session detected - please open the URL in your local browser')
+                                click.echo(f'👉 URL: {url_with_folder}')
+                            elif open_browser_smart(url_with_folder):
+                                click.echo('✅ Browser opened successfully')
+                            else:
+                                click.echo('⚠️  Could not open browser automatically')
+                                click.echo(f'👉 URL: {url_with_folder}')
+                        return
+
+                    if answers['action'] == 'restart':
+                        # Stop existing code-server
+                        click.echo('Stopping existing code-server...')
+                        try:
+                            # Get PID of code-server process
+                            result = subprocess.run(
+                                ['lsof', '-i', f':{port}', '-t'], capture_output=True, text=True, timeout=2
+                            )
+
+                            if result.returncode == 0 and result.stdout.strip():
+                                pid = result.stdout.strip().split('\n')[0]
+                                subprocess.run(['kill', pid], timeout=5)
+
+                                # Wait a moment for process to stop
+                                import time
+
+                                time.sleep(2)
+
+                                click.echo('✅ Existing code-server stopped')
+                        except Exception as e:
+                            click.echo(f'⚠️  Could not stop existing code-server: {e}')
+                            click.echo('Please stop it manually and try again')
+                            return
+
+                except (KeyboardInterrupt, EOFError):
+                    click.echo('\nCancelled')
+                    return
+
+            else:
+                # Another process is using the port
+                click.echo(f'❌ Port {port} is already in use by: {process_name or "unknown process"}')
+                if not custom_port:
+                    click.echo('\nYou can:')
+                    click.echo('1. Stop the process using the port')
+                    click.echo('2. Use a different port with --port option (e.g., --port 8071)')
+                    click.echo('3. Change the default port in ~/.config/code-server/config.yaml')
+                else:
+                    click.echo(f'Please try a different port or stop the process using port {port}')
+                return
 
         # Create URL with folder query parameter
         encoded_path = quote(workspace_path)
         url_with_folder = f'http://localhost:{port}/?folder={encoded_path}'
 
         # Basic code-server command - let code-server handle the workspace internally
-        cmd = ['code-server', workspace_path]
+        cmd = ['code-server']
+
+        # Add custom port binding if specified
+        if custom_port:
+            cmd.extend(['--bind-addr', f'127.0.0.1:{port}'])
+
+        cmd.append(workspace_path)
 
         if not open_browser:
             cmd.append('--disable-getting-started-override')
 
         click.echo(f'🚀 Starting local code-server for workspace: {workspace_path}')
+        if custom_port:
+            click.echo(f'   Using custom port: {port}')
         click.echo(f'   URL: {url_with_folder}')
         click.echo('   Press Ctrl+C to stop the server')
 
@@ -221,17 +488,18 @@ def launch_local_code_server(workspace_path: str, open_browser: bool = True) ->
             time.sleep(3)
 
             # Open browser with folder parameter
-            try:
-                result = subprocess.run(['xdg-open', url_with_folder], capture_output=True, text=True, timeout=2)
-                if result.returncode != 0:
-                    click.echo('⚠️  Could not open browser automatically (no display?)')
-                    click.echo(f'👉 Please manually open: {url_with_folder}')
-                else:
-                    click.echo('✅ Browser opened successfully')
-            except (subprocess.TimeoutExpired, FileNotFoundError):
-                click.echo('⚠️  Could not open browser (headless environment)')
-                click.echo(f'👉 Please manually open: {url_with_folder}')
-            except Exception:
+            if is_vscode_ssh_session():
+                # Special handling for VSCode SSH sessions
+                click.echo(get_ssh_tunnel_instructions(port))
+                click.echo(f'🔗 Remote URL: {url_with_folder}')
+                click.echo(f'\n✨ After port forwarding, access at: http://localhost:{port}')
+            elif is_ssh_session():
+                click.echo('📝 SSH session detected - please open the URL in your local browser')
+                click.echo(f'👉 URL: {url_with_folder}')
+            elif open_browser_smart(url_with_folder):
+                click.echo('✅ Browser opened successfully')
+            else:
+                click.echo('⚠️  Could not open browser automatically')
                 click.echo(f'👉 Please manually open: {url_with_folder}')
 
             # Wait for the server thread (blocking)
@@ -333,19 +601,22 @@ def run_agent_code_server(agent: Optional[str], workspace: str, open_browser: bo
     if open_browser and url:
         click.echo('\nAttempting to open in browser...')
 
-        # Try to open browser, suppressing stderr to avoid xdg-open noise
-        try:
-            # Use subprocess to suppress xdg-open errors
-            result = subprocess.run(['xdg-open', url], capture_output=True, text=True, timeout=2)
-            if result.returncode != 0:
-                click.echo('⚠️  Could not open browser automatically (no display?)')
-                click.echo(f'👉 Please manually open: {url}')
-        except (subprocess.TimeoutExpired, FileNotFoundError):
-            # xdg-open not available or timed out
-            click.echo('⚠️  Could not open browser (headless environment)')
-            click.echo(f'👉 Please manually open: {url}')
-        except Exception:
-            # Fallback for other errors
+        if is_vscode_ssh_session():
+            # Extract port from URL for instructions
+            import re
+
+            port_match = re.search(r':(\d+)', url)
+            if port_match:
+                agent_port = int(port_match.group(1))
+                click.echo(get_ssh_tunnel_instructions(agent_port))
+            click.echo(f'🔗 Remote URL: {url}')
+        elif is_ssh_session():
+            click.echo('📝 SSH session detected - please open the URL in your local browser')
+            click.echo(f'👉 URL: {url}')
+        elif open_browser_smart(url):
+            click.echo('✅ Browser opened successfully')
+        else:
+            click.echo('⚠️  Could not open browser automatically')
             click.echo(f'👉 Please manually open: {url}')
 
     # Show additional instructions
@@ -364,7 +635,8 @@ def run_agent_code_server(agent: Optional[str], workspace: str, open_browser: bo
 @click.option('--agent', help='Agent name or ID')
 @click.option('--open-browser/--no-open-browser', default=True, help='Open in browser')
 @click.option('--workspace', help='Workspace directory path (defaults to current directory)')
-def code_server(agent: Optional[str], open_browser: bool, workspace: Optional[str]):
+@click.option('--port', type=int, help='Port to bind code-server (default: from config or 8070)')
+def code_server(agent: Optional[str], open_browser: bool, workspace: Optional[str], port: Optional[int]):
     """Open code-server either through agent or locally."""
 
     # Get current working directory if workspace not specified
@@ -405,7 +677,7 @@ def code_server(agent: Optional[str], open_browser: bool, workspace: Optional[st
 
         elif answers['option'] == 'local':
             click.echo('\n💻 Starting local code-server...')
-            launch_local_code_server(workspace, open_browser)
+            launch_local_code_server(workspace, open_browser, port)
 
         elif answers['option'] == 'install':
             show_code_server_installation_help()

synapse_sdk/clients/agent/__init__.py

@@ -1,10 +1,11 @@
+from synapse_sdk.clients.agent.container import ContainerClientMixin
 from synapse_sdk.clients.agent.core import CoreClientMixin
 from synapse_sdk.clients.agent.ray import RayClientMixin
 from synapse_sdk.clients.agent.service import ServiceClientMixin
 from synapse_sdk.clients.exceptions import ClientError
 
 
-class AgentClient(CoreClientMixin, RayClientMixin, ServiceClientMixin):
+class AgentClient(CoreClientMixin, RayClientMixin, ServiceClientMixin, ContainerClientMixin):
     name = 'Agent'
     agent_token = None
     user_token = None

synapse_sdk/clients/agent/container.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional, Union
+
+from synapse_sdk.clients.base import BaseClient
+
+
+class ContainerClientMixin(BaseClient):
+    """Client mixin exposing the agent container management API."""
+
+    def health_check(self):
+        """Perform a health check on Docker sock."""
+        path = 'health/'
+        return self._get(path)
+
+    def list_containers(self, params: Optional[Dict[str, Any]] = None, *, list_all: bool = False):
+        """List containers managed by the agent.
+
+        Args:
+            params: Optional query parameters (e.g. {'status': 'running'}).
+            list_all: When True, returns ``(generator, count)`` covering every page.
+
+        Returns:
+            dict | tuple: Standard paginated response or a tuple for ``list_all``.
+        """
+        path = 'containers/'
+        return self._list(path, params=params, list_all=list_all)
+
+    def get_container(self, container_id: Union[int, str]):
+        """Retrieve details for a specific container."""
+        path = f'containers/{container_id}/'
+        return self._get(path)
+
+    def delete_container(self, container_id: Union[int, str]):
+        """Stop and remove a container."""
+        path = f'containers/{container_id}/'
+        return self._delete(path)
+
+    def create_container(
+        self,
+        plugin_release: Optional[Union[str, Any]] = None,
+        *,
+        model: Optional[int] = None,
+        params: Optional[Dict[str, Any]] = None,
+        envs: Optional[Dict[str, str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        labels: Optional[Iterable[str]] = None,
+        plugin_file: Optional[Union[str, Path]] = None,
+    ):
+        """Create a Docker container running a plugin Gradio interface.
+
+        If a container with the same ``plugin_release`` and ``model`` already exists,
+        it will be restarted instead of creating a new one.
+
+        Args:
+            plugin_release: Plugin identifier. Accepts either ``synapse_sdk.plugins.models.PluginRelease``
+                instances or the ``"<plugin_code>@<version>"`` shorthand string.
+            model: Optional model ID to associate with the container. Used together with
+                ``plugin_release`` to uniquely identify a container for restart behavior.
+            params: Arbitrary parameters forwarded to ``plugin/gradio_interface.py``.
+            envs: Extra environment variables injected into the container.
+            metadata: Additional metadata stored with the container record.
+            labels: Optional container labels/tags for display or filtering.
+            plugin_file: Optional path to a packaged plugin release to upload directly.
+                The archive must contain ``plugin/gradio_interface.py``.
+
+        Returns:
+            dict: Container creation response that includes the exposed Gradio endpoint.
+                If an existing container was restarted, the response includes ``restarted: True``.
+
+        Raises:
+            FileNotFoundError: If ``plugin_file`` is provided but does not exist.
+            ValueError: If neither ``plugin_release`` nor ``plugin_file`` are provided.
+        """
+        if not plugin_release and not plugin_file:
+            raise ValueError('Either "plugin_release" or "plugin_file" must be provided to create a container.')
+
+        data: Dict[str, Any] = {}
+
+        if plugin_release:
+            data.update(self._serialize_plugin_release(plugin_release))
+
+        if model is not None:
+            data['model'] = model
+
+        optional_payload = {
+            'params': params if params is not None else None,
+            'envs': envs or None,
+            'metadata': metadata or None,
+            'labels': list(labels) if labels else None,
+        }
+        data.update({key: value for key, value in optional_payload.items() if value is not None})
+
+        files = None
+        if plugin_file:
+            file_path = Path(plugin_file)
+            if not file_path.exists():
+                raise FileNotFoundError(f'Plugin release file not found: {file_path}')
+            files = {'file': file_path}
+        post_kwargs = {'data': data}
+        if files:
+            post_kwargs['files'] = files
+
+        return self._post('containers/', **post_kwargs)
+
+    @staticmethod
+    def _serialize_plugin_release(plugin_release: Union[str, Any]) -> Dict[str, Any]:
+        """Normalize plugin release data for API payloads."""
+        if hasattr(plugin_release, 'code') and hasattr(plugin_release, 'version'):
+            payload = {
+                'plugin_release': plugin_release.code,
+                'plugin': getattr(plugin_release, 'plugin', None),
+                'version': plugin_release.version,
+            }
+
+            # Extract action and entrypoint from the first action in the config
+            if hasattr(plugin_release, 'config') and 'actions' in plugin_release.config:
+                actions = plugin_release.config['actions']
+                if actions:
+                    # Get the first action (typically 'gradio')
+                    action_name = next(iter(actions.keys()))
+                    action_config = actions[action_name]
+                    payload['action'] = action_name
+
+                    # Convert entrypoint from dotted path to file path
+                    if 'entrypoint' in action_config:
+                        entrypoint = action_config['entrypoint']
+                        # Convert 'plugin.gradio_interface.app' to 'plugin/gradio_interface.py'
+                        file_path = entrypoint.rsplit('.', 1)[0].replace('.', '/') + '.py'
+                        payload['entrypoint'] = file_path
+
+            return payload
+
+        if isinstance(plugin_release, str):
+            payload = {'plugin_release': plugin_release}
+            if '@' in plugin_release:
+                plugin, version = plugin_release.rsplit('@', 1)
+                payload.setdefault('plugin', plugin)
+                payload.setdefault('version', version)
+            return payload
+
+        raise TypeError('plugin_release must be a PluginRelease instance or a formatted string "code@version"')