agent-os-kernel 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

modules/iatp/proto/iatp.proto

@@ -0,0 +1,552 @@
+// IATP - Inter-Agent Trust Protocol
+// Protocol Buffer definitions for cross-language interoperability
+//
+// These definitions enable IATP to work across different programming languages
+// (Python, Node.js, Go, Rust, Java) over gRPC.
+//
+// Build commands:
+//   Python:  python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. iatp.proto
+//   Node.js: grpc_tools_node_protoc --js_out=. --grpc_out=. iatp.proto
+//   Go:      protoc --go_out=. --go-grpc_out=. iatp.proto
+//
+// Version: 1.0.0
+
+syntax = "proto3";
+
+package iatp.v1;
+
+option go_package = "github.com/imran-siddique/agent-os/iatp/v1;iatpv1";
+option java_package = "dev.agentos.iatp.v1";
+option java_multiple_files = true;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/struct.proto";
+
+// ============================================================================
+// Enumerations
+// ============================================================================
+
+// Trust levels for agents
+enum TrustLevel {
+  TRUST_LEVEL_UNSPECIFIED = 0;
+  TRUST_LEVEL_VERIFIED_PARTNER = 1;  // Well-known, vetted partner
+  TRUST_LEVEL_TRUSTED = 2;           // Established trust relationship
+  TRUST_LEVEL_STANDARD = 3;          // No prior relationship (default)
+  TRUST_LEVEL_UNKNOWN = 4;           // Minimal information available
+  TRUST_LEVEL_UNTRUSTED = 5;         // Known issues or red flags
+}
+
+// Reversibility support levels for transactions
+enum ReversibilityLevel {
+  REVERSIBILITY_LEVEL_UNSPECIFIED = 0;
+  REVERSIBILITY_LEVEL_FULL = 1;     // Full rollback support
+  REVERSIBILITY_LEVEL_PARTIAL = 2;  // Limited rollback (e.g., with fees)
+  REVERSIBILITY_LEVEL_NONE = 3;     // No rollback support
+}
+
+// Data retention policies
+enum RetentionPolicy {
+  RETENTION_POLICY_UNSPECIFIED = 0;
+  RETENTION_POLICY_EPHEMERAL = 1;   // Data deleted after session
+  RETENTION_POLICY_TEMPORARY = 2;   // Data stored temporarily (e.g., 30 days)
+  RETENTION_POLICY_PERMANENT = 3;   // Data stored indefinitely
+}
+
+// Severity levels for events
+enum Severity {
+  SEVERITY_UNSPECIFIED = 0;
+  SEVERITY_LOW = 1;
+  SEVERITY_MEDIUM = 2;
+  SEVERITY_HIGH = 3;
+  SEVERITY_CRITICAL = 4;
+}
+
+// ============================================================================
+// Core Messages
+// ============================================================================
+
+// Privacy contract specifying data handling policies
+message PrivacyContract {
+  // How long the agent stores data
+  RetentionPolicy retention = 1;
+  
+  // Geographic location of data storage (e.g., "us-west", "eu-central")
+  string storage_location = 2;
+  
+  // Whether humans may review the data
+  bool human_review = 3;
+  
+  // Whether data is encrypted at rest
+  bool encryption_at_rest = 4;
+  
+  // Whether data is encrypted in transit
+  bool encryption_in_transit = 5;
+}
+
+// Capabilities advertised by an agent
+message AgentCapabilities {
+  // Whether duplicate requests are handled safely
+  bool idempotency = 1;
+  
+  // Level of transaction reversibility support
+  ReversibilityLevel reversibility = 2;
+  
+  // Time window for undo operations
+  google.protobuf.Duration undo_window = 3;
+  
+  // Promised response latency
+  google.protobuf.Duration sla_latency = 4;
+  
+  // Maximum requests per minute
+  int32 rate_limit = 5;
+  
+  // Supported protocol versions
+  repeated string protocol_versions = 6;
+  
+  // List of supported actions/operations
+  repeated string supported_actions = 7;
+}
+
+// The capability manifest exchanged during handshake
+message CapabilityManifest {
+  // Unique identifier for the agent
+  string agent_id = 1;
+  
+  // Version of the agent
+  string agent_version = 2;
+  
+  // Trust level of the agent
+  TrustLevel trust_level = 3;
+  
+  // Capabilities supported by the agent
+  AgentCapabilities capabilities = 4;
+  
+  // Privacy policies of the agent
+  PrivacyContract privacy_contract = 5;
+  
+  // RBAC scopes defining agent permissions
+  repeated string scopes = 6;
+  
+  // Agent's public key for verification (base64 encoded)
+  string public_key = 7;
+  
+  // Additional metadata
+  google.protobuf.Struct metadata = 8;
+}
+
+// Attestation record for agent codebase verification
+message AttestationRecord {
+  // Unique identifier for the agent
+  string agent_id = 1;
+  
+  // SHA-256 hash of the agent's codebase
+  string codebase_hash = 2;
+  
+  // SHA-256 hash of the agent's configuration
+  string config_hash = 3;
+  
+  // Digital signature from Control Plane (base64 encoded)
+  string signature = 4;
+  
+  // Identifier for the public key used to verify signature
+  string signing_key_id = 5;
+  
+  // When attestation was created
+  google.protobuf.Timestamp timestamp = 6;
+  
+  // When attestation expires
+  google.protobuf.Timestamp expires_at = 7;
+}
+
+// Distributed tracing context
+message TracingContext {
+  // Unique trace ID for the request
+  string trace_id = 1;
+  
+  // Parent trace ID if this is part of a chain
+  string parent_trace_id = 2;
+  
+  // Span ID within the trace
+  string span_id = 3;
+  
+  // Agent ID processing this request
+  string agent_id = 4;
+  
+  // Timestamp of the trace
+  google.protobuf.Timestamp timestamp = 5;
+  
+  // Baggage items (key-value pairs propagated across services)
+  map<string, string> baggage = 6;
+}
+
+// Event that affects an agent's reputation score
+message ReputationEvent {
+  // Unique identifier for this event
+  string event_id = 1;
+  
+  // Agent whose reputation is affected
+  string agent_id = 2;
+  
+  // Type of event (e.g., "hallucination", "timeout", "success")
+  string event_type = 3;
+  
+  // Severity level
+  Severity severity = 4;
+  
+  // Change in reputation score (negative for bad events)
+  double score_delta = 5;
+  
+  // When event occurred
+  google.protobuf.Timestamp timestamp = 6;
+  
+  // Associated trace ID if event was part of a request
+  string trace_id = 7;
+  
+  // Additional context about the event
+  google.protobuf.Struct details = 8;
+  
+  // Component that detected the event
+  string detected_by = 9;
+}
+
+// Network-wide reputation score for an agent
+message ReputationScore {
+  // Agent identifier
+  string agent_id = 1;
+  
+  // Current reputation score (0.0 to 10.0)
+  double score = 2;
+  
+  // Starting reputation score
+  double initial_score = 3;
+  
+  // Total number of reputation events
+  int32 total_events = 4;
+  
+  // Number of positive reputation events
+  int32 positive_events = 5;
+  
+  // Number of negative reputation events
+  int32 negative_events = 6;
+  
+  // Timestamp of last update
+  google.protobuf.Timestamp last_updated = 7;
+  
+  // Recent reputation events (up to 100)
+  repeated ReputationEvent recent_events = 8;
+}
+
+// ============================================================================
+// Handshake Messages
+// ============================================================================
+
+// Request to initiate trust handshake
+message HandshakeRequest {
+  // Capability manifest of the requesting agent
+  CapabilityManifest manifest = 1;
+  
+  // Optional attestation record
+  AttestationRecord attestation = 2;
+  
+  // Tracing context for distributed tracing
+  TracingContext tracing = 3;
+  
+  // Challenge nonce for mutual authentication
+  bytes challenge_nonce = 4;
+}
+
+// Response to trust handshake
+message HandshakeResponse {
+  // Whether handshake was accepted
+  bool accepted = 1;
+  
+  // Capability manifest of the responding agent
+  CapabilityManifest manifest = 2;
+  
+  // Negotiated trust level
+  TrustLevel negotiated_trust = 3;
+  
+  // Session token for subsequent requests
+  string session_token = 4;
+  
+  // Session expiration time
+  google.protobuf.Timestamp session_expires = 5;
+  
+  // Warning message if trust is low
+  string warning_message = 6;
+  
+  // Response to challenge nonce (signed)
+  bytes challenge_response = 7;
+  
+  // Tracing context
+  TracingContext tracing = 8;
+}
+
+// ============================================================================
+// Action Messages
+// ============================================================================
+
+// Request to execute an action
+message ActionRequest {
+  // Session token from handshake
+  string session_token = 1;
+  
+  // Name of the action to execute
+  string action_name = 2;
+  
+  // Action parameters
+  google.protobuf.Struct parameters = 3;
+  
+  // Tracing context
+  TracingContext tracing = 4;
+  
+  // Whether this action should be reversible
+  bool require_reversible = 5;
+  
+  // Idempotency key for safe retries
+  string idempotency_key = 6;
+  
+  // Request timeout
+  google.protobuf.Duration timeout = 7;
+}
+
+// Response from action execution
+message ActionResponse {
+  // Whether action succeeded
+  bool success = 1;
+  
+  // Result data
+  google.protobuf.Struct result = 2;
+  
+  // Error message if failed
+  string error_message = 3;
+  
+  // Error code if failed
+  string error_code = 4;
+  
+  // Transaction ID for reversible actions
+  string transaction_id = 5;
+  
+  // Undo information if action is reversible
+  UndoInfo undo_info = 6;
+  
+  // Tracing context
+  TracingContext tracing = 7;
+  
+  // Execution duration
+  google.protobuf.Duration duration = 8;
+}
+
+// Information for undoing an action
+message UndoInfo {
+  // Whether this action can be undone
+  bool can_undo = 1;
+  
+  // Deadline for undo operation
+  google.protobuf.Timestamp undo_deadline = 2;
+  
+  // Instructions or data needed for undo
+  google.protobuf.Struct undo_data = 3;
+  
+  // Estimated cost of undo (if applicable)
+  string undo_cost = 4;
+}
+
+// Request to undo a previous action
+message UndoRequest {
+  // Session token
+  string session_token = 1;
+  
+  // Transaction ID to undo
+  string transaction_id = 2;
+  
+  // Reason for undo
+  string reason = 3;
+  
+  // Tracing context
+  TracingContext tracing = 4;
+}
+
+// Response from undo operation
+message UndoResponse {
+  // Whether undo succeeded
+  bool success = 1;
+  
+  // Error message if failed
+  string error_message = 2;
+  
+  // Partial undo info if only partially reversed
+  google.protobuf.Struct partial_result = 3;
+  
+  // Tracing context
+  TracingContext tracing = 4;
+}
+
+// ============================================================================
+// Reputation Messages
+// ============================================================================
+
+// Request to get an agent's reputation
+message GetReputationRequest {
+  // Agent ID to query
+  string agent_id = 1;
+  
+  // Whether to include recent events
+  bool include_events = 2;
+  
+  // Maximum number of events to include
+  int32 max_events = 3;
+}
+
+// Response with agent reputation
+message GetReputationResponse {
+  // Agent's reputation score
+  ReputationScore reputation = 1;
+  
+  // Whether agent was found
+  bool found = 2;
+}
+
+// Request to report a reputation event
+message ReportEventRequest {
+  // The reputation event to report
+  ReputationEvent event = 1;
+  
+  // Reporter's agent ID
+  string reporter_id = 2;
+  
+  // Signature from reporter (for verification)
+  string signature = 3;
+}
+
+// Response from reporting event
+message ReportEventResponse {
+  // Whether event was recorded
+  bool recorded = 1;
+  
+  // New reputation score after event
+  double new_score = 2;
+  
+  // Error message if not recorded
+  string error_message = 3;
+}
+
+// ============================================================================
+// Health & Discovery Messages
+// ============================================================================
+
+// Health check request
+message HealthCheckRequest {
+  // Optional service to check
+  string service = 1;
+}
+
+// Health check response
+message HealthCheckResponse {
+  // Overall health status
+  enum ServingStatus {
+    SERVING_STATUS_UNKNOWN = 0;
+    SERVING_STATUS_SERVING = 1;
+    SERVING_STATUS_NOT_SERVING = 2;
+  }
+  
+  ServingStatus status = 1;
+  
+  // Version of the service
+  string version = 2;
+  
+  // Uptime in seconds
+  int64 uptime_seconds = 3;
+}
+
+// ============================================================================
+// gRPC Service Definitions
+// ============================================================================
+
+// Trust Protocol Service - Core IATP functionality
+service TrustProtocol {
+  // Initiate trust handshake between agents
+  rpc Handshake(HandshakeRequest) returns (HandshakeResponse);
+  
+  // Execute an action on the remote agent
+  rpc ExecuteAction(ActionRequest) returns (ActionResponse);
+  
+  // Undo a previous action
+  rpc UndoAction(UndoRequest) returns (UndoResponse);
+  
+  // Stream of actions (for long-running operations)
+  rpc StreamActions(stream ActionRequest) returns (stream ActionResponse);
+  
+  // Health check
+  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
+}
+
+// Reputation Service - Agent reputation management
+service ReputationService {
+  // Get an agent's reputation
+  rpc GetReputation(GetReputationRequest) returns (GetReputationResponse);
+  
+  // Report a reputation event
+  rpc ReportEvent(ReportEventRequest) returns (ReportEventResponse);
+  
+  // Stream reputation updates
+  rpc StreamReputationUpdates(GetReputationRequest) returns (stream ReputationScore);
+}
+
+// Attestation Service - Codebase verification
+service AttestationService {
+  // Request attestation for an agent
+  rpc RequestAttestation(AttestationRequest) returns (AttestationResponse);
+  
+  // Verify an attestation record
+  rpc VerifyAttestation(VerifyAttestationRequest) returns (VerifyAttestationResponse);
+}
+
+// Request for attestation
+message AttestationRequest {
+  // Agent requesting attestation
+  string agent_id = 1;
+  
+  // Codebase hash to attest
+  string codebase_hash = 2;
+  
+  // Config hash to attest
+  string config_hash = 3;
+  
+  // Requested validity duration
+  google.protobuf.Duration validity = 4;
+}
+
+// Response with attestation
+message AttestationResponse {
+  // The attestation record
+  AttestationRecord attestation = 1;
+  
+  // Whether attestation was granted
+  bool granted = 2;
+  
+  // Error message if not granted
+  string error_message = 3;
+}
+
+// Request to verify attestation
+message VerifyAttestationRequest {
+  // Attestation to verify
+  AttestationRecord attestation = 1;
+}
+
+// Response from verification
+message VerifyAttestationResponse {
+  // Whether attestation is valid
+  bool valid = 1;
+  
+  // Whether attestation has expired
+  bool expired = 2;
+  
+  // Verification error if invalid
+  string error_message = 3;
+  
+  // Trust level implied by attestation
+  TrustLevel implied_trust = 4;
+}