Skip to main content

​
Overview

The Interactive Runtime provides the core runtime that powers both TUI interactive mode and debug non-interactive mode. It manages LSP and ACP subsystem lifecycle with graceful degradation.

​
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

ParameterTypeDefaultDescription
workspacestr”.”Workspace root directory
lsp_enabledboolTrueEnable LSP code intelligence
acp_enabledboolTrueEnable ACP action orchestration
approval_modestr”manual”Approval mode: manual, auto, scoped
trace_enabledboolFalseEnable trace logging
trace_filestrNonePath to save trace file
json_outputboolFalseOutput JSON format
timeoutfloat60.0Operation timeout in seconds
modelstrNoneLLM model to use
verboseboolFalseVerbose 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

StatusDescription
not_startedSubsystem not initialized
startingSubsystem is starting
readySubsystem is ready for use
failedSubsystem failed to start
stoppedSubsystem 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 --interactive --lsp

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

# Enable tracing
praisonai --interactive --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