IPC Protocol & Lifecycle

This document explains the technical standard input/output IPC (Inter-Process Communication) protocol used by NERVI extensions.

📯 Framing and Transport

All IPC communications between NERVI and an extension subprocess use standard input (stdin) and standard output (stdout):

1. Newline Delimited: Every message is a single-line JSON string terminated by a newline character (\n).
2. Standard Error: Any output written by the extension to standard error (stderr) is captured by the Go client and appended to %AppData%\Roaming\nervi\logs\<extension-id>.log.
3. Threading: Stateful extensions must be thread-safe as requests may be sent concurrently.

🛠️ Tool Mode Request/Response

Request Object (Go -> Subprocess)

{
  "method": "call",
  "tool": "calculate_area",
  "arguments": {
    "width": 10,
    "height": 5
  },
  "id": "req-98765"
}

Response Object (Subprocess -> Go)

{
  "result": {
    "area": 50,
    "units": "sqm"
  },
  "error": "",
  "id": "req-98765"
}

📂 Menu Mode Protocol

Menu Selection Request (Go -> Subprocess)

{
  "method": "menu",
  "selection": "1",
  "arguments": ["arg1", "arg2"],
  "id": "req-112"
}

Menu Response Structure (Subprocess -> Go)

{
  "result": {
    "title": "Main Menu Options",
    "items": [
      {"id": "1", "label": "Add numbers"},
      {"id": "2", "label": "List historical results"},
      {"id": "3", "label": "Exit"}
    ],
    "text_content": "Please choose an action below:"
  },
  "error": "",
  "id": "req-112"
}

💾 State Persistence (Stores Data)

Stateful extensions can persist runtime configurations or histories across restarts:

1. StoresData: Set "stores_data": true in manifest.json.
2. State Directory: NERVI creates a state broker path in %AppData%\Roaming\nervi\state\<extension-id>.json.
3. State Sync: The extension broker synchronizes state changes dynamically, allowing real-time monitoring via the nervi app monitor command.