Skip to main content

ValorIDE Inter-Instance Communication Protocol

Purpose​

This protocol defines a simple ACK/NACK communication mechanism between multiple ValorIDE instances running in the same VSCode environment. The goal is to ensure reliable message exchange and prioritize user success.

Communication Channel​

  • Communication occurs via the console (standard input/output).
  • Messages are sent as plain text lines.
  • Each message must be acknowledged by the receiving instance.

Message Format​

  • Messages are JSON strings with the following structure:
{
  "id": "unique-message-id",
  "type": "REQUEST" | "ACK" | "NACK",
  "payload": { ... }
}
  • id: A unique identifier for the message (e.g., UUID).
  • type: The message type.
    • REQUEST: A request message.
    • ACK: Acknowledgment of successful receipt.
    • NACK: Negative acknowledgment indicating failure or error.
  • payload: An object containing message-specific data.

Protocol Flow​

  1. Sender sends a REQUEST message with a unique id.
  2. Receiver processes the message and responds with either:
    • ACK message with the same id if successful.
    • NACK message with the same id if an error occurred.
  3. Sender waits for the response before sending the next message.

Implementation Notes​

  • Both instances must listen to console input and parse incoming messages.
  • Messages must be logged for audit and debugging.
  • Timeouts and retries can be implemented to handle lost messages.
  • The protocol is designed to be simple and extensible.

User Success Priority​

  • All communication errors must be reported clearly.
  • Retries should be attempted automatically.
  • The protocol should never block the user interface.
  • Logging should be accessible to the user for troubleshooting.

Example Message Exchange​

Sender:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "REQUEST",
  "payload": { "command": "build" }
}

Receiver:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "ACK",
  "payload": { "status": "success" }
}

Or on error:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "NACK",
  "payload": { "error": "Build failed" }
}

Next Steps​

  • Implement console listeners in ValorIDE instances.
  • Automate message sending and response handling.
  • Integrate logging and error reporting.

This protocol is designed to be minimal and effective to ensure smooth inter-instance communication and maximize user success.

Simulated Planning Conversation​

Roles:

  • Instance A: Initiator
  • Instance B: Responder

Conversation: Instance A (Initiator):

{"id":"plan-001","type":"REQUEST","payload":{"task":"Plan next development phase"}}

Instance B (Responder):

{"id":"plan-001","type":"ACK","payload":{"message":"Acknowledged. Proposing roles and tasks."}}

Instance A (Initiator):

{"id":"plan-002","type":"REQUEST","payload":{"roles":["Console Listener Implementation", "Message Handler Implementation", "Logger Integration"]}}

Instance B (Responder):

{"id":"plan-002","type":"ACK","payload":{"message":"Roles Acknowledged."}}

Instance A (Initiator):

{"id":"feat-001","type":"REQUEST","payload":{"task":"Plan new feature: Command History Panel"}}

Instance B (Responder):

{"id":"feat-001","type":"ACK","payload":{"message":"Acknowledged. Let's define the scope."}}

Instance A (Initiator):

{"id":"feat-002","type":"REQUEST","payload":{"scope":["Persist commands", "Display in panel", "Filter/Search"]}}

Instance B (Responder):

{"id":"feat-002","type":"ACK","payload":{"message":"Scope Acknowledged."}}