// Terminal Streaming Service - Main service definition.
//
// Architecture:
//   Browser (xterm.js) → WebSocket → Django → gRPC → Agent → PTY
//
// Flow:
//   1. Browser opens terminal → Django creates TerminalSession
//   2. Agent connects via gRPC with session_id
//   3. Bidirectional streaming established
//   4. Input: Browser → Django → Agent (stdin)
//   5. Output: Agent → Django → Browser (stdout/stderr)
//
// Version: 2.25.0
// Date: 2026-03-12
//
// Changelog:
// - v2.25.0: Added GetChallenge RPC and MFA authentication messages (AuthChallenge, AuthResponse)
// - v2.23.0: Added SkillList, SkillShow, SkillRun RPCs for remote skill management and execution
// - v2.22.0: Added RunAgentStream RPC for SDK streaming agent execution
// - v2.21.0: Added GetSessionByHostname RPC for SDK set_machine()
// - v2.19.0: Added BrowserNetwork* RPCs for network capture
// - v2.18.0: Added BrowserMouseMove, BrowserHover, BrowserScroll RPCs
// - v2.17.0: Added BrowserValidateSelectors, BrowserExtractData RPCs
// - v2.16.0: Added Browser Direct Control API (BrowserNavigate, BrowserClick, BrowserExtract, etc.)
// - v2.14.0: Added ListSessions RPC for SDK session discovery
// - v2.13.0: Added RunAgent RPC for SDK agent execution
// - v2.12.0: Added Extract RPC for SDK structured output extraction
// - v2.11.0: Added HLS streaming RPCs (HlsGetPlaylist, HlsGetSegment, HlsStopSession)
// - v2.3.0: Added FileSearch RPC
// - v2.2.0: Added FileCreateArchive RPC

syntax = "proto3";

package terminal;

option go_package = "terminal/proto";

import "agent_messages.proto";
import "control_messages.proto";
import "rpc_messages.proto";
import "file_rpc.proto";
import "file_operations.proto";

// ============================================================================
// SERVICE DEFINITION
// ============================================================================

