Skip to content

Services

Complete API reference for all SW4RM protocol services. Each service provides specialized functionality and can be scaled independently in production deployments.

Core Services

Registry Service

Purpose: Agent lifecycle management, discovery, and health monitoring.

Register Agent

rpc Register(RegisterAgentRequest) returns (RegisterAgentResponse);

message RegisterAgentRequest {
  string agent_id = 1;
  string display_name = 2;
  repeated string capabilities = 3;
  map<string, string> metadata = 4;
  HealthConfig health_config = 5;
}

message RegisterAgentResponse {
  bool success = 1;
  string registration_token = 2;
  uint64 heartbeat_interval_ms = 3;
  repeated PolicyRule policies = 4;
}

Example:

{
  "agent_id": "log-analyzer-001",
  "display_name": "Production Log Analyzer",
  "capabilities": ["log_parsing", "anomaly_detection", "alerting"],
  "metadata": {
    "version": "2.1.0",
    "environment": "production",
    "region": "us-west-2"
  },
  "health_config": {
    "check_interval_ms": 30000,
    "timeout_ms": 5000
  }
}

Note: Deployments include additional declaration fields aligned with the spec, such as communication_class and max_parallel_instances. Field names and placement vary by schema version. Include these fields where supported to enable correct routing and scheduling policies.

Discover Agents

rpc DiscoverAgents(DiscoverAgentsRequest) returns (DiscoverAgentsResponse);

message DiscoverAgentsRequest {
  repeated string required_capabilities = 1;
  map<string, string> metadata_filters = 2;
  bool include_health_status = 3;
}

message DiscoverAgentsResponse {
  repeated AgentInfo agents = 1;

  message AgentInfo {
    string agent_id = 1;
    string display_name = 2;
    repeated string capabilities = 3;
    HealthStatus health_status = 4;
    uint64 last_seen_timestamp = 5;
  }
}

Health Monitoring

rpc SendHeartbeat(HeartbeatRequest) returns (HeartbeatResponse);

message HeartbeatRequest {
  string agent_id = 1;
  string registration_token = 2;
  HealthMetrics metrics = 3;
}

message HealthMetrics {
  uint64 messages_processed = 1;
  double cpu_usage_percent = 2;
  uint64 memory_usage_mb = 3;
  double error_rate_percent = 4;
  repeated string active_capabilities = 5;
}

Router Service

Purpose: Reliable message routing, delivery guarantees, and load balancing.

Send Message

rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);

message SendMessageRequest {
  Envelope envelope = 1;
  DeliveryOptions delivery_options = 2;
}

message DeliveryOptions {
  uint32 retry_attempts = 1;        // Max retry attempts
  uint64 retry_delay_ms = 2;        // Initial retry delay
  double retry_backoff_factor = 3;  // Exponential backoff multiplier
  uint64 ttl_ms = 4;               // Message time-to-live
  bool require_ack = 5;            // Wait for acknowledgment
  uint64 ack_timeout_ms = 6;       // Acknowledgment timeout
}

message SendMessageResponse {
  bool accepted = 1;
  string delivery_id = 2;
  ErrorCode error_code = 3;
  string error_message = 4;
}

Stream Messages

rpc StreamMessages(StreamMessagesRequest) returns (stream Envelope);

message StreamMessagesRequest {
  string agent_id = 1;
  repeated MessageType message_types = 2;
  map<string, string> filters = 3;
  uint32 buffer_size = 4;
  bool include_acks = 5;
}

Message Status

rpc GetMessageStatus(GetMessageStatusRequest) returns (GetMessageStatusResponse);

message GetMessageStatusRequest {
  repeated string message_ids = 1;
}

message GetMessageStatusResponse {
  map<string, MessageStatus> statuses = 1;

  message MessageStatus {
    string message_id = 1;
    DeliveryStage stage = 2;
    repeated Ack acknowledgments = 3;
    uint64 last_update_timestamp = 4;
    ErrorCode error_code = 5;
  }
}

Scheduler Service

Purpose: Work coordination, task distribution, and resource management.

Submit Task

rpc SubmitTask(SubmitTaskRequest) returns (SubmitTaskResponse);

message SubmitTaskRequest {
  string task_id = 1;
  TaskDefinition task = 2;
  TaskConstraints constraints = 3;
  map<string, string> metadata = 4;
}

