@2389research/coven-openclaw 0.1.0

package/proto/coven.proto

@@ -0,0 +1,641 @@
+// ABOUTME: Protocol buffer definitions for agent-server communication.
+// ABOUTME: Defines the bidirectional streaming protocol for coven control.
+
+syntax = "proto3";
+package coven;
+
+import "google/protobuf/empty.proto";
+
+// Agent connects to server, receives commands, sends results
+service CovenControl {
+  // Agent registration - bidirectional stream for lifecycle
+  rpc AgentStream(stream AgentMessage) returns (stream ServerMessage);
+}
+
+// Messages from agent to server
+message AgentMessage {
+  oneof payload {
+    RegisterAgent register = 1;
+    MessageResponse response = 2;
+    Heartbeat heartbeat = 3;
+    InjectionAck injection_ack = 4;  // Acknowledge context injection
+    ExecutePackTool execute_pack_tool = 5;  // Request pack tool execution
+  }
+}
+
+// Git repository state (optional - agent may not be in a git repo)
+message GitInfo {
+  string branch = 1;
+  string commit = 2;
+  bool dirty = 3;
+  string remote = 4;
+  int32 ahead = 5;
+  int32 behind = 6;
+}
+
+// Environment metadata sent during registration
+message AgentMetadata {
+  string working_directory = 1;
+  GitInfo git = 2;
+  string hostname = 3;
+  string os = 4;
+  repeated string workspaces = 5;  // Workspace tags for filtering
+  string backend = 6;              // Backend type: "mux", "cli", "acp", "direct"
+}
+
+// Agent registration
+message RegisterAgent {
+  string agent_id = 1;           // Unique agent identifier
+  string name = 2;               // Human-readable name
+  repeated string capabilities = 3;  // What this agent can do
+  AgentMetadata metadata = 4;    // Environment context
+  repeated string protocol_features = 5;  // Supported features: "token_usage", "tool_states", "injection", "cancellation"
+}
+
+// Response to a message request
+message MessageResponse {
+  string request_id = 1;         // Correlates with SendMessage
+  oneof event {
+    string thinking = 2;
+    string text = 3;
+    ToolUse tool_use = 4;
+    ToolResult tool_result = 5;
+    Done done = 6;
+    string error = 7;
+    FileData file = 8;
+    ToolApprovalRequest tool_approval_request = 9;
+    SessionInit session_init = 10;
+    SessionOrphaned session_orphaned = 11;
+    TokenUsage usage = 12;           // Token consumption update
+    ToolStateUpdate tool_state = 13; // Tool lifecycle update
+    Cancelled cancelled = 14;        // Request was cancelled
+  }
+}
+
+// Backend session initialized (session_id assigned/confirmed)
+message SessionInit {
+  string session_id = 1;
+}
+
+// Backend session was orphaned (expired, lost, needs retry)
+message SessionOrphaned {
+  string reason = 1;
+}
+
+// Token usage statistics from the LLM provider
+message TokenUsage {
+  int32 input_tokens = 1;         // Tokens in the prompt
+  int32 output_tokens = 2;        // Tokens generated
+  int32 cache_read_tokens = 3;    // Tokens read from cache (Anthropic)
+  int32 cache_write_tokens = 4;   // Tokens written to cache (Anthropic)
+  int32 thinking_tokens = 5;      // Extended thinking tokens (Claude)
+}
+
+// Tool execution state
+enum ToolState {
+  TOOL_STATE_UNSPECIFIED = 0;
+  TOOL_STATE_PENDING = 1;           // Tool identified, not yet started
+  TOOL_STATE_AWAITING_APPROVAL = 2; // Waiting for human approval
+  TOOL_STATE_RUNNING = 3;           // Actively executing
+  TOOL_STATE_COMPLETED = 4;         // Finished successfully
+  TOOL_STATE_FAILED = 5;            // Execution error
+  TOOL_STATE_DENIED = 6;            // Approval denied
+  TOOL_STATE_TIMEOUT = 7;           // Execution timed out
+  TOOL_STATE_CANCELLED = 8;         // Cancelled by user/system
+}
+
+// Tool state transition notification
+message ToolStateUpdate {
+  string id = 1;                    // Tool invocation ID (matches ToolUse.id)
+  ToolState state = 2;              // New state
+  optional string detail = 3;       // Optional detail (error message, etc.)
+}
+
+// Cancellation acknowledgment (agent → server)
+message Cancelled {
+  string reason = 1;                // Echo back the reason
+}
+
+// Priority for context injection
+enum InjectionPriority {
+  INJECTION_PRIORITY_UNSPECIFIED = 0;
+  INJECTION_PRIORITY_IMMEDIATE = 1;   // Process before current turn completes
+  INJECTION_PRIORITY_NORMAL = 2;      // Standard priority
+  INJECTION_PRIORITY_DEFERRED = 3;    // Process after current work
+}
+
+// Context injection request (server → agent)
+message InjectContext {
+  string injection_id = 1;            // Unique ID for acknowledgment
+  string content = 2;                 // Content to inject
+  InjectionPriority priority = 3;     // When to process
+  optional string source = 4;         // Origin (e.g., "pack:elevenlabs", "system")
+}
+
+// Context injection acknowledgment (agent → server)
+message InjectionAck {
+  string injection_id = 1;            // Matches InjectContext.injection_id
+  bool accepted = 2;                  // Whether agent accepted the injection
+  optional string reason = 3;         // Why rejected (if not accepted)
+}
+
+// Request cancellation (server → agent)
+message CancelRequest {
+  string request_id = 1;              // Request to cancel
+  optional string reason = 2;         // Why cancelled (e.g., "user_requested")
+}
+
+// Request for tool approval before execution (agent → server)
+message ToolApprovalRequest {
+  string id = 1;           // Correlates with ToolUse.id
+  string name = 2;         // Tool name
+  string input_json = 3;   // Tool input for display
+}
+
+message ToolUse {
+  string id = 1;
+  string name = 2;
+  string input_json = 3;
+}
+
+message ToolResult {
+  string id = 1;
+  string output = 2;
+  bool is_error = 3;
+}
+
+message Done {
+  string full_response = 1;
+}
+
+message FileData {
+  string filename = 1;
+  string mime_type = 2;
+  bytes data = 3;
+}
+
+message Heartbeat {
+  int64 timestamp_ms = 1;
+}
+
+// Agent requests pack tool execution (agent → server)
+message ExecutePackTool {
+  string request_id = 1;        // Unique ID for correlation
+  string tool_name = 2;         // Name of the pack tool to execute
+  string input_json = 3;        // Tool input as JSON
+}
+
+// Server returns pack tool execution result (server → agent)
+message PackToolResult {
+  string request_id = 1;        // Correlates with ExecutePackTool.request_id
+  oneof result {
+    string output_json = 2;     // Success: tool output as JSON
+    string error = 3;           // Failure: error message
+  }
+}
+
+// Messages from server to agent
+message ServerMessage {
+  oneof payload {
+    Welcome welcome = 1;
+    SendMessage send_message = 2;
+    Shutdown shutdown = 3;
+    ToolApprovalResponse tool_approval = 4;
+    RegistrationError registration_error = 5;
+    InjectContext inject_context = 6;   // Push context to agent mid-turn
+    CancelRequest cancel_request = 7;   // Cancel in-flight request
+    PackToolResult pack_tool_result = 8; // Result of pack tool execution
+  }
+}
+
+// Server rejects registration (e.g., agent_id already taken)
+message RegistrationError {
+  string reason = 1;              // Human-readable error message
+  string suggested_id = 2;        // Optional: server-suggested alternative ID
+}
+
+// Response to tool approval request (server → agent)
+message ToolApprovalResponse {
+  string id = 1;           // Correlates with ToolApprovalRequest.id
+  bool approved = 2;       // True = execute, False = skip
+  bool approve_all = 3;    // If true, auto-approve remaining tools this request
+}
+
+// Server acknowledges registration
+message Welcome {
+  string server_id = 1;
+  string agent_id = 2;     // Confirmed agent ID (instance name)
+  string instance_id = 3;  // Short code for binding commands
+  string principal_id = 4; // Principal UUID for reference
+  repeated ToolDefinition available_tools = 5; // Pack tools available to this agent
+  string mcp_token = 6;    // Token for MCP endpoint authentication (capability-scoped)
+  string mcp_endpoint = 7; // Base MCP endpoint URL (e.g., "http://gateway:8080/mcp")
+  map<string, string> secrets = 8; // Resolved env vars for this agent (global + overrides)
+}
+
+// Server tells agent to process a message
+message SendMessage {
+  string request_id = 1;         // Unique request ID for correlation
+  string thread_id = 2;          // Conversation thread
+  string sender = 3;             // Who sent the message
+  string content = 4;            // Message content
+  repeated FileAttachment attachments = 5;
+}
+
+message FileAttachment {
+  string filename = 1;
+  string mime_type = 2;
+  bytes data = 3;
+}
+
+// Server tells agent to shut down
+message Shutdown {
+  string reason = 1;
+}
+
+// AdminService provides administrative operations for managing the gateway.
+// All methods require admin or owner role (enforced by RequireAdmin interceptor).
+service AdminService {
+  rpc ListBindings(ListBindingsRequest) returns (ListBindingsResponse);
+  rpc CreateBinding(CreateBindingRequest) returns (Binding);
+  rpc UpdateBinding(UpdateBindingRequest) returns (Binding);
+  rpc DeleteBinding(DeleteBindingRequest) returns (DeleteBindingResponse);
+
+  // Token management
+  rpc CreateToken(CreateTokenRequest) returns (CreateTokenResponse);
+
+  // Principal management
+  rpc ListPrincipals(ListPrincipalsRequest) returns (ListPrincipalsResponse);
+  rpc CreatePrincipal(CreatePrincipalRequest) returns (Principal);
+  rpc DeletePrincipal(DeletePrincipalRequest) returns (DeletePrincipalResponse);
+}
+
+// Binding represents a channel-to-agent mapping for message routing
+message Binding {
+  string id = 1;
+  string frontend = 2;
+  string channel_id = 3;
+  string agent_id = 4;
+  string created_at = 5;  // ISO-8601
+  optional string created_by = 6;
+}
+
+message ListBindingsRequest {
+  optional string frontend = 1;
+  optional string agent_id = 2;
+}
+
+message ListBindingsResponse {
+  repeated Binding bindings = 1;
+}
+
+message CreateBindingRequest {
+  string frontend = 1;
+  string channel_id = 2;
+  string agent_id = 3;
+}
+
+message UpdateBindingRequest {
+  string id = 1;
+  string agent_id = 2;
+}
+
+message DeleteBindingRequest {
+  string id = 1;
+}
+
+message DeleteBindingResponse {
+  // Empty response indicates success
+}
+
+// Token management messages
+message CreateTokenRequest {
+  string principal_id = 1;      // Principal to create token for
+  int64 ttl_seconds = 2;        // Token lifetime in seconds (default: 30 days)
+}
+
+message CreateTokenResponse {
+  string token = 1;             // The generated JWT token
+  string expires_at = 2;        // ISO-8601 expiration timestamp
+}
+
+// Principal management messages
+message Principal {
+  string id = 1;
+  string type = 2;              // "client", "agent", "pack"
+  string display_name = 3;
+  string status = 4;            // "pending", "approved", "online", "offline", "revoked"
+  optional string pubkey_fp = 5; // SSH public key fingerprint (for agents)
+  string created_at = 6;        // ISO-8601
+  repeated string roles = 7;
+}
+
+message ListPrincipalsRequest {
+  optional string type = 1;     // Filter by type
+  optional string status = 2;   // Filter by status
+}
+
+message ListPrincipalsResponse {
+  repeated Principal principals = 1;
+}
+
+message CreatePrincipalRequest {
+  string type = 1;              // "client" or "agent"
+  string display_name = 2;
+  optional string pubkey = 3;   // Full SSH public key (for agents)
+  optional string pubkey_fp = 4; // Or just the fingerprint
+  repeated string roles = 5;    // Roles to assign (e.g., "member")
+}
+
+message DeletePrincipalRequest {
+  string id = 1;
+}
+
+message DeletePrincipalResponse {
+  // Empty response indicates success
+}
+
+// ClientService provides client-facing operations for interacting with agents.
+// Requires authenticated principal (member role or higher).
+service ClientService {
+  rpc GetEvents(GetEventsRequest) returns (GetEventsResponse);
+  rpc GetMe(google.protobuf.Empty) returns (MeResponse);
+  rpc SendMessage(ClientSendMessageRequest) returns (ClientSendMessageResponse);
+
+  // Real-time streaming of events for a conversation
+  rpc StreamEvents(StreamEventsRequest) returns (stream ClientStreamEvent);
+
+  // List available agents for this principal
+  rpc ListAgents(ListAgentsRequest) returns (ListAgentsResponse);
+
+  // Register an agent (members can self-register agents)
+  rpc RegisterAgent(RegisterAgentRequest) returns (RegisterAgentResponse);
+
+  // Register a client (members can self-register clients like TUI)
+  rpc RegisterClient(RegisterClientRequest) returns (RegisterClientResponse);
+
+  // Respond to a tool approval request
+  rpc ApproveTool(ApproveToolRequest) returns (ApproveToolResponse);
+
+  // Respond to a user question (from ask_user tool)
+  rpc AnswerQuestion(AnswerQuestionRequest) returns (AnswerQuestionResponse);
+}
+
+// Request to answer a user question
+message AnswerQuestionRequest {
+  string agent_id = 1;              // Which agent asked the question
+  string question_id = 2;           // Correlates with UserQuestionRequest.question_id
+  repeated string selected = 3;     // Selected option label(s)
+  optional string custom_text = 4;  // If user typed a custom "Other" response
+}
+
+// Response to answering a question
+message AnswerQuestionResponse {
+  bool success = 1;
+  optional string error = 2;
+}
+
+// Request to approve or deny a tool execution
+message ApproveToolRequest {
+  string agent_id = 1;        // Which agent's tool to approve
+  string tool_id = 2;         // Correlates with ClientToolApprovalRequest.tool_id
+  bool approved = 3;          // True = execute, False = skip
+  bool approve_all = 4;       // If true, auto-approve remaining tools this request
+}
+
+// Response to tool approval
+message ApproveToolResponse {
+  bool success = 1;           // Whether the approval was processed
+  optional string error = 2;  // Error message if not successful
+}
+
+// Request to stream events for a conversation
+message StreamEventsRequest {
+  string conversation_key = 1;        // Which conversation to stream
+  optional string since_event_id = 2; // Resume from this event ID (for reconnection)
+}
+
+// Streaming event sent to clients - wraps all possible event types
+message ClientStreamEvent {
+  string conversation_key = 1;
+  string timestamp = 2;               // ISO-8601
+
+  oneof payload {
+    // Text content events
+    TextChunk text = 3;
+    ThinkingChunk thinking = 4;
+
+    // Tool lifecycle events
+    ToolUse tool_use = 5;
+    ToolResult tool_result = 6;
+    ToolStateUpdate tool_state = 7;
+
+    // Session events
+    TokenUsage usage = 8;
+    StreamDone done = 9;
+    StreamError error = 10;
+
+    // Full message (for history replay)
+    Event event = 11;
+
+    // Tool approval request (needs human decision)
+    ClientToolApprovalRequest tool_approval = 12;
+
+    // User question request (agent asking user a question via ask_user tool)
+    UserQuestionRequest user_question = 13;
+  }
+}
+
+// User question request sent to clients (from ask_user builtin tool)
+message UserQuestionRequest {
+  string agent_id = 1;              // Which agent is asking
+  string question_id = 2;           // Unique ID for correlation
+  string question = 3;              // The question text
+  repeated QuestionOption options = 4;  // Multiple choice options
+  bool multi_select = 5;            // Can select multiple answers
+  optional string header = 6;       // Short label/category for the question
+  int32 timeout_seconds = 7;        // How long client has to respond
+}
+
+// A single option in a user question
+message QuestionOption {
+  string label = 1;                 // Display text (also used as the value)
+  optional string description = 2;  // Optional explanation
+}
+
+// Tool approval request sent to clients (wraps ToolApprovalRequest with agent context)
+message ClientToolApprovalRequest {
+  string agent_id = 1;        // Which agent is requesting approval
+  string request_id = 2;      // Correlates with the message request
+  string tool_id = 3;         // Correlates with ToolUse.id
+  string tool_name = 4;       // Tool name for display
+  string input_json = 5;      // Tool input for display
+}
+
+// Incremental text chunk
+message TextChunk {
+  string content = 1;
+}
+
+// Incremental thinking chunk
+message ThinkingChunk {
+  string content = 1;
+}
+
+// Stream completed successfully
+message StreamDone {
+  optional string full_response = 1;  // Complete concatenated response
+}
+
+// Stream error
+message StreamError {
+  string message = 1;
+  bool recoverable = 2;               // Can client retry?
+}
+
+// Agent info for client listing
+message AgentInfo {
+  string id = 1;
+  string name = 2;
+  string backend = 3;                 // "mux", "cli", "acp", "direct"
+  string working_dir = 4;
+  bool connected = 5;
+  optional AgentMetadata metadata = 6;
+}
+
+message ListAgentsRequest {
+  optional string workspace = 1;      // Filter by workspace tag
+}
+
+message ListAgentsResponse {
+  repeated AgentInfo agents = 1;
+}
+
+// RegisterAgentRequest allows a linked device to register an agent
+message RegisterAgentRequest {
+  string display_name = 1;        // Name for the agent
+  string fingerprint = 2;         // SSH key fingerprint (SHA256 hex, 64 chars)
+}
+
+// RegisterAgentResponse returns the created principal info
+message RegisterAgentResponse {
+  string principal_id = 1;
+  string status = 2;              // "approved"
+}
+
+// RegisterClientRequest allows a linked device to register a client (TUI, CLI)
+message RegisterClientRequest {
+  string display_name = 1;        // Name for the client
+  string fingerprint = 2;         // SSH key fingerprint (SHA256 hex, 64 chars)
+}
+
+// RegisterClientResponse returns the created principal info
+message RegisterClientResponse {
+  string principal_id = 1;
+  string status = 2;              // "approved"
+}
+
+// ClientSendMessageRequest is the request for direct client message sending.
+// The idempotency_key is required and must be unique per message to prevent duplicates.
+message ClientSendMessageRequest {
+  string conversation_key = 1;
+  string content = 2;
+  repeated FileAttachment attachments = 3;
+  string idempotency_key = 4;  // required, 1-100 chars
+}
+
+// ClientSendMessageResponse is the response for direct client message sending.
+message ClientSendMessageResponse {
+  string status = 1;  // "accepted" or "duplicate"
+  string message_id = 2;  // assigned message ID (empty for duplicates)
+}
+
+// MeResponse contains the authenticated principal's identity information
+message MeResponse {
+  string principal_id = 1;
+  string principal_type = 2;
+  string display_name = 3;
+  string status = 4;
+  repeated string roles = 5;
+  optional string member_id = 6;
+  optional string member_display_name = 7;
+}
+
+// Event represents a ledger event in conversation history
+message Event {
+  string id = 1;
+  string conversation_key = 2;
+  string direction = 3;           // "inbound_to_agent" or "outbound_from_agent"
+  string author = 4;
+  string timestamp = 5;           // ISO-8601
+  string type = 6;                // "message", "tool_call", "tool_result", "system", "error"
+  optional string text = 7;
+  optional string raw_transport = 8;
+  optional string raw_payload_ref = 9;
+  optional string actor_principal_id = 10;
+  optional string actor_member_id = 11;
+}
+
+message GetEventsRequest {
+  string conversation_key = 1;
+  optional string since = 2;      // ISO-8601
+  optional string until = 3;      // ISO-8601
+  optional int32 limit = 4;       // 1-500
+  optional string cursor = 5;
+}
+
+message GetEventsResponse {
+  repeated Event events = 1;
+  optional string next_cursor = 2;
+  bool has_more = 3;
+}
+
+// Tool definitions for packs
+message ToolDefinition {
+  string name = 1;
+  string description = 2;
+  string input_schema_json = 3;  // MCP-compatible JSON Schema
+  repeated string required_capabilities = 4;
+  int32 timeout_seconds = 5;  // optional, default 30
+}
+
+message PackManifest {
+  string pack_id = 1;
+  string version = 2;
+  repeated ToolDefinition tools = 3;
+}
+
+// Tool execution messages
+message ExecuteToolRequest {
+  string tool_name = 1;
+  string input_json = 2;
+  string request_id = 3;
+}
+
+message ExecuteToolResponse {
+  string request_id = 1;
+  oneof result {
+    string output_json = 2;
+    string error = 3;
+  }
+}
+
+// Pack registration acknowledgment
+message PackWelcome {
+  string pack_id = 1;
+  repeated string rejected_tools = 2;  // Tools that collided with existing names
+}
+
+// Available tools list for agents
+message AvailableTools {
+  repeated ToolDefinition tools = 1;
+}
+
+// PackService allows tool packs to connect and provide tools to agents
+service PackService {
+  // Pack registers with manifest, receives tool execution requests
+  rpc Register(PackManifest) returns (stream ExecuteToolRequest);
+
+  // Pack sends tool execution results back
+  rpc ToolResult(ExecuteToolResponse) returns (google.protobuf.Empty);
+}