# Symbiont REPL Guide


The Symbiont REPL (Read-Eval-Print Loop) provides an interactive environment for developing, testing, and debugging Symbiont agents and DSL code.

> **Looking for an interactive TUI?** [`symbi shell`](/symbi-shell) (Beta) wraps the same `repl_core` engine this guide covers, plus an LLM orchestrator, a full command catalogue (`/spawn`, `/run`, `/chain`, …), and remote attach. Use the REPL when you want a scriptable JSON-RPC surface for IDE integration; use the shell when you want conversational authoring against the same runtime.

## Features

- **Interactive DSL Evaluation**: Execute Symbiont DSL code in real-time
- **Agent Lifecycle Management**: Create, start, stop, pause, resume, and destroy agents
- **Execution Monitoring**: Real-time monitoring of agent execution with statistics and traces
- **Policy Enforcement**: Built-in policy checking and capability gating
- **Session Management**: Snapshot and restore REPL sessions
- **JSON-RPC Protocol**: Programmatic access via JSON-RPC over stdio
- **LSP Support**: Language Server Protocol for IDE integration

## Getting Started

### Starting the REPL

```bash
# Interactive REPL mode
symbi repl

# JSON-RPC server mode over stdio (for IDE integration)
symbi repl --stdio
```

> **Note:** The `--config` flag is not yet supported. Configuration is read from the default `symbiont.toml` location. Custom config support is planned for a future release.

### Basic Usage

```rust
# Define an agent
metadata {
  version = "1.0.0"
  description = "A simple greeting agent"
}

agent greeter(name: String) -> String {
  capabilities = ["greet"]

  policy safe {
    allow: read(name) if true
  }

  with memory = "ephemeral" {
    return greet(name);
  }
}
```

## REPL Commands

### Agent Management

| Command | Description |
|---------|-------------|
| `:agents` | List all agents |
| `:agent list` | List all agents |
| `:agent start <id>` | Start an agent |
| `:agent stop <id>` | Stop an agent |
| `:agent pause <id>` | Pause an agent |
| `:agent resume <id>` | Resume a paused agent |
| `:agent destroy <id>` | Destroy an agent |
| `:agent execute <id> <behavior> [args]` | Execute agent behavior |
| `:agent debug <id>` | Show debug info for an agent |

### Monitoring Commands

| Command | Description |
|---------|-------------|
| `:monitor stats` | Show execution statistics |
| `:monitor traces [limit]` | Show execution traces |
| `:monitor report` | Show detailed execution report |
| `:monitor clear` | Clear monitoring data |

### Memory Commands

| Command | Description |
|---------|-------------|
| `:memory inspect <agent-id>` | Inspect memory state for an agent |
| `:memory compact <agent-id>` | Compact memory storage for an agent |
| `:memory purge <agent-id>` | Purge all memory for an agent |

### Webhook Commands

| Command | Description |
|---------|-------------|
| `:webhook list` | List configured webhooks |
| `:webhook add` | Add a new webhook |
| `:webhook remove` | Remove a webhook |
| `:webhook test` | Test a webhook |
| `:webhook logs` | Show webhook logs |

### Recording Commands

| Command | Description |
|---------|-------------|
| `:record on <file>` | Start recording the session to a file |
| `:record off` | Stop recording the session |

### Session Commands

| Command | Description |
|---------|-------------|
| `:snapshot` | Create a session snapshot |
| `:clear` | Clear the session |
| `:help` or `:h` | Show help message |
| `:version` | Show version information |

## DSL Features

### Agent Definitions

```rust
metadata {
  version = "2.1.0"
  description = "Analyzes datasets with privacy protection"
}

agent data_analyzer(data: DataSet, options: AnalysisOptions) -> AnalysisResults {
  capabilities = ["data_read", "analysis"]

  policy privacy {
    allow: read(data) if true
    deny: write(any)
  }

  with memory = "ephemeral", sandbox = "tier1" {
    return analyze(data, options);
  }
}
```

