go-sip/proto/agent/agent.proto

syntax = "proto3";

package agent;

option go_package = "git.ipao.vip/rogee/go-sip/gen/agent;agentpb";

// AgentControl is the project-owned Unary gRPC boundary between the single
// active Dispatcher and a Cell Agent. It carries metadata and facts, never
// audio bytes or an internal message-bus replacement.
service AgentControlService {
  rpc GetAgentStatus(GetAgentStatusRequest) returns (GetAgentStatusResponse);
  rpc ActivateAgent(ActivateAgentRequest) returns (ActivateAgentResponse);
  rpc GetBootstrap(GetBootstrapRequest) returns (GetBootstrapResponse);
  rpc SetAdmissionState(SetAdmissionStateRequest) returns (SetAdmissionStateResponse);
  rpc Execute(ExecuteRequest) returns (ExecuteResponse);
  // Local P1 Mock: accepts a Dispatcher-authorized, immutable dial decision.
  rpc ExecuteAuthorized(ExecuteAuthorizedRequest) returns (ExecuteAuthorizedResponse);
  rpc ExecuteApproved(ExecuteApprovedRequest) returns (ExecuteApprovedResponse);
  rpc GetLoadedSIP(GetLoadedSIPRequest) returns (GetLoadedSIPResponse);
  rpc GetExecutionPermit(GetExecutionPermitRequest) returns (GetExecutionPermitResponse);
  rpc ApplyTaskControl(ApplyTaskControlRequest) returns (ApplyTaskControlResponse);
  rpc QueryExecution(QueryExecutionRequest) returns (QueryExecutionResponse);
  rpc ReportExecutionEvent(ReportExecutionEventRequest) returns (ReportExecutionEventResponse);
  rpc RequestUpload(RequestUploadRequest) returns (RequestUploadResponse);
  rpc CompleteUpload(CompleteUploadRequest) returns (CompleteUploadResponse);
  // Agent requests a fresh bounded token explicitly; the Dispatcher owns the original target.
  rpc RequestRecordingUpload(RequestRecordingUploadRequest) returns (RequestRecordingUploadResponse);
  rpc ReportCallEnded(ReportCallEndedRequest) returns (ReportCallEndedResponse);
  rpc ReportCallResult(ReportCallResultRequest) returns (ReportCallResultResponse);
}

enum ResultCode {
  RESULT_CODE_UNSPECIFIED = 0;
  RESULT_CODE_ACCEPTED = 1;
  RESULT_CODE_APPLIED = 2;
  RESULT_CODE_REJECTED = 3;
  RESULT_CODE_UNKNOWN = 4;
  RESULT_CODE_CONFLICT = 5;
}

enum FailureCode {
  FAILURE_CODE_UNSPECIFIED = 0;
  FAILURE_CODE_INVALID_ARGUMENT = 1;
  FAILURE_CODE_UNAUTHENTICATED = 2;
  FAILURE_CODE_PERMISSION_DENIED = 3;
  FAILURE_CODE_FAILED_PRECONDITION = 4;
  FAILURE_CODE_ABORTED = 5;
  FAILURE_CODE_RESOURCE_EXHAUSTED = 6;
  FAILURE_CODE_UNAVAILABLE = 7;
  FAILURE_CODE_DEADLINE_EXCEEDED = 8;
  FAILURE_CODE_NOT_FOUND = 9;
  FAILURE_CODE_ALREADY_EXISTS = 10;
}

enum ActivationState {
  ACTIVATION_STATE_UNSPECIFIED = 0;
  ACTIVATION_STATE_PENDING = 1;
  ACTIVATION_STATE_ACTIVE = 2;
  ACTIVATION_STATE_CONFLICT = 3;
  ACTIVATION_STATE_REVOKED = 4;
}

enum AdmissionState {
  ADMISSION_STATE_UNSPECIFIED = 0;
  ADMISSION_STATE_OPEN = 1;
  ADMISSION_STATE_CLOSED = 2;
  ADMISSION_STATE_DRAINING = 3;
  ADMISSION_STATE_QUARANTINED = 4;
}

enum ControlAction {
  CONTROL_ACTION_UNSPECIFIED = 0;
  CONTROL_ACTION_PAUSE = 1;
  CONTROL_ACTION_RESUME = 2;
  CONTROL_ACTION_STOP = 3;
}

enum ActiveCallPolicy {
  ACTIVE_CALL_POLICY_UNSPECIFIED = 0;
  ACTIVE_CALL_POLICY_DRAIN = 1;
  ACTIVE_CALL_POLICY_HANGUP = 2;
}

