Adapter Development

---
name: adapter-development
description: Comprehensive guide for AIDB debug adapter development. Covers component-based
  architecture, language-specific patterns (Python/debugpy, JavaScript/vscode-js-debug,
  Java/java-debug), lifecycle hooks, process management, port management, launch orchestration,
  resource cleanup, child sessions, and common pitfalls. Essential for developing
  or maintaining AIDB debug adapters.
---

# AIDB Adapter Development Skill

## Executive Summary

AIDB debug adapters provide language-agnostic debugging capabilities through the Debug Adapter Protocol (DAP). The architecture is **component-based** - adapters delegate to specialized components rather than implementing everything in monolithic classes.

**For comprehensive architecture details**, see `docs/developer-guide/overview.md` for the complete system architecture and data flow diagrams.

### Core Architecture

```
DebugAdapter (base class)
├── ProcessManager       - Process lifecycle (launch, monitor, stop, cleanup)
├── PortManager          - Port acquisition, verification, release
├── LaunchOrchestrator   - Launch sequence coordination
├── TargetResolver       - Target type detection and normalization
├── SourcePathResolver   - Source path resolution for remote debugging
└── AdapterHooksMixin    - Lifecycle hooks for extension points
```

### Key Principles

1. **Component Delegation**: Adapters delegate to focused components (ProcessManager, PortManager, LaunchOrchestrator)
1. **Lifecycle Hooks**: Customize behavior via hooks rather than overriding entire methods
1. **Resource Management**: Centralized cleanup via ResourceManager
1. **Human-Cadence Debugging**: Operations happen at human speed, not API speed
1. **Language-Agnostic API**: Same Python API works across Python, JavaScript, Java

## Resource Files

This skill is organized into focused resource files for language-specific patterns:

- **[python-adapter-patterns.md](resources/python-adapter-patterns.md)** - debugpy configuration, module vs script patterns
- **[javascript-adapter-patterns.md](resources/javascript-adapter-patterns.md)** - vscode-js-debug, child sessions, Node.js patterns
- **[java-adapter-patterns.md](resources/java-adapter-patterns.md)** - java-debug + JDT LS integration, compilation

## Related Skills

When working on adapter development, you may also need:

- **dap-protocol-guide** - Adapters heavily rely on DAP protocol types and request/response patterns
- **testing-strategy** - Adapters must be tested using E2E patterns with DebugInterface abstraction
- **code-reuse-enforcement** - Always check for existing utilities before implementing adapter components

## Quick Start: Creating a New Adapter

```python
from aidb.adapters.base import DebugAdapter
from aidb.adapters.base.config import AdapterConfig

class MyLanguageAdapter(DebugAdapter):
    """My language debug adapter using component architecture."""

    def __init__(self, session, ctx=None, config=None, **kwargs):
        if config is None:
            config = MyLanguageConfig()

        super().__init__(
            session=session,
            ctx=ctx,
            config=config,
            **kwargs
        )

        # Register language-specific hooks
        self._register_my_language_hooks()

    def _register_my_language_hooks(self):
        """Register language-specific lifecycle hooks."""
        self.register_hook(
            LifecycleHook.PRE_LAUNCH,
            self._validate_environment,
            priority=90  # High priority = runs first
        )

    async def _validate_environment(self, context: HookContext):
        """Pre-launch hook to validate environment."""
        # Validation logic here
        pass

    async def _build_launch_command(self, target, adapter_host,
                                   adapter_port, args=None):
        """Build the command to launch the debug adapter."""
        return [
            "/path/to/debug/adapter",
            "--host", adapter_host,
            "--port", str(adapter_port),
            target
        ]

    def _add_adapter_specific_vars(self, env: dict) -> dict:
        """Add language-specific environment variables."""
        env["MY_LANG_DEBUG"] = "1"
        return env

    def _create_target_resolver(self) -> "TargetResolver":
        """Create language-specific target resolver."""
        return MyLanguageTargetResolver(adapter=self, ctx=self.ctx)

    def _create_source_path_resolver(self) -> "SourcePathResolver":
        """Create language-specific source path resolver for remote debugging."""
        return MyLanguageSourcePathResolver(adapter=self, ctx=self.ctx)

    def _get_process_name_pattern(self) -> str:
        """Get process name pattern for cleanup."""
        return "my-language-debug"
```

## Component Access Patterns

### ProcessManager Usage

See `ProcessManager` in `src/aidb/adapters/base/components/process_manager.py` for full implementation.