Agent behavior lives in the agent's `with` block (and in `function` definitions) —
there is no separate `behavior` construct. Policy rules (`allow` / `deny` /
`require` / `audit`) gate what the agent may do. See the
[DSL Guide](dsl-guide.md) and [DSL Specification](dsl-specification.md) for the
full grammar.

### Built-in Functions

| Function | Description | Example |
|----------|-------------|---------|
| `print(...)` | Print values to output | `print("Hello", name)` |
| `len(value)` | Get length of string, list, or map | `len("hello")` → `5` |
| `upper(string)` | Convert string to uppercase | `upper("hello")` → `"HELLO"` |
| `lower(string)` | Convert string to lowercase | `lower("HELLO")` → `"hello"` |
| `format(template, ...)` | Format string with arguments | `format("Hello, {}!", name)` |

> **Planned built-in functions:** Advanced I/O functions such as `read_file()`, `read_csv()`, `write_results()`, `analyze()`, and `transform_data()` are not yet implemented. These are planned for a future release.

### Data Types

```rust
# Basic types
let name = "Alice"          # String
let age = 30               # Integer
let height = 5.8           # Number
let active = true          # Boolean
let empty = null           # Null

# Collections
let items = [1, 2, 3]      # List
let config = {             # Map
  "host": "localhost",
  "port": 8080
}

# Time and size units
let timeout = 30s          # Duration
let max_size = 100MB       # Size
```

## Architecture

### Components

```
symbi repl
├── repl-cli/          # CLI interface and JSON-RPC server
├── repl-core/         # Core REPL engine and evaluator  
├── repl-proto/        # JSON-RPC protocol definitions
└── repl-lsp/          # Language Server Protocol implementation
```

### Core Components

- **DslEvaluator**: Executes DSL programs with runtime integration
- **ReplEngine**: Coordinates evaluation and command handling
- **ExecutionMonitor**: Tracks execution statistics and traces
- **RuntimeBridge**: Integrates with Symbiont runtime for policy enforcement
- **SessionManager**: Handles snapshots and session state

### JSON-RPC Protocol

The REPL supports JSON-RPC 2.0 for programmatic access:

```json
// Evaluate DSL code
{
  "jsonrpc": "2.0",
  "method": "evaluate",
  "params": {"input": "let x = 42"},
  "id": 1
}

// Response
{
  "jsonrpc": "2.0",
  "result": {"value": "42", "type": "integer"},
  "id": 1
}
```

## Security & Policy Enforcement

### Capability Checking

The REPL enforces capability requirements defined in agent security blocks:

```rust
agent SecureAgent {
  name: "Secure Agent"
  security {
    capabilities: ["filesystem", "network"]
    sandbox: true
  }
}

behavior ReadFile {
  input { path: string }
  output { content: string }
  steps {
    # This will check if agent has "filesystem" capability
    require capability("filesystem")
    # NOTE: read_file() is a planned built-in function (not yet implemented).
    # This example illustrates how capability checking works.
    let content = read_file(path)
    return content
  }
}
```

### Policy Integration

The REPL integrates with the Symbiont policy engine to enforce access controls and audit requirements.

## Debugging & Monitoring

### Execution Traces

```
:monitor traces 10

Recent Execution Traces:
  14:32:15.123 - AgentCreated [Agent: abc-123] (2ms)
  14:32:15.125 - AgentStarted [Agent: abc-123] (1ms)  
  14:32:15.130 - BehaviorExecuted [Agent: abc-123] (5ms)
  14:32:15.135 - AgentPaused [Agent: abc-123]
```

### Statistics

```
:monitor stats

Execution Monitor Statistics:
  Total Executions: 42
  Successful: 38
  Failed: 4
  Success Rate: 90.5%
  Average Duration: 12.3ms
  Total Duration: 516ms
  Active Executions: 2
```