enum ExecutionState {
  EXECUTION_STATE_UNSPECIFIED = 0;
  EXECUTION_STATE_PREPARED = 1;
  EXECUTION_STATE_PERMIT_GRANTED = 2;
  EXECUTION_STATE_DISPATCHING = 3;
  EXECUTION_STATE_OBSERVED = 4;
  EXECUTION_STATE_UNKNOWN = 5;
  EXECUTION_STATE_TERMINAL = 6;
}

enum AssetKind {
  ASSET_KIND_UNSPECIFIED = 0;
  ASSET_KIND_RECORDING = 1;
  ASSET_KIND_TRANSCRIPT = 2;
}

enum UploadState {
  UPLOAD_STATE_UNSPECIFIED = 0;
  UPLOAD_STATE_REQUESTED = 1;
  UPLOAD_STATE_COMPLETED = 3;
  UPLOAD_STATE_FAILED = 4;
  reserved 2, 5;
  reserved "UPLOAD_STATE_UPLOADING", "UPLOAD_STATE_EXPIRED";
}

enum FactKind {
  FACT_KIND_UNSPECIFIED = 0;
  FACT_KIND_EXECUTION_ACCEPTED = 1;
  FACT_KIND_CALL_STATUS = 2;
  FACT_KIND_CALL_FINISHED = 3;
  FACT_KIND_TRANSCRIPT_UPDATED = 4;
  FACT_KIND_TRANSCRIPT_FAILED = 5;
  FACT_KIND_CONTACT_OPT_OUT = 6;
  FACT_KIND_RECORDING_PROGRESS = 7;
}

message RequestMeta {
  string protocol_version = 1;
  string request_id = 2;
  string trace_id = 3;
  string operation_id = 4;
  int64 deadline_unix_ms = 5;
  string dispatcher_epoch = 6;
  string agent_id = 7;
  string cell_id = 8;
  string boot_id = 9;
  uint64 session_generation = 10;
  string idempotency_key = 11;
}

message ResponseMeta {
  string protocol_version = 1;
  string request_id = 2;
  string trace_id = 3;
  string operation_id = 4;
  int64 observed_at_unix_ms = 5;
  string dispatcher_epoch = 6;
  string agent_id = 7;
  string cell_id = 8;
  string boot_id = 9;
  uint64 session_generation = 10;
}

message Failure {
  FailureCode code = 1;
  bool retryable = 2;
  string detail = 3;
  string field = 4;
}

message OperationReceipt {
  ResponseMeta meta = 1;
  ResultCode result = 2;
  Failure failure = 3;
  string fact_id = 4;
  string content_sha256 = 5;
  int64 accepted_at_unix_ms = 6;
}

message AgentBinding {
  string agent_id = 1;
  string cell_id = 2;
  string expected_boot_id = 3;
  string dispatcher_epoch = 4;
  uint64 session_generation = 5;
  string endpoint_id = 6;
  string dispatcher_id = 7; // Bound to the active, authenticated D session.
}

message Capability {
  string name = 1;
  string version = 2;
  string value = 3;
}

message ResourceSample {
  int64 observed_at_unix_ms = 1;
  double cpu_used_ratio = 2;
  int64 memory_available_bytes = 3;
  int64 fd_used = 4;
  int64 fd_limit = 5;
  int64 spool_used_bytes = 6;
  int64 spool_capacity_bytes = 7;
  int64 media_ports_used = 8;
  int64 media_ports_capacity = 9;
  bool sample_fresh = 10;
  string missing_reason = 11;
}

// Project-local v0.1 status convention: exactly one kind="sip" entry identifies
// the SIP artifact loaded by the Agent/Asterisk; state="applied" means that exact
// artifact is active. revision and config_sha256 must match the approved artifact.
// Missing, duplicate, or mismatched SIP entries are unknown and fail closed.
message AppliedConfig {
  string kind = 1;
  string revision = 2;
  string config_sha256 = 3;
  string state = 4;
  int64 observed_at_unix_ms = 5;
}

message AgentStatus {
  string agent_id = 1;
  string cell_id = 2;
  string boot_id = 3;
  string software_version = 4;
  string protocol_version = 5;
  string asterisk_version = 6;
  AdmissionState admission_state = 7;
  repeated Capability capabilities = 8;
  ResourceSample resources = 9;
  repeated AppliedConfig applied_configs = 10;
  bool mtls_authenticated = 11;
  bool session_active = 12;
  string status_reason = 13;
}

message Session {
  string dispatcher_epoch = 1;
  uint64 session_generation = 2;
  int64 expires_at_unix_ms = 3;
  bytes session_credential = 4;
}

message ConfigReference {
  string kind = 1;
  string version = 2;
  string sha256 = 3;
  string source = 4;
}