message TaskDefinition {
  string task_type = 1;
  bytes payload = 2;
  repeated string required_capabilities = 3;
  TaskPriority priority = 4;
  uint64 deadline_timestamp = 5;
}

message TaskConstraints {
  repeated string preferred_agents = 1;
  repeated string excluded_agents = 2;
  ResourceRequirements resources = 3;
  uint32 max_retries = 4;
  bool allow_preemption = 5;
}

Query Tasks

rpc QueryTasks(QueryTasksRequest) returns (QueryTasksResponse);

message QueryTasksRequest {
  repeated TaskStatus status_filter = 1;
  string agent_id_filter = 2;
  uint64 since_timestamp = 3;
  uint32 limit = 4;
}

message QueryTasksResponse {
  repeated TaskInfo tasks = 1;

  message TaskInfo {
    string task_id = 1;
    TaskStatus status = 2;
    string assigned_agent = 3;
    uint64 created_timestamp = 4;
    uint64 started_timestamp = 5;
    uint64 completed_timestamp = 6;
    ExecutionMetrics metrics = 7;
  }
}

Extended Services

HITL Service

Purpose: Human-in-the-loop workflows, approvals, and manual interventions.

Request Approval

rpc RequestApproval(ApprovalRequest) returns (ApprovalResponse);

message ApprovalRequest {
  string request_id = 1;
  ApprovalType approval_type = 2;
  string context = 3;
  repeated string approver_roles = 4;
  uint64 deadline_timestamp = 5;
  ApprovalPolicy policy = 6;
}

message ApprovalPolicy {
  uint32 required_approvals = 1;
  bool allow_self_approval = 2;
  string auto_timeout_action = 3;  // "APPROVE", "DENY", "ESCALATE"
  repeated ApprovalRule rules = 4;
}

Poll Decisions

rpc PollDecisions(PollDecisionsRequest) returns (stream ApprovalDecision);

message ApprovalDecision {
  string request_id = 1;
  DecisionType decision = 2;      // APPROVED, DENIED, ESCALATED
  string approver_id = 3;
  string reason = 4;
  uint64 timestamp = 5;
  map<string, string> metadata = 6;
}

Worktree Service

Purpose: Repository context management, workspace isolation, and version control.

Bind Worktree

rpc BindWorktree(BindWorktreeRequest) returns (BindWorktreeResponse);

message BindWorktreeRequest {
  string agent_id = 1;
  string repo_id = 2;
  string worktree_id = 3;
  WorktreeConfig config = 4;
}

message WorktreeConfig {
  string branch = 1;
  string commit_sha = 2;
  IsolationLevel isolation_level = 3;
  repeated PolicyHook hooks = 4;
  map<string, string> environment = 5;
}

message BindWorktreeResponse {
  bool success = 1;
  string workspace_path = 2;
  WorktreeInfo info = 3;
  repeated string available_commands = 4;
}

Execute Git Command

rpc ExecuteGitCommand(GitCommandRequest) returns (GitCommandResponse);

message GitCommandRequest {
  string agent_id = 1;
  string worktree_id = 2;
  repeated string command_args = 3;
  map<string, string> options = 4;
  uint64 timeout_ms = 5;
}

message GitCommandResponse {
  int32 exit_code = 1;
  string stdout = 2;
  string stderr = 3;
  uint64 execution_time_ms = 4;
  WorktreeInfo updated_info = 5;
}

Tool Service

Purpose: External tool execution, API integration, and result management.

Execute Tool

rpc ExecuteTool(ToolExecutionRequest) returns (ToolExecutionResponse);

message ToolExecutionRequest {
  string tool_name = 1;
  string operation = 2;
  map<string, bytes> parameters = 3;
  ExecutionPolicy policy = 4;
  string correlation_id = 5;
}

message ExecutionPolicy {
  uint64 timeout_ms = 1;
  uint32 retry_attempts = 2;
  IsolationLevel isolation = 3;
  ResourceLimits limits = 4;
  repeated string allowed_domains = 5;
  bool capture_output = 6;
}

message ToolExecutionResponse {
  bool success = 1;
  int32 exit_code = 2;
  bytes result_data = 3;
  string error_message = 4;
  ExecutionMetrics metrics = 5;
  repeated string logs = 6;
}

