The Cordum Agent Protocol (CAP)
CAP is the canonical protobuf contract in thecap repository. It defines the envelope, message types, job metadata, heartbeats, cancellations, safety requests, and SDK surface used by the Cordum control plane and external workers.
BusPacket envelope
Every CAP message is wrapped in a single protobuf envelope with tracing, sender identity, timestamps, protocol version, and a oneof payload.
message BusPacket {
string trace_id = 1;
string sender_id = 2;
google.protobuf.Timestamp created_at = 3;
int32 protocol_version = 4;
oneof payload {
JobRequest job_request = 10;
JobResult job_result = 11;
Heartbeat heartbeat = 12;
SystemAlert alert = 13;
JobProgress job_progress = 15;
JobCancel job_cancel = 16;
Handshake handshake = 17;
}
bytes signature = 14;
}Message types in the current proto
- JobRequest
- JobResult
- Heartbeat
- SystemAlert
- JobProgress
- JobCancel
- Handshake
Job and result payloads
Includes job identifiers, topic, priority, context_ptr, workflow lineage, labels, structured metadata, and optional compensation details for rollback-aware workflows.
Carries job_id, JobStatus, result_ptr, worker_id, execution_ms, error fields, structured ErrorCode, and artifact pointers emitted during execution.
- tenant_id / actor_id / actor_type
- idempotency_key
- capability
- risk_tags[]
- requires[]
- pack_id
- labels{}Safety and lifecycle semantics
service SafetyKernel {
rpc Check(PolicyCheckRequest) returns (PolicyCheckResponse);
rpc Evaluate(PolicyCheckRequest) returns (PolicyCheckResponse);
rpc Explain(PolicyCheckRequest) returns (PolicyCheckResponse);
rpc Simulate(PolicyCheckRequest) returns (PolicyCheckResponse);
rpc ListSnapshots(ListSnapshotsRequest) returns (ListSnapshotsResponse);
}
enum DecisionType {
DECISION_TYPE_ALLOW = 1;
DECISION_TYPE_DENY = 2;
DECISION_TYPE_REQUIRE_HUMAN = 3;
DECISION_TYPE_THROTTLE = 4;
DECISION_TYPE_ALLOW_WITH_CONSTRAINTS = 5;
}Lifecycle notes
- CAP job statuses include pending, scheduled, dispatched, running, succeeded, failed, cancelled, denied, and timeout.
FAILED_RETRYABLEandFAILED_FATALare part of the JobStatus enum.- Heartbeats report worker load, pool, max_parallel_jobs, memory_load, progress_pct, and last_memo.
- Handshakes let components advertise capabilities during connection setup.
SDK layout
The CAP repository currently includes SDK folders for multiple languages. Cordum itself imports the generated Go types and runtime helpers, while examples demonstrate integration patterns for other languages.