message UploadPolicy {
  bool enabled = 1;
  int64 max_asset_bytes = 2;
  repeated string allowed_hosts = 4;
  reserved 3;
  reserved "min_retention_ms";
}

message ExecutionBinding {
  string tenant_id = 1;
  string tenant_key = 2;
  string execution_id = 3;
  string task_id = 4;
  string task_item_id = 5;
  int64 task_revision = 6;
  string call_id = 7;
  string attempt_id = 8;
  string agent_version_id = 9;
  string route_policy_id = 10;
  string caller_profile_id = 11;
}

message AssetDescriptor {
  AssetKind kind = 1;
  string asset_id = 2;
  string call_id = 3;
  string execution_id = 4;
  string format = 5;
  int64 size_bytes = 6;
  string checksum_sha256 = 7;
  int32 channels = 8;
  int32 sample_rate_hz = 9;
  int64 duration_ms = 10;
}

message Header {
  string name = 1;
  string value = 2;
}

message GetAgentStatusRequest {
  RequestMeta meta = 1;
  AgentBinding target = 2;
}

message GetAgentStatusResponse {
  ResponseMeta meta = 1;
  AgentStatus status = 2;
  Failure failure = 3;
}

message ActivateAgentRequest {
  RequestMeta meta = 1;
  AgentBinding binding = 2;
  string activation_operation_id = 3;
  bytes session_nonce = 4;
  int64 session_expires_at_unix_ms = 5;
}

message ActivateAgentResponse {
  ResponseMeta meta = 1;
  ActivationState state = 2;
  Session session = 3;
  Failure failure = 4;
}

message GetBootstrapRequest {
  RequestMeta meta = 1;
  string agent_id = 2;
  string cell_id = 3;
  string boot_id = 4;
  uint64 session_generation = 5;
}

message GetBootstrapResponse {
  ResponseMeta meta = 1;
  ActivationState state = 2;
  repeated ConfigReference runtime_configs = 3;
  UploadPolicy upload_policy = 4;
  Failure failure = 5;
}

message SetAdmissionStateRequest {
  RequestMeta meta = 1;
  AgentBinding target = 2;
  AdmissionState state = 3;
  string barrier_id = 4;
  uint64 expected_admission_generation = 5;
  string reason = 6;
}

message SetAdmissionStateResponse {
  OperationReceipt receipt = 1;
  uint64 applied_admission_generation = 2;
}

message ExecuteRequest {
  RequestMeta meta = 1;
  ExecutionBinding binding = 2;
  bytes call_execute_json = 3;
  string config_sha256 = 4;
  uint64 admission_generation = 5;
  string resource_reservation_id = 6;
  string permit_id = 7;
}

message ExecuteResponse {
  OperationReceipt receipt = 1;
  ExecutionState state = 2;
}

// Versioned project-local D→Agent execution contract. Only the Dispatcher
// evaluates the task/line schedule, allowlist, route and effective duration.
// The Agent checks the authorized deadline and transport/session identity; it
// never selects another trunk or recalculates outbound business policy.
message ExecuteAuthorizedRequest {
  string schema_version = 1; // agent-authorized-origination.v0.1
  RequestMeta meta = 2;
  ExecutionBinding binding = 3;
  string selected_trunk_id = 4;
  string caller_id = 5;
  string callee = 6;
  int64 ring_timeout_ms = 7;
  int64 max_call_duration_ms = 8;
  int64 dial_before_unix_ms = 9; // Exclusive D-issued deadline.
  string bound_snapshot_sha256 = 10;
}

message ExecuteAuthorizedResponse {
  OperationReceipt receipt = 1;
  ExecutionState state = 2;
}

// Exact, immutable task/provider bytes and SIP revision accompany each
// authorized execution. Provider bytes may contain credentials: never log
// or persist this request body. The Agent checks session, binding and
// deadline, but does not recalculate the Dispatcher outbound policy.
message ExecuteApprovedRequest {
  RequestMeta meta = 1;
  string dispatcher_id = 2;
  int64 tenant_id = 3;
  string task_id = 4;
  string source_event_id = 5;
  string call_id = 6;
  string selected_trunk_id = 7;
  string caller_id = 8;
  string callee = 9;
  string dialed_callee = 10;
  int64 ring_timeout_ms = 11;
  int64 max_call_duration_ms = 12;
  int64 dial_before_unix_ms = 13;
  int64 sip_revision = 14;
  bytes task_config_json = 15;
  bytes providers_json = 16;
  string binding_sha256 = 17;
}

message ExecuteApprovedResponse {
  string call_id = 1;
  bool accepted = 2;
}