List Available Tools

rpc ListTools(ListToolsRequest) returns (ListToolsResponse);

message ListToolsResponse {
  repeated ToolDefinition tools = 1;

  message ToolDefinition {
    string name = 1;
    string description = 2;
    repeated string supported_operations = 3;
    ParameterSchema parameter_schema = 4;
    repeated string required_permissions = 5;
    ToolCapabilities capabilities = 6;
  }
}

Negotiation Service

Purpose: Multi-agent consensus, artifact approval workflows, and coordination.

Port: 50064

Submit Proposal

rpc SubmitProposal(NegotiationProposal) returns (ProposalResponse);

message NegotiationProposal {
  string artifact_type = 1;           // REQUIREMENTS, PLAN, CODE, DEPLOYMENT
  string artifact_id = 2;             // Unique identifier
  bytes artifact = 3;                 // Binary content
  string artifact_content_type = 4;   // MIME type
  repeated string requested_critics = 5; // Critic agent IDs
  string negotiation_room_id = 6;     // Session identifier
  string producer_id = 7;             // Submitting agent
}

message ProposalResponse {
  bool accepted = 1;
  string proposal_id = 2;
  string negotiation_room_id = 3;
  repeated string assigned_critics = 4;
}

Submit Vote

rpc SubmitVote(NegotiationVote) returns (VoteResponse);

message NegotiationVote {
  string artifact_id = 1;
  string critic_id = 2;
  float score = 3;                    // 0-10 score
  float confidence = 4;               // 0-1 confidence level
  bool passed = 5;                    // Meets minimum criteria
  repeated string strengths = 6;
  repeated string weaknesses = 7;
  repeated string recommendations = 8;
  string negotiation_room_id = 9;
}

Wait for Decision

rpc WaitForDecision(WaitRequest) returns (NegotiationDecision);

message NegotiationDecision {
  string artifact_id = 1;
  DecisionOutcome outcome = 2;        // APPROVED, REVISION_REQUESTED, ESCALATED_TO_HITL
  repeated NegotiationVote votes = 3;
  AggregatedScore aggregated_score = 4;
  string rationale = 5;
  string policy_version = 6;
}

message AggregatedScore {
  float mean = 1;
  float weighted_mean = 2;
  float min_score = 3;
  float max_score = 4;
  float std_dev = 5;
  int32 vote_count = 6;
}

Reasoning Service

Purpose: Decision support, parallelism evaluation, and debate orchestration.

Port: 50065

Evaluate Options

rpc EvaluateOptions(EvaluationRequest) returns (EvaluationResponse);

message EvaluationRequest {
  string evaluation_id = 1;
  repeated OptionCandidate candidates = 2;
  EvaluationCriteria criteria = 3;
  string context = 4;
}

message OptionCandidate {
  string option_id = 1;
  string description = 2;
  bytes data = 3;
  map<string, float> estimated_scores = 4;
}

message EvaluationCriteria {
  repeated CriterionWeight weights = 1;
  float minimum_threshold = 2;
  EvaluationStrategy strategy = 3;  // WEIGHTED_SUM, PARETO, MULTI_OBJECTIVE
}

message EvaluationResponse {
  string evaluation_id = 1;
  repeated RankedOption results = 2;
  string selected_option_id = 3;
  string rationale = 4;
}

Start Debate

rpc StartDebate(DebateRequest) returns (DebateSession);

message DebateRequest {
  string topic = 1;
  repeated string participant_agents = 2;
  DebateConfig config = 3;
}

message DebateConfig {
  int32 max_rounds = 1;
  int64 round_timeout_ms = 2;
  string moderator_policy = 3;
  repeated string position_types = 4;  // PRO, CON, NEUTRAL
}

message DebateSession {
  string session_id = 1;
  string status = 2;
  repeated DebateRound rounds = 3;
  DebateSummary summary = 4;
}

Logging Service

Purpose: Distributed logging, audit trails, and compliance reporting.

Port: 50066

Emit Log Entry

rpc EmitLog(LogEntry) returns (LogResponse);