```python
from aidb.resources.process_tags import ProcessType

# Launch subprocess with session tagging
proc = await self._process_manager.launch_subprocess(
    cmd=cmd,
    env=env,
    session_id=self.session.id,
    language=self.config.language,
    process_type=ProcessType.ADAPTER,  # String constant: "adapter", "debuggee", or "lsp_server"
    kwargs={}
)

# Wait for adapter readiness
await self._process_manager.wait_for_adapter_ready(port, start_time)

# Get process status
if self._process_manager.is_alive:
    pid = self._process_manager.pid
```

### PortManager Usage

See `PortManager` in `src/aidb/adapters/base/components/port_manager.py` for full implementation. Key methods:

- `acquire(requested_port=None)` - Acquire and verify port availability
- `release()` - Release the port
- `port` property - Get current port

### LaunchOrchestrator Usage

See `LaunchOrchestrator` in `src/aidb/adapters/base/components/launch_orchestrator.py` for full implementation. Key methods:

- `launch(target, port, args)` - Simple launch with target file
- `launch_with_config(launch_config, port, workspace_root)` - Launch with VS Code launch.json configuration

### SourcePathResolver Usage

See `SourcePathResolver` in `src/aidb/adapters/base/source_path_resolver.py` for base implementation. Each language adapter implements its own resolver:

- **Python**: `src/aidb/adapters/lang/python/source_path_resolver.py` - Handles site-packages, venv, egg paths
- **JavaScript**: `src/aidb/adapters/lang/javascript/source_path_resolver.py` - Handles node_modules, webpack paths
- **Java**: `src/aidb/adapters/lang/java/source_path_resolver.py` - Handles JAR notation, Maven layouts

Key methods:

- `extract_relative_path(file_path)` - Extract language-specific relative path from adapter-returned path
- `resolve(file_path, source_paths)` - Resolve remote path to local source file

## Lifecycle Hooks Reference

Hooks execute in priority order (lower number = runs first):

### Hook Priorities

- **90-100**: Critical validation (environment, target file)
- **70-80**: Setup/preparation (workspaces, configurations)
- **50**: Default priority
- **20-30**: Post-operation delays/waits
- **10**: Cleanup operations

### Common Hooks

```python
# Pre-launch validation
self.register_hook(
    LifecycleHook.PRE_LAUNCH,
    self._validate_environment,
    priority=90
)

# Post-launch setup
self.register_hook(
    LifecycleHook.POST_LAUNCH,
    self._wait_for_ready,
    priority=20
)

# Post-stop cleanup
self.register_hook(
    LifecycleHook.POST_STOP,
    self._cleanup_resources,
    priority=10
)
```

## Code Reuse: Existing Utilities

Before implementing new functionality, check these shared resources:

### Base Classes

- **DebugAdapter** (`aidb/adapters/base/adapter.py`) - Base adapter with component architecture
- **AdapterConfig** (`aidb/adapters/base/config.py`) - Configuration base class
- **BaseLaunchConfig** (`aidb/adapters/base/launch.py`) - VS Code launch.json support

### Components

- **ProcessManager** (`aidb/adapters/base/components/process_manager.py`)
- **PortManager** (`aidb/adapters/base/components/port_manager.py`)
- **LaunchOrchestrator** (`aidb/adapters/base/components/launch_orchestrator.py`)

### Utilities

- **AdapterBinaryLocator** (`aidb/adapters/utils/binary_locator.py`) - Find adapter binaries
- **AdapterOutputCapture** (`aidb/adapters/utils/output_capture.py`) - Capture stdout/stderr
- **AdapterTraceLogManager** (`aidb/adapters/utils/trace_log.py`) - Trace log management

### Common Patterns (`aidb_common/`)

See source code docstrings in `src/aidb_common/` for detailed API documentation.

- **Obj** (`aidb_common/patterns/`) - Base class with context support
- **normalize_path()** (`aidb_common/path.py`) - Path normalization
- **config** (`aidb_common/config/`) - Environment variable reading
- **Language** enum (`aidb_common/constants.py`) - Supported language constants

## Launch Configuration Patterns

Adapters can support VS Code launch.json configurations:

```python
def get_launch_configuration(self) -> dict[str, Any]:
    """Get launch configuration for DAP Launch request."""
    config = {
        "type": "mylang",
        "request": "launch",
        "name": "Debug MyLang",
        "program": self._target_file,
        "args": self._target_args,
        "cwd": self._target_cwd,
        "env": self._target_env,
    }
    return config
```

