CLI <-> Backend Communication

This page details the communication mechanism between the JuliaOS frontends (CLI, Python Wrapper) and the Julia backend server.

Overview

Communication relies on a client-server model where frontends act as clients sending requests to the Julia backend server.

• Server: The Julia backend (julia/julia_server.jl) runs an HTTP server (using HTTP.jl) listening on a specific port (default: 8052). A WebSocket server on port 8053 is prepared but currently disabled in the code.

• Clients: The Node.js CLI (packages/cli/) and the Python Wrapper (packages/python-wrapper/) initiate connections to the HTTP server.

• Bridge Component: A dedicated component within the clients (e.g., @juliaos/julia-bridge in Node.js, or internal HTTP client in Python) handles formatting requests, sending them, and parsing responses.

• Protocol: Communication uses HTTP POST requests to the /api/command endpoint. Payloads are JSON objects containing a command string (e.g., "agents.create_agent") and a params or payload object/array containing arguments.

Request/Response Flow

1. Client Action: User interacts with the CLI or calls a Python API function.

2. Bridge Formatting: The client-side bridge constructs a JSON payload.

   {
     "command": "agents.create_agent",
     // Payload format might be array or object depending on handler
     "params": ["MyAgent", "Trading", {"risk": 0.5}] 
     // or "payload": { "name": "MyAgent", ... }
   }

3. HTTP Request: The bridge sends an HTTP POST request to http://<backend_host>:8052/api/command with the JSON payload.

4. Server Receives: The Julia HTTP server (julia_server.jl) receives the request at the /api/command route.

5. Command Parsing: The server parses the JSON body to extract the command string and params/payload.

6. Command Handling: The server's command handler (likely defined in julia_server.jl or a dedicated command module) looks up the function associated with the command string in a registry (like Bridge.command_handlers).

7. Backend Logic: The registered handler function (e.g., AgentSystem.handle_create_agent(...)) is called with the parameters from the payload.

8. Response Formatting: The handler function returns a result (e.g., data object or error).

9. HTTP Response: The Julia server sends an HTTP response (typically JSON) back to the client bridge, often wrapping the result.

   // Example success response format from Bridge.jl
   {
     "result": { "agent_id": "uuid-123-abc", ... }, // Actual data from handler
     "error": null,
     "id": "request-id"
   }
   // Example error response format
   {
     "result": null,
     "error": "Command execution failed: Agent name already exists",
     "id": "request-id"
   }

10. Bridge Parsing: The client-side bridge receives the HTTP response and parses the JSON, checking for errors.

11. Client Update: The result data or error is returned to the original caller (CLI displays message, Python function returns value or raises exception).

Communication Diagram

sequenceDiagram
    participant Client as CLI / Python Wrapper
    participant BridgeLib as Client Bridge Lib (JS/Py)
    participant JuliaServer as Julia Backend (HTTP Server @ :8052)
    participant CmdDispatcher as Command Dispatcher (Julia)
    participant HandlerFunc as Specific Handler Func (Julia)
    participant CoreModules as Core Julia Modules

    Client->>BridgeLib: User Action / API Call
    BridgeLib->>BridgeLib: Format JSON: {command, params/payload, id}
    BridgeLib->>JuliaServer: POST /api/command (JSON Payload)
    JuliaServer->>CmdDispatcher: Receive Request, Parse JSON
    CmdDispatcher->>CmdDispatcher: Lookup handler for command string
    CmdDispatcher->>HandlerFunc: Invoke handler(params)
    HandlerFunc->>CoreModules: Execute Logic (AgentSystem, etc.)
    CoreModules-->>HandlerFunc: Return data/result
    HandlerFunc-->>CmdDispatcher: Return result/error
    CmdDispatcher-->>JuliaServer: Format JSON Response: {result, error, id}
    JuliaServer-->>BridgeLib: HTTP Response (JSON Body)
    BridgeLib->>BridgeLib: Parse JSON Response, Check error field
    BridgeLib-->>Client: Return data or raise error
    Client->>Client: Process result / Display to user

Key Components

• /julia/julia_server.jl: Contains the HTTP server (HTTP.jl), routing for /api/command, request parsing, and command dispatch logic.

• /julia/src/Bridge.jl: Defines request/response structs, manages the command_handlers registry, provides utility functions (get_token_address, execute_trade, submit_signed_transaction), and handles the core run_command logic.

• Client Libraries (/packages/julia-bridge/ or Python internal): Responsible for making the HTTP POST calls and handling responses on the client side.