> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Runtime Module

> Unified core runtime for all interactive modes with session management and approval flows

## Overview

The Interactive Runtime provides a **unified core runtime** that powers all interactive modes in PraisonAI:

* `praisonai chat` - Interactive chat mode
* `praisonai chat` - Interactive terminal chat mode
* `praisonai tui launch` - Full-screen TUI mode

All modes share the same:

* Session storage and continuation
* Tool dispatch and loading
* Permission/approval semantics
* Event-based architecture

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai
```

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonai.cli.features import InteractiveRuntime, RuntimeConfig

async def main():
    # Configure runtime
    config = RuntimeConfig(
        workspace="./my_project",
        lsp_enabled=True,
        acp_enabled=True,
        approval_mode="auto",
        trace_enabled=True
    )
    
    # Create and start runtime
    runtime = InteractiveRuntime(config)
    status = await runtime.start()
    
    print(f"LSP ready: {runtime.lsp_ready}")
    print(f"ACP ready: {runtime.acp_ready}")
    print(f"Read-only: {runtime.read_only}")
    
    # Use runtime for operations...
    
    await runtime.stop()

asyncio.run(main())
```

## Configuration

### RuntimeConfig

| Parameter       | Type  | Default  | Description                         |
| --------------- | ----- | -------- | ----------------------------------- |
| `workspace`     | str   | "."      | Workspace root directory            |
| `lsp_enabled`   | bool  | True     | Enable LSP code intelligence        |
| `acp_enabled`   | bool  | True     | Enable ACP action orchestration     |
| `approval_mode` | str   | "manual" | Approval mode: manual, auto, scoped |
| `trace_enabled` | bool  | False    | Enable trace logging                |
| `trace_file`    | str   | None     | Path to save trace file             |
| `json_output`   | bool  | False    | Output JSON format                  |
| `timeout`       | float | 60.0     | Operation timeout in seconds        |
| `model`         | str   | None     | LLM model to use                    |
| `verbose`       | bool  | False    | Verbose output                      |

## Runtime Status

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
status = runtime.get_status()
```

Returns:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "started": true,
  "workspace": "/path/to/project",
  "lsp": {
    "enabled": true,
    "status": "ready",
    "ready": true,
    "error": null
  },
  "acp": {
    "enabled": true,
    "status": "ready",
    "ready": true,
    "error": null
  },
  "read_only": false,
  "approval_mode": "auto"
}
```

## Subsystem States

| Status        | Description                |
| ------------- | -------------------------- |
| `not_started` | Subsystem not initialized  |
| `starting`    | Subsystem is starting      |
| `ready`       | Subsystem is ready for use |
| `failed`      | Subsystem failed to start  |
| `stopped`     | Subsystem has been stopped |

## LSP Operations

When LSP is ready, you can use code intelligence:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get symbols in a file
symbols = await runtime.lsp_get_symbols("main.py")

# Get definition location
definitions = await runtime.lsp_get_definition("main.py", line=10, col=5)

# Get references
references = await runtime.lsp_get_references("main.py", line=10, col=5)

# Get diagnostics
diagnostics = await runtime.lsp_get_diagnostics("main.py")
```

## ACP Operations

When ACP is ready, you can create and apply action plans:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Create a plan
plan = await runtime.acp_create_plan("Create a new file")

# Apply a plan
result = await runtime.acp_apply_plan(plan, auto_approve=True)
```

## Tracing

Enable tracing to capture all operations:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
config = RuntimeConfig(
    workspace="./project",
    trace_enabled=True,
    trace_file="trace.json"
)
runtime = InteractiveRuntime(config)
await runtime.start()

# ... perform operations ...

# Save trace
runtime.save_trace("my_trace.json")

# Get trace object
trace = runtime.get_trace()
print(trace.to_dict())
```

## Graceful Degradation

The runtime handles subsystem failures gracefully:

* **LSP fails**: Code intelligence falls back to regex-based extraction
* **ACP fails**: Runtime enters read-only mode (no file modifications)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
if runtime.read_only:
    print("Warning: ACP unavailable, read-only mode")
```

## CLI Integration

The runtime integrates with CLI flags:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable LSP
praisonai chat --lsp

# Enable ACP with auto-approval
praisonai chat --acp --approval auto

# Enable tracing
praisonai chat --trace --trace-file session.json
```

## Operational Notes

### Performance

* Subsystems start in parallel for faster initialization
* LSP client is lazy-loaded only when enabled
* ACP session is lightweight (in-process)

### Dependencies

* `pylsp` (optional) - For Python LSP support
* `pyright` (optional) - Alternative Python LSP

### Production Caveats

* LSP startup may take a few seconds for large workspaces
* Trace files can grow large for long sessions
* ACP session is in-memory; external storage needed for persistence

## InteractiveCore (Unified Runtime)

The new `InteractiveCore` provides a unified runtime for all interactive modes:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.cli.interactive import InteractiveCore, InteractiveConfig

# Create config
config = InteractiveConfig(
    model="gpt-4o-mini",
    continue_session=True,  # Resume last session
    files=["README.md"],    # Attach files
    
)

# Create core
core = InteractiveCore(config=config)

# Create or continue session
if config.continue_session:
    session_id = core.continue_session()
else:
    session_id = core.create_session(title="My Session")

# Execute prompt
import asyncio
response = asyncio.run(core.prompt("Hello!"))
print(response)
```

### CLI Flags

| Flag          | Short | Description              |
| ------------- | ----- | ------------------------ |
| `--model`     | `-m`  | LLM model to use         |
| `--session`   | `-s`  | Session ID to resume     |
| `--continue`  | `-c`  | Continue last session    |
| `--file`      | `-f`  | Attach file(s) to prompt |
| `--workspace` | `-w`  | Workspace directory      |
| `--verbose`   | `-v`  | Verbose output           |
| `--memory`    |       | Enable memory            |

### Session Management

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List sessions
praisonai session list

# Export session
praisonai session export <session_id> --output session.json

# Import session
praisonai session import session.json

# Continue last session
praisonai chat --continue "What was my last question?"
```

### Approval Modes

The runtime supports three approval modes:

| Mode     | Description                           |
| -------- | ------------------------------------- |
| `prompt` | Ask user for each action (default)    |
| `auto`   | Auto-approve all actions              |
| `reject` | Reject all actions requiring approval |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
config = InteractiveConfig(approval_mode="auto")
```

## Related

* [Agent-Centric Tools](/cli/agent-tools) - Tools powered by this runtime
* [Debug CLI](/cli/debug-cli) - Debug commands
* [ACP](/cli/acp) - Agent Communication Protocol