message LogEntry {
  string log_id = 1;
  string agent_id = 2;
  LogLevel level = 3;                 // DEBUG, INFO, WARN, ERROR, FATAL
  string message = 4;
  map<string, string> attributes = 5;
  string correlation_id = 6;
  string span_id = 7;
  uint64 timestamp = 8;
}

enum LogLevel {
  LOG_LEVEL_UNSPECIFIED = 0;
  DEBUG = 1;
  INFO = 2;
  WARN = 3;
  ERROR = 4;
  FATAL = 5;
}

message LogResponse {
  bool accepted = 1;
  string log_id = 2;
}

Query Logs

rpc QueryLogs(LogQuery) returns (stream LogEntry);

message LogQuery {
  repeated string agent_ids = 1;
  LogLevel min_level = 2;
  uint64 start_timestamp = 3;
  uint64 end_timestamp = 4;
  map<string, string> attribute_filters = 5;
  string correlation_id = 6;
  int32 limit = 7;
}

Emit Audit Event

rpc EmitAuditEvent(AuditEvent) returns (AuditResponse);

message AuditEvent {
  string event_id = 1;
  string actor_id = 2;                // Agent or user performing action
  string action = 3;                  // CREATE, READ, UPDATE, DELETE, EXECUTE
  string resource_type = 4;           // message, task, worktree, etc.
  string resource_id = 5;
  string result = 6;                  // SUCCESS, FAILURE, DENIED
  map<string, string> metadata = 7;
  uint64 timestamp = 8;
}

Connector Service

Purpose: External API integration, tool provider registration, and capability bridging.

Port: 50067

Register Provider

rpc RegisterProvider(ProviderRegistration) returns (RegistrationResponse);

message ProviderRegistration {
  string provider_id = 1;
  string provider_name = 2;
  ProviderType provider_type = 3;     // MCP, REST, GRPC, CUSTOM
  repeated ToolDescriptor tools = 4;
  ConnectionConfig connection = 5;
  HealthCheckConfig health_config = 6;
}

message ToolDescriptor {
  string tool_name = 1;
  string description = 2;
  bytes input_schema = 3;             // JSON Schema
  bytes output_schema = 4;            // JSON Schema
  repeated string required_permissions = 5;
  bool is_idempotent = 6;
  bool supports_streaming = 7;
}

message ConnectionConfig {
  string endpoint = 1;
  AuthConfig auth = 2;
  TlsConfig tls = 3;
  int64 timeout_ms = 4;
  int32 max_concurrent_requests = 5;
}

Invoke Tool

rpc InvokeTool(ToolInvocation) returns (ToolResult);

message ToolInvocation {
  string provider_id = 1;
  string tool_name = 2;
  bytes arguments = 3;                // JSON-encoded arguments
  string correlation_id = 4;
  ExecutionPolicy policy = 5;
}

message ToolResult {
  bool success = 1;
  bytes result = 2;                   // JSON-encoded result
  string error_message = 3;
  int64 execution_time_ms = 4;
  map<string, string> metadata = 5;
}

List Providers

rpc ListProviders(ListProvidersRequest) returns (ListProvidersResponse);

message ListProvidersResponse {
  repeated ProviderInfo providers = 1;

  message ProviderInfo {
    string provider_id = 1;
    string provider_name = 2;
    ProviderType provider_type = 3;
    HealthStatus health_status = 4;
    repeated string available_tools = 5;
    uint64 last_seen_timestamp = 6;
  }
}

Scheduler Policy Service

Purpose: Negotiation policy configuration, profile management, and evaluation reporting.

Port: 50070

Package: sw4rm.scheduler

Set Negotiation Policy

rpc SetNegotiationPolicy(SetNegotiationPolicyRequest) returns (SetNegotiationPolicyResponse);

message SetNegotiationPolicyRequest {
  NegotiationPolicy policy = 1;
}

message SetNegotiationPolicyResponse {
  bool ok = 1;
  string reason = 2;
}

Get Negotiation Policy

rpc GetNegotiationPolicy(GetNegotiationPolicyRequest) returns (GetNegotiationPolicyResponse);

message GetNegotiationPolicyResponse {
  NegotiationPolicy policy = 1;
}

Set/List Policy Profiles