message GetLoadedSIPRequest {
  RequestMeta meta = 1;
}

message GetLoadedSIPResponse {
  map<string, int64> trunk_revision = 1;
}

message GetExecutionPermitRequest {
  RequestMeta meta = 1;
  ExecutionBinding binding = 2;
  string resource_reservation_id = 3;
  int64 expected_task_revision = 4;
  uint64 admission_generation = 5;
  string config_sha256 = 6;
}

message ExecutionPermit {
  string permit_id = 1;
  string resource_reservation_id = 2;
  int64 issued_at_unix_ms = 3;
  int64 expires_at_unix_ms = 4;
  string dispatcher_epoch = 5;
  uint64 session_generation = 6;
  string fencing_token = 7;
  string config_sha256 = 8;
}

message GetExecutionPermitResponse {
  OperationReceipt receipt = 1;
  ExecutionPermit permit = 2;
}

message ApplyTaskControlRequest {
  RequestMeta meta = 1;
  ExecutionBinding binding = 2;
  ControlAction action = 3;
  ActiveCallPolicy active_call_policy = 4;
  int64 expected_task_revision = 5;
  string reason = 6;
}

message ApplyTaskControlResponse {
  OperationReceipt receipt = 1;
  int64 applied_task_revision = 2;
  ExecutionState state = 3;
}

message QueryExecutionRequest {
  RequestMeta meta = 1;
  ExecutionBinding binding = 2;
}

message ExecutionSnapshot {
  ExecutionBinding binding = 1;
  ExecutionState state = 2;
  string call_state = 3;
  string attempt_id = 4;
  string reason_code = 5;
  int64 observed_at_unix_ms = 6;
  bool unknown = 7;
  repeated AssetDescriptor assets = 8;
}

message QueryExecutionResponse {
  ResponseMeta meta = 1;
  ExecutionSnapshot snapshot = 2;
  Failure failure = 3;
}

message ExecutionFact {
  string fact_id = 1;
  string content_sha256 = 2;
  ExecutionBinding binding = 3;
  FactKind kind = 4;
  int64 observed_at_unix_ms = 5;
  string source_boot_id = 6;
  uint64 source_sequence = 7;
  bytes payload_json = 8;
}

message ReportExecutionEventRequest {
  RequestMeta meta = 1;
  ExecutionFact fact = 2;
}

message ReportExecutionEventResponse {
  OperationReceipt receipt = 1;
}

message RequestUploadRequest {
  RequestMeta meta = 1;
  ExecutionBinding binding = 2;
  AssetDescriptor asset = 3;
  string upload_id = 4;
}

message UploadGrant {
  string upload_id = 1;
  string target_url = 2;
  repeated Header headers = 3;
  int64 expires_at_unix_ms = 4;
  string object_key = 5;
  string required_checksum_sha256 = 6;
  int64 max_bytes = 7;
  string bucket = 8;
}

message RequestUploadResponse {
  OperationReceipt receipt = 1;
  UploadGrant grant = 2;
  UploadState state = 3;
}

message CompleteUploadRequest {
  RequestMeta meta = 1;
  ExecutionBinding binding = 2;
  AssetDescriptor asset = 3;
  string upload_id = 4;
  int64 uploaded_size_bytes = 5;
  string uploaded_checksum_sha256 = 6;
}

message CompleteUploadResponse {
  OperationReceipt receipt = 1;
  UploadState state = 2;
  reserved 3;
  reserved "oss_id";
}

// These facts refer only to the Dispatcher-approved execution identified by
// source_event_id; no audio bytes or temporary credential is persisted in MQ.
message RequestRecordingUploadRequest {
  RequestMeta meta = 1;
  string dispatcher_id = 2;
  int64 tenant_id = 3;
  string source_event_id = 4;
  string upload_id = 5;
  AssetDescriptor asset = 6;
}

message RequestRecordingUploadResponse {
  UploadGrant grant = 1;
}

message ReportCallEndedRequest {
  RequestMeta meta = 1;
  string dispatcher_id = 2;
  int64 tenant_id = 3;
  string source_event_id = 4;
}

message ReportCallEndedResponse {
  OperationReceipt receipt = 1;
}

message UploadObservation {
  string upload_id = 1;
  string recording_id = 2;
  int32 put_status_code = 3;
  int64 size_bytes = 4;
  string checksum_sha256 = 5;
}

message ReportCallResultRequest {
  RequestMeta meta = 1;
  string dispatcher_id = 2;
  int64 tenant_id = 3;
  string source_event_id = 4;
  bytes result_payload_json = 5;
  UploadObservation upload = 6;
}

message ReportCallResultResponse {
  OperationReceipt receipt = 1;
}