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

pip install praisonai

Quick Start

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

status = runtime.get_status()

Returns:

{
  "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:

# 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:

# 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:

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)

if runtime.read_only:
    print("Warning: ACP unavailable, read-only mode")

CLI Integration

The runtime integrates with CLI flags:

# 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:

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

# 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

config = InteractiveConfig(approval_mode="auto")

Related

• Agent-Centric Tools - Tools powered by this runtime
• Debug CLI - Debug commands
• ACP - Agent Communication Protocol