### Agent Debugging

```
:agent debug abc-123

Agent Debug Information:
  ID: abc-123-def-456
  Name: Data Analyzer
  Version: 2.1.0
  State: Running
  Created: 2024-01-15 14:30:00 UTC
  Description: Analyzes datasets with privacy protection
  Author: data-team@company.com
  Available Functions/Behaviors: 5
  Required Capabilities: 2
    - data_read
    - analysis
  Resource Configuration:
    Memory: 512MB
    CPU: 2
    Storage: 1GB
```

## IDE Integration

### Language Server Protocol

The REPL provides LSP support for IDE integration via the `repl-lsp` crate. The LSP server is started separately from the REPL itself:

```bash
# The LSP server is provided by the repl-lsp crate and launched
# by your editor's LSP client configuration (not via symbi repl flags).
```

> **Note:** The `--lsp` flag is not supported on `symbi repl`. LSP is implemented in the `repl-lsp` crate and should be configured through your editor's LSP settings.

### Supported Features

- Syntax highlighting
- Error diagnostics
- Text synchronization

**Planned features** (not yet implemented):
- Code completion
- Hover information
- Go to definition
- Symbol search

## Best Practices

### Development Workflow

1. **Start with Simple Expressions**: Test basic DSL constructs
2. **Define Agents Incrementally**: Start with minimal agent definitions
3. **Test Behaviors Separately**: Define and test behaviors before integration
4. **Use Monitoring**: Leverage execution monitoring for debugging
5. **Create Snapshots**: Save important session states

### Performance Tips

- Use `:monitor clear` periodically to reset monitoring data
- Limit trace history with `:monitor traces <limit>`
- Destroy unused agents to free resources
- Use snapshots for complex session states

### Security Considerations

- Always define appropriate capabilities for agents
- Test policy enforcement in development
- Use sandbox mode for untrusted code
- Monitor execution traces for security events

## Troubleshooting

### Common Issues

**Agent Creation Fails**
```
Error: Missing capability: filesystem
```
*Solution*: Add required capabilities to agent security block

**Execution Timeout**
```
Error: Maximum execution depth exceeded
```
*Solution*: Check for infinite recursion in behavior logic

**Policy Violation**
```
Error: Policy violation: data access denied
```
*Solution*: Verify agent has appropriate permissions

### Debug Commands

```rust
# Check agent state
:agent debug <agent-id>

# View execution traces
:monitor traces 50

# Check system statistics  
:monitor stats

# Create debug snapshot
:snapshot
```

## Examples

### Simple Agent

```rust
agent Calculator {
  name: "Basic Calculator"
  version: "1.0.0"
}

behavior Add {
  input { a: number, b: number }
  output { result: number }
  steps {
    return a + b
  }
}

# Test the behavior
let result = Add(5, 3)
print("5 + 3 =", result)
```

### Data Processing Agent

```rust
agent DataProcessor {
  name: "Data Processing Agent"
  version: "1.0.0"
  
  security {
    capabilities: ["data_read", "data_write"]
    sandbox: true
  }
  
  resources {
    memory: 256MB
    cpu: 1
  }
}

behavior ProcessCsv {
  input { file_path: string }
  output { summary: ProcessingSummary }

  steps {
    require capability("data_read")

    # NOTE: read_csv(), transform_data(), and write_results() are planned
    # built-in functions (not yet implemented). This example illustrates
    # the intended pattern for data processing behaviors.
    let data = read_csv(file_path)
    let processed = transform_data(data)

    require capability("data_write")
    write_results(processed)

    return {
      "rows_processed": len(data),
      "status": "completed"
    }
  }
}
```

## See Also

- [DSL Guide](dsl-guide.md) - Complete DSL language reference
- [Runtime Architecture](runtime-architecture.md) - System architecture overview
- [Security Model](security-model.md) - Security implementation details
- [API Reference](api-reference.md) - Complete API documentation