## Environment Variable Patterns

See `src/aidb_common/env/` for environment handling utilities (reader.py, resolver.py).

Use the template method pattern for environment preparation:

```python
def _prepare_environment(self) -> dict[str, str]:
    """Prepare environment (base implementation)."""
    env = self._load_base_environment()
    env = self._add_trace_configuration(env)
    return self._add_adapter_specific_vars(env)

def _add_adapter_specific_vars(self, env: dict) -> dict:
    """Add language-specific variables (override this)."""
    env["MY_LANG_HOME"] = "/path/to/lang"
    return env
```

## Resource Cleanup Patterns

Always implement proper cleanup in hooks:

```python
async def stop(self) -> None:
    """Stop the debug adapter and clean up."""
    context = await self.execute_hook(LifecycleHook.PRE_STOP)

    if not context.cancelled:
        # Stop process manager
        await self._process_manager.stop()

        # Release port
        if self.port:
            self._port_manager.release()

        # Cleanup auxiliary components
        if self._trace_manager:
            self._trace_manager.cleanup()

    await self.execute_hook(LifecycleHook.POST_STOP)
```

## Process Tagging for Orphan Detection

All AIDB-spawned processes are tagged with environment variables for safe cleanup:

```python
from aidb.resources.process_tags import ProcessType

# Automatically handled by ProcessManager
proc = await self.process_manager.launch_subprocess(
    cmd=cmd,
    env=env,
    session_id=self.session.id,        # Tags process with session ID
    language=self.config.language,      # Tags with language
    process_type=ProcessType.ADAPTER,   # String constant: "adapter", "debuggee", or "lsp_server"
    kwargs={}
)
```

Tags enable:

- Safe orphan detection across sessions
- Cleanup of only AIDB-owned processes
- Session-to-process mapping

## DAP Protocol Reference

The authoritative DAP protocol reference is in `src/aidb/dap/protocol/` - fully typed and always up-to-date.

```python
from aidb.dap.protocol.types import (
    Capabilities,
    InitializeRequest,
    LaunchRequest,
    SetBreakpointsRequest,
)
```

## Testing Your Adapter

Use the shared test infrastructure:

```python
# Test with API directly
session = await client.start_session(
    target="/path/to/file",
    language="mylang",
    breakpoints=[{"line": 10}]
)

# Test with launch.json
session = await client.start_session(
    target="/path/to/file",
    language="mylang",
    launch_config_name="Debug MyLang",
    workspace_root="/path/to/project"
)
```

## Navigation to Resource Files

For detailed language-specific patterns and examples:

1. **Python Adapter Patterns** → `resources/python-adapter-patterns.md`
   - debugpy configuration, module vs script patterns, trace logging
1. **JavaScript Adapter Patterns** → `resources/javascript-adapter-patterns.md`
   - vscode-js-debug, child sessions, Node.js debugging, breakpoint transfer
1. **Java Adapter Patterns** → `resources/java-adapter-patterns.md`
   - java-debug + JDT LS integration, compilation, pooling patterns

## Important Reminders

1. **Don't override entire methods** - Use lifecycle hooks for customization
1. **Don't manage processes directly** - Use ProcessManager component
1. **Don't handle ports manually** - Use PortManager component
1. **Don't forget cleanup** - Register POST_STOP hooks
1. **Don't block async operations** - Use await for I/O operations
1. **Check existing code first** - Look for reusable utilities before implementing

## File Paths Reference

All file paths mentioned in this skill are relative to the repo root:

- Base adapter: `src/aidb/adapters/base/adapter.py`
- Components: `src/aidb/adapters/base/components/`
- SourcePathResolver base: `src/aidb/adapters/base/source_path_resolver.py`
- Python adapter: `src/aidb/adapters/lang/python/python.py`
- Python source resolver: `src/aidb/adapters/lang/python/source_path_resolver.py`
- JavaScript adapter: `src/aidb/adapters/lang/javascript/javascript.py`
- JavaScript source resolver: `src/aidb/adapters/lang/javascript/source_path_resolver.py`
- Java adapter: `src/aidb/adapters/lang/java/java.py`
- Java source resolver: `src/aidb/adapters/lang/java/source_path_resolver.py`
- DAP protocol: `src/aidb/dap/protocol/` (types.py, requests.py, responses.py, events.py, bodies.py, base.py)