rpc SetPolicyProfiles(SetPolicyProfilesRequest) returns (SetPolicyProfilesResponse);
rpc ListPolicyProfiles(ListPolicyProfilesRequest) returns (ListPolicyProfilesResponse);

Get Effective Policy

rpc GetEffectivePolicy(GetEffectivePolicyRequest) returns (GetEffectivePolicyResponse);

message GetEffectivePolicyRequest {
  string negotiation_id = 1;
}

message GetEffectivePolicyResponse {
  EffectivePolicy effective = 1;
}

Submit Evaluation / HITL Action

rpc SubmitEvaluation(SubmitEvaluationRequest) returns (SubmitEvaluationResponse);
rpc HitlAction(HitlActionRequest) returns (HitlActionResponse);

For client usage details, see Scheduler Policy Client.

Negotiation Room Service

Purpose: Multi-agent artifact approval workflows with producer-critic-coordinator pattern.

Port: 50068

Package: sw4rm.negotiation_room

Submit Proposal

rpc SubmitProposal(SubmitProposalRequest) returns (SubmitProposalResponse);

message SubmitProposalRequest {
  NegotiationProposal proposal = 1;
}

message SubmitProposalResponse {
  string artifact_id = 1;
  string negotiation_room_id = 2;
}

Submit Vote

rpc SubmitVote(SubmitVoteRequest) returns (SubmitVoteResponse);

message SubmitVoteRequest {
  NegotiationVote vote = 1;
}

message SubmitVoteResponse {
  string artifact_id = 1;
  string critic_id = 2;
}

Get Votes / Get Decision / Wait For Decision

rpc GetVotes(GetVotesRequest) returns (GetVotesResponse);
rpc GetDecision(GetDecisionRequest) returns (GetDecisionResponse);
rpc WaitForDecision(WaitForDecisionRequest) returns (WaitForDecisionResponse);

WaitForDecision blocks until a decision is rendered or timeout_seconds expires.

For client usage details, see Negotiation Room Client.

Handoff Service

Purpose: Safe delegation of work between agents when capability requirements change or workload balancing is needed.

Port: 50071

Package: sw4rm.handoff

Request Handoff

rpc RequestHandoff(HandoffRequest) returns (Empty);

message HandoffRequest {
  string request_id = 1;
  string from_agent = 2;
  string to_agent = 3;
  string reason = 4;
  bytes context_snapshot = 5;
  repeated string capabilities_required = 6;
  int32 priority = 7;
  google.protobuf.Duration timeout = 8;
}

Accept / Reject Handoff

rpc AcceptHandoff(HandoffResponse) returns (Empty);
rpc RejectHandoff(HandoffResponse) returns (Empty);

message HandoffResponse {
  string request_id = 1;
  bool accepted = 2;
  string accepting_agent = 3;
  string rejection_reason = 4;
}

Get Pending Handoffs / Complete Handoff

rpc GetPendingHandoffs(GetPendingHandoffsRequest) returns (GetPendingHandoffsResponse);
rpc CompleteHandoff(CompleteHandoffRequest) returns (CompleteHandoffResponse);

Handoff states: PENDINGACCEPTED/REJECTEDCOMPLETED/EXPIRED.

For client usage details, see Handoff Client.

Workflow Service

Purpose: DAG-based multi-agent task coordination where nodes represent agent-executed steps with explicit dependencies.

Port: 50072

Package: sw4rm.workflow

Create Workflow

rpc CreateWorkflow(CreateWorkflowRequest) returns (CreateWorkflowResponse);

message CreateWorkflowRequest {
  WorkflowDefinition definition = 1;
}

message CreateWorkflowResponse {
  string workflow_id = 1;
  bool success = 2;
  string error = 3;
}

Implementations MUST validate the workflow definition forms a valid DAG (no cycles) before persisting. On cycle detection, CreateWorkflow MUST fail with error_code=workflow_cycle_detected.

Start / Get State / Resume Workflow

rpc StartWorkflow(StartWorkflowRequest) returns (StartWorkflowResponse);
rpc GetWorkflowState(GetWorkflowStateRequest) returns (GetWorkflowStateResponse);
rpc ResumeWorkflow(ResumeWorkflowRequest) returns (ResumeWorkflowResponse);

Node statuses: PENDINGREADYRUNNINGCOMPLETED/FAILED/SKIPPED.

