docs: add initial RVBox design and protocol contracts

2026-08-21 09:02:57 +00:00
commit 97c2d5cf45
10 changed files with 1138 additions and 0 deletions
@@ -0,0 +1,147 @@
+syntax = "proto3";
+
+package rvbox.v1;
+
+option go_package = "github.com/rvbox/rvbox/gen/go/rvbox/v1;rvboxv1";
+
+import "google/protobuf/timestamp.proto";
+import "rvbox/v1/common.proto";
+
+// One AgentEnvelope is carried in one binary WebSocket message.
+message AgentEnvelope {
+  // Empty only for ClientHello. All other envelopes are fenced to a session.
+  string session_id = 1;
+  uint64 session_generation = 2;
+  string message_id = 3;
+
+  oneof payload {
+    ClientHello client_hello = 10;
+    ServerWelcome server_welcome = 11;
+    CommandDispatch command_dispatch = 12;
+    CommandAccepted command_accepted = 13;
+    CommandEvent command_event = 14;
+    EventAck event_ack = 15;
+    StdinWrite stdin_write = 16;
+    CloseStdin close_stdin = 17;
+    SignalCommand signal_command = 18;
+    ScriptChunk script_chunk = 19;
+    ScriptCommit script_commit = 20;
+    ClientCapacity client_capacity = 21;
+    ReconcileRequest reconcile_request = 22;
+    ReconcileSnapshot reconcile_snapshot = 23;
+    AgentError error = 24;
+    ClientOutputTruncated client_output_truncated = 25;
+  }
+}
+
+message ClientHello {
+  // Configured hostname; opaque 1-128 ASCII characters.
+  string client_id = 1;
+  ProtocolRange supported_protocol = 2;
+  string daemon_version = 3;
+  Platform platform = 4;
+  string architecture = 5;
+  string daemon_cwd = 6;
+  repeated ShellType supported_shells = 7;
+  string reconnect_uuid = 8;
+  uint32 max_running_commands = 9;
+  uint32 max_queued_commands = 10;
+  google.protobuf.Timestamp sent_at = 11;
+}
+
+message ServerWelcome {
+  ProtocolVersion selected_protocol = 1;
+  // AgentEnvelope.session_id and .session_generation are canonical.
+  google.protobuf.Timestamp server_time = 2;
+}
+
+message CommandDispatch {
+  string issue_uuid = 1;
+  uint64 command_revision = 2;
+  uint64 target_session_generation = 3;
+  google.protobuf.Timestamp issue_time = 4;
+  ExecutionSpec spec = 5;
+}
+
+message CommandAccepted {
+  string issue_uuid = 1;
+  uint64 command_revision = 2;
+  bool accepted = 3;
+  ControlError rejection = 4;
+}
+
+// Cumulative durable acknowledgement of client CommandEvent values.
+message EventAck {
+  string issue_uuid = 1;
+  uint64 through_event_seq = 2;
+}
+
+message StdinWrite {
+  string issue_uuid = 1;
+  uint64 write_seq = 2;
+  bytes data = 3;
+  bool append_newline = 4;
+}
+
+message CloseStdin {
+  string issue_uuid = 1;
+  uint64 write_seq = 2;
+}
+
+message SignalCommand {
+  string issue_uuid = 1;
+  uint64 command_revision = 2;
+  SignalKind signal = 3;
+}
+
+message ScriptChunk {
+  string issue_uuid = 1;
+  uint64 offset = 2;
+  bytes data = 3;
+  bytes sha256 = 4;
+}
+
+message ScriptCommit {
+  string issue_uuid = 1;
+  uint64 size_bytes = 2;
+  bytes sha256 = 3;
+}
+
+message ClientCapacity {
+  uint32 running_commands = 1;
+  uint32 queued_commands = 2;
+  uint32 max_running_commands = 3;
+  uint32 max_queued_commands = 4;
+}
+
+message ReconcileRequest {
+  repeated ReconcileTarget targets = 1;
+}
+
+message ReconcileTarget {
+  string issue_uuid = 1;
+  uint64 last_server_event_seq = 2;
+  uint64 command_revision = 3;
+}
+
+// Sent only for requests in ReconcileRequest; server-confirmed terminal history
+// is intentionally not requested.
+message ReconcileSnapshot {
+  string issue_uuid = 1;
+  bool known_to_client = 2;
+  CommandLifecycle lifecycle = 3;
+  uint64 last_client_event_seq = 4;
+  uint64 command_revision = 5;
+}
+
+// Sent before retained replay data when an offline client had to rotate
+// unacknowledged output to remain within its hard spool limits.
+message ClientOutputTruncated {
+  string issue_uuid = 1;
+  OutputTruncation truncation = 2;
+}
+
+message AgentError {
+  ControlError error = 1;
+  bool close_session = 2;
+}