service TerminalStreamingService {
  // PRIMARY: Bidirectional streaming for terminal I/O
  // Agent opens stream → Django sends input → Agent sends output
  rpc ConnectTerminal(stream AgentMessage) returns (stream ControlMessage);

  // MFA challenge nonce (v2.25.0)
  // Called BEFORE ConnectTerminal when workspace requires Ed25519 signing.
  // Returns a 32-byte nonce the agent must sign in RegisterRequest.session_signature.
  // Also indicates which auth methods the workspace requires.
  rpc GetChallenge(GetChallengeRequest) returns (GetChallengeResponse);

  // Session management RPCs
  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
  rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
  rpc GetSessionStatus(GetSessionStatusRequest) returns (GetSessionStatusResponse);
  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);  // v2.14.0
  rpc GetSessionByHostname(GetSessionByHostnameRequest) returns (GetSessionByHostnameResponse);  // v2.21.0

  // Terminal control RPCs (for external clients like Django management commands)
  rpc SendInput(SendInputRequest) returns (SendInputResponse);
  rpc SendResize(SendResizeRequest) returns (SendResizeResponse);
  rpc SendSignal(SendSignalRequest) returns (SendSignalResponse);

  // History & Output
  rpc GetHistory(GetHistoryRequest) returns (GetHistoryResponse);
  rpc GetOutput(GetOutputRequest) returns (GetOutputResponse);  // v2.20.0 - SDK execute() support

  // Health check
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);

  // Device token registration (for push notifications)
  rpc RegisterDeviceToken(RegisterDeviceTokenRequest) returns (RegisterDeviceTokenResponse);
  rpc UnregisterDeviceToken(UnregisterDeviceTokenRequest) returns (UnregisterDeviceTokenResponse);

  // Session lifecycle (push-wake flow)
  rpc EnterBackground(EnterBackgroundRequest) returns (EnterBackgroundResponse);
  rpc WakeFromBackground(WakeFromBackgroundRequest) returns (WakeFromBackgroundResponse);
  rpc QueueCommand(QueueCommandRequest) returns (QueueCommandResponse);

  // File operations (routed through streaming to agent)
  rpc FileListDirectory(FileListDirectoryRpcRequest) returns (FileListDirectoryRpcResponse);
  rpc FileRead(FileReadRpcRequest) returns (FileReadRpcResponse);
  rpc FileWrite(FileWriteRpcRequest) returns (FileWriteRpcResponse);
  rpc FileCreateDirectory(FileCreateDirectoryRpcRequest) returns (FileCreateDirectoryRpcResponse);
  rpc FileDelete(FileDeleteRpcRequest) returns (FileDeleteRpcResponse);
  rpc FileMove(FileMoveRpcRequest) returns (FileMoveRpcResponse);
  rpc FileCopy(FileCopyRpcRequest) returns (FileCopyRpcResponse);
  rpc FileGetInfo(FileGetInfoRpcRequest) returns (FileGetInfoRpcResponse);
  rpc FileCreateArchive(FileCreateArchiveRpcRequest) returns (FileCreateArchiveRpcResponse);
  rpc FileSearch(FileSearchRpcRequest) returns (FileSearchRpcResponse);

  // HLS streaming (v2.11.0) - for adaptive video streaming
  rpc HlsGetPlaylist(HlsGetPlaylistRpcRequest) returns (HlsGetPlaylistRpcResponse);
  rpc HlsGetSegment(HlsGetSegmentRpcRequest) returns (HlsGetSegmentRpcResponse);
  rpc HlsStopSession(HlsStopSessionRpcRequest) returns (HlsStopSessionRpcResponse);

  // Streaming relay (for cross-device file transfer via HTTP -> gRPC)
  rpc InitiateStreamingRelay(StreamingRelayRequest) returns (StreamingRelayResponse);
  rpc RelayChunk(StreamingRelayChunk) returns (StreamingRelayAck);
  rpc GetStreamingRelayStatus(StreamingRelayStatusRequest) returns (StreamingRelayStatus);
  rpc CancelStreamingRelay(StreamingRelayCancelRequest) returns (StreamingRelayCancelResponse);

  // Push notification (send desktop notification to agent)
  rpc SendPushNotification(SendPushNotificationRequest) returns (SendPushNotificationResponse);

  // Structured data extraction (v2.12.0) - for SDK programmatic access
  // Agent uses tools to gather data and returns JSON matching provided schema
  rpc Extract(ExtractRequest) returns (ExtractResponse);

  // Run AI agent (v2.13.0) - for SDK agent execution
  // SDK sends prompt, Django relays to connected agent, returns result
  rpc RunAgent(RunAgentRequest) returns (RunAgentResponse);

  // Run AI agent with streaming (v2.22.0) - for SDK streaming agent execution
  // SDK sends prompt, Django relays to agent with stream_events=true,
  // streams AgentStreamEvent back to SDK, ends with final result
  rpc RunAgentStream(RunAgentRequest) returns (stream RunAgentStreamResponse);

  // Cancel running agent (v2.15.0) - for SDK agent cancellation
  // SDK sends cancel request, Django relays to connected agent, returns confirmation
  rpc CancelAgent(CancelAgentRequest) returns (CancelAgentResponse);

  // ============================================================================
  // SKILLS (v2.23.0)
  // Remote skill management and execution - SDK can list, inspect, and run skills
  // ============================================================================

  // List installed skills on connected machine
  rpc SkillList(SkillListRequest) returns (SkillListResponse);

  // Get skill details (manifest, content, source path)
  rpc SkillShow(SkillShowRequest) returns (SkillShowResponse);

  // Execute a skill with a prompt
  rpc SkillRun(SkillRunRequest) returns (SkillRunResponse);

}

// ============================================================================
// MFA CHALLENGE MESSAGES (v2.25.0)
// ============================================================================

// Request a challenge nonce before opening ConnectTerminal stream.
// Used when workspace requires Ed25519 signed sessions.
// Also returns which auth methods the workspace requires so agent
// can prepare (prompt TOTP, load keypair) before opening the stream.
message GetChallengeRequest {
  string workspace_id = 1;    // Workspace the agent is connecting to
  string session_id   = 2;    // Session UUID the agent will use in ConnectTerminal
}

message GetChallengeResponse {
  bytes  nonce            = 1;   // 32-byte cryptographically random nonce
  int64  expires_at       = 2;   // Unix timestamp: nonce valid until (now + 120s)
  repeated string required_methods = 3;  // e.g. [], ["totp"], ["ed25519"], ["totp", "ed25519"]
}
