# PROP: Pluggable I/O Adapter Protocol for Multi-Channel Support

## Source
- **URL**: https://github.com/openclaw/openclaw (OpenClaw -- 100k+ stars, Channel Layer pattern), https://github.com/tisu19021997/langclaw (Langclaw -- Python multi-channel framework), https://vercel.com/changelog/chat-sdk-adds-telegram-adapter-support (Vercel Chat SDK adapter pattern)
- **Author**: OpenClaw team, tisu19021997 (Langclaw), Vercel
- **Date**: 2025-2026

## Summary
Define a Python Protocol (abstract interface) for I/O adapters that decouples iEvo's core orchestration from any specific interface. Implement the TUI adapter (Textual, already exists) and CLI adapter (headless, for CI/automation) first. The protocol enables future adapters for Telegram, Discord, Web (WebSocket), and desktop (Tauri IPC) without changing core logic. Inspired by OpenClaw's Channel Layer pattern and Langclaw's `app.add_channel()` design.

## Relevance to iEvo
iEvo's TUI (Textual) is currently hardwired as the only interface. The structured interview model (spec-writer asks questions, user answers) is inherently channel-independent -- the same conversation flow works on Telegram, Discord, or a web form. Decoupling I/O now means every future channel is an adapter plugin, not a core rewrite.

## Proposed Change

### 1. I/O Adapter Protocol
Create `src/ievo/adapters/protocol.py`:
```python
from typing import Protocol, AsyncIterator

class IOAdapter(Protocol):
    async def start(self) -> None: ...
    async def send_message(self, response: AgentResponse) -> None: ...
    async def receive_messages(self) -> AsyncIterator[UserMessage]: ...
    async def send_structured_prompt(self, prompt: StructuredPrompt) -> UserResponse: ...
    async def stop(self) -> None: ...
```

### 2. Message types
Create `src/ievo/adapters/messages.py`:
- `UserMessage`: text, channel, user_id, session_id, attachments
- `AgentResponse`: text, structured data, actions (buttons, forms)
- `StructuredPrompt`: question, options, validation rules, input type
- `UserResponse`: value, selected_option

### 3. TUI adapter (refactor)
Refactor `src/ievo/tui/app.py` to implement `IOAdapter`:
- `send_message()` -> updates Textual widgets
- `receive_messages()` -> reads from Textual input widget
- `send_structured_prompt()` -> renders interactive prompt in TUI

### 4. CLI adapter (new, for headless/CI)
Create `src/ievo/adapters/cli_adapter.py`:
- Reads from stdin, writes to stdout
- Structured prompts become simple text questions
- Enables `ievo --headless` mode for CI pipelines

### 5. Adapter registry
Adapters register in `plugin.yaml` or programmatically via `ievo.adapters.register()`. iEvo selects the adapter based on launch context (TUI by default, CLI if `--headless`, Telegram if configured).

## Affected Components
- New: `src/ievo/adapters/` (package: protocol, messages, cli_adapter)
- Modified: `src/ievo/tui/app.py` (refactor to implement IOAdapter)
- Modified: `src/ievo/cli.py` (adapter selection based on launch mode)
- Modified: `src/ievo/core/config.py` (adapter configuration)

## Scores
- Applicability: 4/5 (TUI refactor + CLI adapter are immediate value; other channels are future)
- Effort: medium (protocol definition and TUI refactor; each new adapter is low effort after that)
- Impact: UX (same experience everywhere), reliability (testable adapter interfaces)