For client usage details, see Workflow Client.

Activity Service

Purpose: Artifact storage and retrieval for negotiation rounds (contracts, diffs, decisions, scores).

Port: 50069

Package: sw4rm.activity

Append Artifact

rpc AppendArtifact(AppendArtifactRequest) returns (AppendArtifactResponse);

message Artifact {
  string negotiation_id = 1;
  string kind = 2;           // contract|diff|decision|score|note
  string version = 3;        // e.g., v3
  string content_type = 4;
  bytes content = 5;
  string created_at = 6;     // ISO-8601
}

message AppendArtifactResponse {
  bool ok = 1;
  string reason = 2;
}

List Artifacts

rpc ListArtifacts(ListArtifactsRequest) returns (ListArtifactsResponse);

message ListArtifactsRequest {
  string negotiation_id = 1;
  string kind = 2;           // Optional filter by artifact kind
}

message ListArtifactsResponse {
  repeated Artifact items = 1;
}

For client usage details, see Activity Client.

Service Discovery and Health

Service Registry Pattern

All services register with a central service registry. The following message defines the registration format:

message ServiceRegistration {
  string service_name = 1;
  string service_version = 2;
  repeated ServiceEndpoint endpoints = 3;
  HealthCheckConfig health_config = 4;
  map<string, string> metadata = 5;
}

message ServiceEndpoint {
  string address = 1;          // host:port
  string protocol = 2;         // "grpc", "http"
  bool tls_enabled = 3;
  map<string, string> tags = 4; // "region", "zone", "env"
}

Load Balancing Strategies

Services support the following load balancing strategies:

  • Round Robin: The load balancer distributes requests evenly across endpoints.
  • Least Connections: The load balancer routes to the endpoint with fewest active connections.
  • Weighted: The load balancer routes based on endpoint capacity weights.
  • Locality Aware: The load balancer prefers endpoints in the same region or zone.
  • Health Based: The load balancer excludes unhealthy endpoints from rotation.

Circuit Breaker Pattern

All service clients implement circuit breakers with the following configuration:

message CircuitBreakerConfig {
  uint32 failure_threshold = 1;      // Failures before opening
  uint64 recovery_timeout_ms = 2;    // Time before trying to close
  uint64 request_timeout_ms = 3;     // Individual request timeout
  double failure_rate_threshold = 4; // Percentage failure rate
}

States:

  • CLOSED: The circuit allows requests to pass through during normal operation.
  • OPEN: The circuit rejects requests immediately during failure mode.
  • HALF_OPEN: The circuit allows limited requests to test recovery.

Error Handling Patterns

Standard Error Response

message ErrorResponse {
  ErrorCode code = 1;
  string message = 2;
  repeated ErrorDetail details = 3;
  string request_id = 4;
  uint64 timestamp = 5;
}

message ErrorDetail {
  string field = 1;
  string violation = 2;
  string help_text = 3;
}

Retry Policies

All services implement exponential backoff with jitter. The following function shows the calculation:

def calculate_delay(attempt: int, base_delay_ms: int, max_delay_ms: int) -> int:
    """Calculate retry delay with exponential backoff and jitter."""
    delay = min(base_delay_ms * (2 ** attempt), max_delay_ms)
    jitter = random.uniform(0.1, 0.9) * delay
    return int(delay + jitter)

Security Considerations

Authentication

Services use mutual TLS authentication with the following configuration:

tls_config:
  cert_file: "/etc/certs/service.pem"
  key_file: "/etc/certs/service.key"
  ca_file: "/etc/certs/ca.pem"
  verify_client_cert: true
  min_tls_version: "1.3"

Authorization

The system enforces role-based access control per service:

message ServicePermission {
  string service_name = 1;
  repeated string allowed_methods = 2;
  repeated string required_roles = 3;
  repeated ResourceConstraint resource_constraints = 4;
}

Audit Logging

All service operations generate audit logs with the following structure:

{
  "timestamp": "2024-08-08T15:30:00Z",
  "service": "router",
  "method": "SendMessage", 
  "agent_id": "log-analyzer-001",
  "resource": "msg-abc123",
  "action": "CREATE",
  "result": "SUCCESS",
  "duration_ms": 125,
  "request_id": "req-def456"
}