Symbiont REPL Guide¶

Branch execution status: Async builtins retain the invoking caller's identity. The bridge freezes its project root, and default reason()/tool_call() calls require protected run journals and return public audit references. Direct inference calls also require journals; :audit lists their public references. Function and behavior declarations persist across inputs, and running behaviors keep a snapshot of their helpers. The legacy REPL syntax does not implement canonical per-agent sandbox selection. Explicit unsupported tier, sandbox, resource and execution-policy requirements now fail registration. See DSL invocation context and the branch guide for current coverage.

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 (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¶

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

Enter each declaration on one line:

agent Greeter {}
function greet(value: string) { return upper(value) }
behavior Welcome { steps { return greet(args) } }
:agents
:agent start <id>
:agent execute <id> Welcome hello

Replace <id> with the UUID printed for Greeter. The final command returns HELLO. Declaration and startup do not execute the behavior. Optional command arguments arrive as one string named args. Definitions persist; local variables and arguments do not carry into the next invocation. A failed module registration does not replace earlier definitions. Runtime errors remain visible and the client can accept the next command. print() diagnostics go to stderr independently of the structured response.

The canonical agent name(...) { with ... } language used by symbi run is a separate parsing path. Legacy REPL security tiers and sandbox modes are not its execution settings. Registration refuses explicit legacy tier/sandbox modes, populated resources and execution policies, before publishing any definitions. Duplicate constraint blocks and capability lists also fail parsing. Capability-only declarations keep their existing checks. Tool effects use the project boundary and governed dispatcher; without a configured permitting gate, tool requests are denied. Direct LLM calls, composition and pattern calls require a signed journal for each provider call. Their existing result types remain unchanged; use :audit for public references. Communication requires a configured gate and a registered recipient. send_to acknowledges durable startup, while its terminal journal records later completion. race returns the first success and cancels outstanding calls. These controls do not establish canonical source selection or aggregate inference budgets.

To reproduce the RPC and terminal smoke tests after a workspace build:

python3 scripts/test-repl-session.py --binary target/debug/repl-cli --report /tmp/repl-session.json

REPL Commands¶

Agent Management¶

Monitoring Commands¶

Memory Commands¶

Webhook Commands¶

Recording Commands¶

Session Commands¶

DSL Features¶

Agent Definitions¶

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 and DSL Specification for the full grammar.

Built-in Functions¶

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¶

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

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

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

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:

# 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

Execution Timeout

Error: Maximum execution depth exceeded

Policy Violation

Error: Policy violation: data access denied

Debug Commands¶

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

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¶

agent DataProcessor {
  name: "Data Processing Agent"
  version: "1.0.0"

  security {
    capabilities: ["data_read", "data_write"]
  }

}

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 - Complete DSL language reference
• Runtime Architecture - System architecture overview
• Security Model - Security implementation details
• API Reference - Complete API documentation