rvbox/protos/rvbox/v1/agent.proto

syntax = "proto3";

package rvbox.v1;

import "google/protobuf/timestamp.proto";
import "rvbox/v1/common.proto";

option go_package = "github.com/rvbox/rvbox/gen/go/rvbox/v1;rvboxv1";

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

  oneof payload {
    ClientHello client_hello = 3;
    ServerWelcome server_welcome = 4;
    CommandDispatch command_dispatch = 5;
    CommandAccepted command_accepted = 6;
    CommandEvent command_event = 7;
    EventAck event_ack = 8;
    StdinWrite stdin_write = 9;
    CloseStdin close_stdin = 10;
    SignalCommand signal_command = 11;
    ScriptChunk script_chunk = 12;
    ScriptCommit script_commit = 13;
    ClientCapacity client_capacity = 14;
    ReconcileRequest reconcile_request = 15;
    ReconcileSnapshot reconcile_snapshot = 16;
    AgentError error = 17;
    ReconcileResult reconcile_result = 18;
  }
}

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;
  // Omitted-CWD default on Unix; protected per-identity work root on Windows.
  string daemon_cwd = 6;
  repeated ShellType supported_shells = 7;
  // Generated once and persisted in the client state directory.
  string client_instance_id = 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;
  google.protobuf.Timestamp queue_expiry_time = 6;
  // Required immutable digest for client-side UUID/hash idempotency checks.
  bytes immutable_request_sha256 = 7;
}

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;
  bytes immutable_request_sha256 = 4;
}

message ReconcileSnapshot {
  // The complete set still retained by the client, including non-terminal and
  // terminal-but-unacknowledged commands.
  repeated ReconcileCommandState retained_commands = 1;
}

message ReconcileCommandState {
  string issue_uuid = 1;
  CommandLifecycle lifecycle = 2;
  uint64 last_client_event_seq = 3;
  uint64 command_revision = 4;
  // True only for a matching UUID/request hash in the compact tombstone ledger.
  bool tombstoned = 5;
  bytes immutable_request_sha256 = 6;
}

// Sent after the server durably compares a complete snapshot and before it
// dispatches new work on the session. Repetition is idempotent.
message ReconcileResult {
  repeated string terminate_local_issue_uuids = 1;
  repeated string discard_local_terminal_issue_uuids = 2;
}

message AgentError {
  ControlError error = 1;
  bool close_session = 2;
}