monarchic-agent-protocol 0.1.15 → 0.1.17

data/schemas/v1/monarchic_agent_protocol.proto

@@ -22,6 +22,9 @@ enum AgentRole {
   REVIEWER = 5;
   SECURITY = 6;
   OPS = 7;
+  PUBLISHER = 8;
+  RESEARCHER = 9;
+  VERIFICATION = 10;
 }
 
 enum OutcomeDecision {
@@ -65,20 +68,6 @@ message ExperimentSpec {
   google.protobuf.Struct extensions = 9;
 }
 
-message DeliveryContract {
-  string objective = 1;
-  repeated string definition_of_done = 2;
-  repeated string required_checks = 3;
-  string risk_tier = 4;
-  optional uint32 max_cycle_minutes = 5;
-  optional uint32 max_agent_turns = 6;
-  optional string pr_strategy = 7;
-  optional string review_policy = 8;
-  optional string rollback_strategy = 9;
-  optional string notes = 10;
-  google.protobuf.Struct extensions = 11;
-}
-
 message ObjectiveSpec {
   string metric_key = 1;
   string direction = 2;
@@ -104,6 +93,17 @@ message EvalResult {
   google.protobuf.Struct extensions = 9;
 }
 
+message FailureClass {
+  string category = 1;
+  string code = 2;
+  bool retryable = 3;
+  optional string detail = 4;
+  optional string scope = 5;
+  optional string source = 6;
+  optional string next_action = 7;
+  google.protobuf.Struct extensions = 8;
+}
+
 message Provenance {
   string prompt_sha256 = 1;
   string code_sha256 = 2;
@@ -121,9 +121,624 @@ message Provenance {
   google.protobuf.Struct extensions = 14;
 }
 
+enum IntentClass {
+  INTENT_CLASS_UNSPECIFIED = 0;
+  INTENT_CLASS_INSPECT = 1;
+  INTENT_CLASS_VALIDATE = 2;
+  INTENT_CLASS_EXECUTE = 3;
+  INTENT_CLASS_VERIFY = 4;
+}
+
+message Intent {
+  string intent_id = 1;
+  uint64 submitted_at = 2;
+  string submitter = 3;
+  string policy_version = 4;
+  string target_repo = 5;
+  string target_ref = 6;
+  string goal = 7;
+  google.protobuf.Struct constraints = 8;
+  string context_digest = 9;
+  IntentClass intent_class = 10;
+}
+
+message BootstrapIntent {
+  string contract_version = 1;
+  string bootstrap_intent_id = 2;
+  string project_key = 3;
+  repeated string target_repos = 4;
+  optional string pipeline_template_id = 5;
+  string campaign_goal = 6;
+  optional string notes = 7;
+  string priority_profile = 8;
+  uint64 created_at_ms = 9;
+}
+
+message AgentRunnerPreference {
+  string runner_id = 1;
+  optional string model = 2;
+  optional string provider = 3;
+  optional string reasoning_effort = 4;
+  repeated string required_capabilities = 5;
+  repeated string labels = 6;
+  google.protobuf.Struct extensions = 7;
+}
+
+message AgentRunnerPolicy {
+  string runner_policy_id = 1;
+  string display_name = 2;
+  optional string description = 3;
+  repeated AgentRunnerPreference runner_preferences = 4;
+  repeated string role_ids = 5;
+  google.protobuf.Struct extensions = 6;
+}
+
+message AgentProfile {
+  string agent_id = 1;
+  string role_id = 2;
+  string display_name = 3;
+  optional string description = 4;
+  repeated AgentRunnerPreference runner_preferences = 5;
+  repeated string allowed_network_modes = 6;
+  bool requires_human_review = 7;
+  repeated string required_skill_ids = 8;
+  repeated string required_mcp_ids = 9;
+  google.protobuf.Struct extensions = 10;
+  optional string runner_policy_id = 11;
+}
+
+message ResolvedAgentRunner {
+  string runner_id = 1;
+  optional string model = 2;
+  optional string provider = 3;
+  optional string reasoning_effort = 4;
+  uint32 preference_index = 5;
+  optional string selection_reason = 6;
+  google.protobuf.Struct extensions = 7;
+}
+
+message BootstrapPlanTask {
+  string task_id = 1;
+  string display_name = 2;
+  string role_id = 3;
+  string task_milestone = 4;
+  repeated string depends_on = 5;
+  optional string target_repo = 6;
+  repeated string required_skill_ids = 7;
+  repeated string required_mcp_ids = 8;
+  optional string interaction_mode = 9;
+  optional string network_mode = 10;
+  optional bool requires_human_review = 11;
+  google.protobuf.Struct filesystem_policy = 12;
+  optional string template_slot_id = 13;
+  optional string notes = 14;
+  optional string agent_id = 15;
+  optional string injected_by_role_id = 16;
+  repeated AgentRunnerPreference runner_preferences = 17;
+  optional ResolvedAgentRunner resolved_runner = 18;
+}
+
+enum BootstrapPlanningMode {
+  BOOTSTRAP_PLANNING_MODE_UNSPECIFIED = 0;
+  BOOTSTRAP_PLANNING_MODE_DIRECT_TEMPLATE_FILL = 1;
+  BOOTSTRAP_PLANNING_MODE_BOUNDED_RESEARCH_REPLAN = 2;
+}
+
+message BootstrapPlan {
+  string contract_version = 1;
+  string bootstrap_plan_id = 2;
+  string bootstrap_intent_id = 3;
+  string project_key = 4;
+  BootstrapPlanningMode planning_mode = 5;
+  optional string pipeline_template_id = 6;
+  string campaign_goal = 7;
+  uint64 created_at_ms = 8;
+  repeated BootstrapPlanTask tasks = 9;
+}
+
+message BootstrapFilesystemPolicy {
+  repeated string read = 1;
+  repeated string write = 2;
+  repeated string execute = 3;
+}
+
+message BootstrapSkillBinding {
+  string id = 1;
+  bool required = 2;
+  string purpose = 3;
+}
+
+message BootstrapTemplateSlotContext {
+  string slot_id = 1;
+  string display_name = 2;
+  string role = 3;
+  string interaction_mode = 4;
+  string network_mode = 5;
+  bool requires_human_review = 6;
+  BootstrapFilesystemPolicy filesystem_policy = 7;
+  repeated BootstrapSkillBinding required_skills = 8;
+  repeated string required_mcps = 9;
+}
+
+message BootstrapTemplateConnectionContext {
+  string from_slot_id = 1;
+  string to_slot_id = 2;
+  string kind = 3;
+  bool required = 4;
+  optional string description = 5;
+}
+
+message BootstrapTemplateLaneContext {
+  string lane_id = 1;
+  string display_name = 2;
+  string from_slot_id = 3;
+  string to_slot_id = 4;
+  repeated string slot_ids = 5;
+  bool repeat_per_task_group = 6;
+}
+
+message BootstrapTemplateContext {
+  string template_id = 1;
+  string display_name = 2;
+  repeated BootstrapTemplateSlotContext slots = 3;
+  repeated BootstrapTemplateConnectionContext connections = 4;
+  repeated BootstrapTemplateLaneContext lanes = 5;
+}
+
+message AgentCommand {
+  string runner_id = 1;
+  repeated string argv = 2;
+}
+
+message BootstrapPlanningContext {
+  string contract_version = 1;
+  string project_key = 2;
+  string target_repo = 3;
+  repeated string target_repos = 4;
+  string campaign_goal = 5;
+  optional string notes = 6;
+  string priority_profile = 7;
+  repeated string codex_cmd = 8 [deprecated = true];
+  repeated string available_skill_ids = 9;
+  optional BootstrapTemplateContext selected_template = 10;
+  BootstrapPlanningMode planning_mode = 11;
+  repeated string enabled_role_ids = 12;
+  repeated AgentCommand agent_cmds = 13;
+  repeated string default_agent_cmd = 14;
+  repeated AgentProfile agent_profiles = 15;
+  repeated RunnerCapabilities available_runners = 16;
+  repeated AgentRunnerPolicy runner_policies = 17;
+}
+
+enum CampaignPipelineConnectionKind {
+  CAMPAIGN_PIPELINE_CONNECTION_KIND_UNSPECIFIED = 0;
+  CAMPAIGN_PIPELINE_CONNECTION_KIND_DEPENDS_ON = 1;
+  CAMPAIGN_PIPELINE_CONNECTION_KIND_HANDOFF = 2;
+  CAMPAIGN_PIPELINE_CONNECTION_KIND_REVIEW = 3;
+  CAMPAIGN_PIPELINE_CONNECTION_KIND_MESSAGE_ROUTE = 4;
+  CAMPAIGN_PIPELINE_CONNECTION_KIND_ARTIFACT_FLOW = 5;
+}
+
+message CampaignPipelineTaskRef {
+  string task_id = 1;
+  string task_artifact = 2;
+  optional string role_id = 3;
+  optional string task_milestone = 4;
+  optional string task_format = 5;
+  repeated string depends_on = 6;
+  repeated string runner_args = 7;
+  optional string interaction_mode = 8;
+  optional string network_mode = 9;
+  bool requires_human_review = 10;
+  BootstrapFilesystemPolicy filesystem_policy = 11;
+  repeated BootstrapSkillBinding required_skills = 12;
+  repeated string required_mcp_ids = 13;
+}
+
+message CampaignPipelineConnection {
+  string from_task_id = 1;
+  string to_task_id = 2;
+  CampaignPipelineConnectionKind kind = 3;
+  bool required = 4;
+  optional string description = 5;
+}
+
+message CampaignPipelineGate {
+  string name = 1;
+  repeated string command = 2;
+  optional string workdir = 3;
+}
+
+message CampaignPipelineGatePolicy {
+  bool require_standard = 1;
+  repeated CampaignPipelineGate required_gates = 2;
+}
+
+message CampaignPipelineSpec {
+  string contract_version = 1;
+  string pipeline_id = 2;
+  string version = 3;
+  optional string objective = 4;
+  optional string project_key = 5;
+  bool continue_on_error = 6;
+  optional CampaignPipelineGatePolicy gate_policy = 7;
+  google.protobuf.Struct metadata = 8;
+  repeated CampaignPipelineConnection connections = 9;
+  repeated CampaignPipelineTaskRef tasks = 10;
+}
+
+enum PlanStatus {
+  PLAN_STATUS_UNSPECIFIED = 0;
+  DRAFT = 1;
+  PLANNED = 2;
+  EXECUTING = 3;
+  COMPLETE = 4;
+  BOUNDED = 5;
+  FAILED = 6;
+  CANCELLED = 7;
+  UNKNOWN = 8;
+}
+
+message RoleProvenance {
+  string role_name = 1;
+  string template_hash = 2;
+  string render_hash = 3;
+}
+
+message PlanProvenance {
+  string generated_by = 1;
+  optional string policy_profile = 2;
+  uint64 generated_at_ms = 3;
+  optional RoleProvenance role = 4;
+}
+
+message FailureDetail {
+  string class = 1;
+  string code = 2;
+  string message = 3;
+  google.protobuf.Struct details = 4;
+}
+
+enum ArtifactKind {
+  ARTIFACT_KIND_UNSPECIFIED = 0;
+  ARTIFACT_KIND_PLAN = 1;
+  ARTIFACT_KIND_EXECUTION_RECEIPT = 2;
+  ARTIFACT_KIND_VERIFICATION_RECEIPT = 3;
+  ARTIFACT_KIND_EVENT_LOG = 4;
+  ARTIFACT_KIND_DIGEST_MANIFEST = 5;
+  ARTIFACT_KIND_PROOF_MANIFEST = 6;
+  ARTIFACT_KIND_PATCH = 7;
+  ARTIFACT_KIND_TEST_REPORT = 8;
+  ARTIFACT_KIND_BUILD_LOG = 9;
+  ARTIFACT_KIND_BUNDLE = 10;
+  ARTIFACT_KIND_CUSTOM = 11;
+}
+
+message ArtifactDescriptor {
+  string artifact_id = 1;
+  ArtifactKind kind = 2;
+  string digest = 3;
+  string media_type = 4;
+  string logical_name = 5;
+  string producer = 6;
+  string contract_version = 7;
+}
+
+message DigestManifest {
+  string contract_version = 1;
+  string manifest_id = 2;
+  string run_id = 3;
+  string plan_id = 4;
+  uint64 created_at = 5;
+  string combined_digest = 6;
+  string event_digest = 7;
+  repeated ArtifactDescriptor artifact_descriptors = 8;
+}
+
+message PrincipalRef {
+  string principal_id = 1;
+  string provider = 2;
+  optional string display_name = 3;
+}
+
+message TenantRef {
+  string tenant_id = 1;
+  optional string display_name = 2;
+}
+
+enum AuthMechanism {
+  AUTH_MECHANISM_UNSPECIFIED = 0;
+  AUTH_MECHANISM_SHARED_SECRET = 1;
+  AUTH_MECHANISM_BEARER_TOKEN = 2;
+  AUTH_MECHANISM_SIGNED_TOKEN = 3;
+  AUTH_MECHANISM_MUTUAL_TLS = 4;
+  AUTH_MECHANISM_CUSTOM = 5;
+}
+
+message AuthContext {
+  string contract_version = 1;
+  string auth_context_id = 2;
+  PrincipalRef principal = 3;
+  TenantRef tenant = 4;
+  AuthMechanism mechanism = 5;
+  string credential_id = 6;
+  repeated string scopes = 7;
+  uint64 issued_at = 8;
+  optional uint64 expires_at = 9;
+}
+
+enum UsageCategory {
+  USAGE_CATEGORY_UNSPECIFIED = 0;
+  USAGE_CATEGORY_CONTROL_PLANE = 1;
+  USAGE_CATEGORY_EXECUTION = 2;
+  USAGE_CATEGORY_VERIFICATION = 3;
+  USAGE_CATEGORY_AUDIT_EXPORT = 4;
+  USAGE_CATEGORY_CUSTOM = 5;
+}
+
+enum UsageUnit {
+  USAGE_UNIT_UNSPECIFIED = 0;
+  USAGE_UNIT_REQUESTS = 1;
+  USAGE_UNIT_MILLISECONDS = 2;
+  USAGE_UNIT_BYTES = 3;
+  USAGE_UNIT_TOKENS = 4;
+  USAGE_UNIT_RUNS = 5;
+  USAGE_UNIT_CUSTOM = 6;
+}
+
+message UsageRecord {
+  string contract_version = 1;
+  string usage_id = 2;
+  PrincipalRef principal = 3;
+  TenantRef tenant = 4;
+  optional string run_id = 5;
+  optional string plan_id = 6;
+  UsageCategory category = 7;
+  string metric_name = 8;
+  uint64 quantity = 9;
+  UsageUnit unit = 10;
+  uint64 recorded_at = 11;
+}
+
+message AuditExportManifest {
+  string contract_version = 1;
+  string export_id = 2;
+  PrincipalRef principal = 3;
+  TenantRef tenant = 4;
+  string run_id = 5;
+  string plan_id = 6;
+  uint64 exported_at = 7;
+  string combined_digest = 8;
+  repeated ArtifactDescriptor artifact_descriptors = 9;
+}
+
+enum PlanStepKind {
+  PLAN_STEP_KIND_UNSPECIFIED = 0;
+  PLAN_STEP_KIND_ANALYSIS = 1;
+  PLAN_STEP_KIND_EXECUTION = 2;
+  PLAN_STEP_KIND_VERIFICATION = 3;
+  PLAN_STEP_KIND_REVIEW = 4;
+  PLAN_STEP_KIND_MERGE = 5;
+  PLAN_STEP_KIND_RELEASE = 6;
+  PLAN_STEP_KIND_CUSTOM = 7;
+}
+
+enum ReplanStrategy {
+  REPLAN_STRATEGY_UNSPECIFIED = 0;
+  REPLAN_STRATEGY_RETRY = 1;
+  REPLAN_STRATEGY_REPAIR = 2;
+  REPLAN_STRATEGY_ESCALATE = 3;
+  REPLAN_STRATEGY_BLOCK = 4;
+}
+
+message ReplanPolicy {
+  ReplanStrategy strategy = 1;
+  uint32 max_attempts = 2;
+}
+
+message StepOutputExpectation {
+  ArtifactKind kind = 1;
+  string logical_name = 2;
+}
+
+message PlanStep {
+  string step_id = 1;
+  string description = 2;
+  repeated string depends_on = 3;
+  google.protobuf.Struct task_template = 4;
+  optional FailureDetail failure = 5;
+  optional string task_id = 6;
+  PlanStepKind kind = 7;
+  google.protobuf.Struct inputs = 8;
+  repeated StepOutputExpectation expected_outputs = 9;
+  repeated string policy_tags = 10;
+}
+
+message Plan {
+  string contract_version = 1;
+  string plan_id = 2;
+  optional string run_id = 3;
+  string objective = 4;
+  PlanStatus status = 5;
+  uint64 created_at_ms = 6;
+  uint64 updated_at_ms = 7;
+  PlanProvenance provenance = 8;
+  repeated PlanStep steps = 9;
+  optional string intent_id = 10;
+  optional string plan_version = 11;
+  optional string planner_version = 12;
+  ReplanPolicy replan_policy = 13;
+  optional string input_digest = 14;
+}
+
+message ExecutionReceipt {
+  string contract_version = 1;
+  string run_id = 2;
+  string plan_id = 3;
+  string plan_hash = 4;
+  repeated string task_hashes = 5;
+  repeated string artifact_hashes = 6;
+  string outcome_hash = 7;
+  PlanStatus status = 8;
+  optional FailureDetail failure = 9;
+  uint64 generated_at_ms = 10;
+  optional ResolvedAgentRunner resolved_runner = 11;
+}
+
+enum VerificationStatus {
+  VERIFICATION_STATUS_UNSPECIFIED = 0;
+  VERIFICATION_STATUS_PENDING = 1;
+  VERIFICATION_STATUS_PASSED = 2;
+  VERIFICATION_STATUS_FAILED = 3;
+  VERIFICATION_STATUS_BLOCKED = 4;
+}
+
+enum VerificationCheckStatus {
+  VERIFICATION_CHECK_STATUS_UNSPECIFIED = 0;
+  VERIFICATION_CHECK_STATUS_PASSED = 1;
+  VERIFICATION_CHECK_STATUS_FAILED = 2;
+  VERIFICATION_CHECK_STATUS_BLOCKED = 3;
+  VERIFICATION_CHECK_STATUS_SKIPPED = 4;
+}
+
+enum BlockedOutcomeScope {
+  BLOCKED_OUTCOME_SCOPE_UNSPECIFIED = 0;
+  BLOCKED_OUTCOME_SCOPE_INTENT = 1;
+  BLOCKED_OUTCOME_SCOPE_PLAN = 2;
+  BLOCKED_OUTCOME_SCOPE_STEP = 3;
+  BLOCKED_OUTCOME_SCOPE_RUN = 4;
+  BLOCKED_OUTCOME_SCOPE_VERIFICATION = 5;
+  BLOCKED_OUTCOME_SCOPE_MERGE = 6;
+  BLOCKED_OUTCOME_SCOPE_RELEASE = 7;
+}
+
+message VerificationCheck {
+  string check_id = 1;
+  string name = 2;
+  VerificationCheckStatus status = 3;
+  string message = 4;
+  repeated string artifact_ids = 5;
+}
+
+message BlockedOutcome {
+  string code = 1;
+  BlockedOutcomeScope scope = 2;
+  string message = 3;
+  google.protobuf.Struct details = 4;
+  repeated ArtifactDescriptor blocking_artifacts = 5;
+}
+
+message VerificationReceipt {
+  string contract_version = 1;
+  string verification_id = 2;
+  string plan_id = 3;
+  repeated string execution_receipt_ids = 4;
+  string verification_policy_version = 5;
+  VerificationStatus status = 6;
+  repeated VerificationCheck checks = 7;
+  repeated BlockedOutcome blocked_outcomes = 8;
+  repeated string artifact_digest_set = 9;
+  uint64 verified_at_ms = 10;
+}
+
+enum ReviewDecisionScope {
+  REVIEW_DECISION_SCOPE_UNSPECIFIED = 0;
+  REVIEW_DECISION_SCOPE_PLAN = 1;
+  REVIEW_DECISION_SCOPE_STEP = 2;
+  REVIEW_DECISION_SCOPE_PULL_REQUEST = 3;
+  REVIEW_DECISION_SCOPE_VERIFICATION = 4;
+  REVIEW_DECISION_SCOPE_RELEASE = 5;
+}
+
+enum ReviewDisposition {
+  REVIEW_DISPOSITION_UNSPECIFIED = 0;
+  REVIEW_DISPOSITION_APPROVE = 1;
+  REVIEW_DISPOSITION_REQUEST_CHANGES = 2;
+  REVIEW_DISPOSITION_REJECT = 3;
+  REVIEW_DISPOSITION_DEFER = 4;
+}
+
+message ReviewDecision {
+  string decision_id = 1;
+  string plan_id = 2;
+  ReviewDecisionScope scope = 3;
+  string actor = 4;
+  ReviewDisposition decision = 5;
+  string reason = 6;
+  uint64 created_at = 7;
+}
+
+enum RerunTrigger {
+  RERUN_TRIGGER_UNSPECIFIED = 0;
+  RERUN_TRIGGER_REVIEW_DECISION = 1;
+  RERUN_TRIGGER_MANUAL = 2;
+}
+
+message RerunScope {
+  string scope_id = 1;
+  string plan_id = 2;
+  RerunTrigger trigger = 3;
+  string reason = 4;
+  optional string source_decision_id = 5;
+  repeated string task_ids = 6;
+  repeated string step_ids = 7;
+  repeated string paths = 8;
+  uint64 created_at = 9;
+}
+
+enum RerunSelectionStrategy {
+  RERUN_SELECTION_STRATEGY_UNSPECIFIED = 0;
+  RERUN_SELECTION_STRATEGY_TASK_IDS = 1;
+  RERUN_SELECTION_STRATEGY_STEP_IDS = 2;
+  RERUN_SELECTION_STRATEGY_PATHS = 3;
+}
+
+enum RerunExecutionStatus {
+  RERUN_EXECUTION_STATUS_UNSPECIFIED = 0;
+  RERUN_EXECUTION_STATUS_PENDING = 1;
+  RERUN_EXECUTION_STATUS_SUCCEEDED = 2;
+  RERUN_EXECUTION_STATUS_FAILED = 3;
+  RERUN_EXECUTION_STATUS_PARTIAL = 4;
+}
+
+message RerunExecutionResult {
+  string result_id = 1;
+  string plan_id = 2;
+  string rerun_scope_id = 3;
+  optional string source_decision_id = 4;
+  RerunTrigger trigger = 5;
+  RerunSelectionStrategy matched_strategy = 6;
+  repeated string root_tasks = 7;
+  repeated string selected_tasks = 8;
+  repeated string matched_paths = 9;
+  string reason = 10;
+  RerunExecutionStatus status = 11;
+  repeated string completed_tasks = 12;
+  repeated string failed_tasks = 13;
+  repeated string skipped_tasks = 14;
+  uint64 created_at = 15;
+  uint64 updated_at = 16;
+}
+
+message PrLifecycleState {
+  string state_id = 1;
+  string plan_id = 2;
+  optional uint64 pr_number = 3;
+  optional string pr_url = 4;
+  optional ReviewDecision review_decision = 5;
+  optional RerunScope rerun_scope = 6;
+  optional RerunExecutionResult rerun_result = 7;
+  optional VerificationReceipt verification_receipt = 8;
+  bool merge_ready = 9;
+  bool release_ready = 10;
+  repeated BlockedOutcome blocked_outcomes = 11;
+  uint64 updated_at = 12;
+}
+
 message Task {
   string version = 1;
   string task_id = 2;
+  // Legacy enum role. Prefer role_id for new producers and consumers.
   AgentRole role = 3;
   string goal = 4;
   google.protobuf.Struct inputs = 5;
@@ -132,8 +747,10 @@ message Task {
   RunContext run_context = 8;
   google.protobuf.Struct extensions = 9;
   ExperimentSpec experiment_spec = 10;
-  DeliveryContract delivery_contract = 11;
-  ObjectiveSpec objective_spec = 12;
+  ObjectiveSpec objective_spec = 11;
+  // Canonical open-ended role identifier. This allows built-in and custom
+  // roles without requiring protocol enum changes.
+  string role_id = 12;
 }
 
 message Artifact {
@@ -160,6 +777,68 @@ message Event {
   google.protobuf.Struct extensions = 7;
   Provenance provenance = 8;
   repeated EvalResult eval_results = 9;
+  FailureClass failure_class = 10;
+}
+
+enum RunEventStream {
+  RUN_EVENT_STREAM_UNSPECIFIED = 0;
+  RUN_EVENT_STREAM_EXECUTION = 1;
+  RUN_EVENT_STREAM_RECOVERY = 2;
+  RUN_EVENT_STREAM_REVIEW = 3;
+  RUN_EVENT_STREAM_VERIFICATION = 4;
+  RUN_EVENT_STREAM_LIFECYCLE = 5;
+  RUN_EVENT_STREAM_CUSTOM = 6;
+}
+
+message RunEventRecord {
+  string contract_version = 1;
+  string event_id = 2;
+  string run_id = 3;
+  string plan_id = 4;
+  uint64 sequence = 5;
+  RunEventStream stream = 6;
+  uint64 recorded_at = 7;
+  optional string step_id = 8;
+  optional string task_id = 9;
+  string event_type = 10;
+  string status = 11;
+  optional string message = 12;
+  repeated string artifact_ids = 13;
+}
+
+enum TaskMessageKind {
+  TASK_MESSAGE_KIND_UNSPECIFIED = 0;
+  TASK_MESSAGE_KIND_ARTIFACT_READY = 1;
+  TASK_MESSAGE_KIND_CLARIFICATION_REQUEST = 2;
+  TASK_MESSAGE_KIND_CLARIFICATION_RESPONSE = 3;
+}
+
+message TaskMessage {
+  string version = 1;
+  string message_id = 2;
+  string run_id = 3;
+  string from_task_id = 4;
+  string to_task_id = 5;
+  TaskMessageKind kind = 6;
+  optional string subject = 7;
+  optional string body = 8;
+  repeated string artifact_refs = 9;
+  optional string reply_to = 10;
+  string created_at = 11;
+  bool requires_ack = 12;
+  google.protobuf.Struct extensions = 13;
+  Provenance provenance = 14;
+}
+
+message TaskMessageAck {
+  string version = 1;
+  string message_id = 2;
+  string run_id = 3;
+  string task_id = 4;
+  string acked_at = 5;
+  string status = 6;
+  optional string note = 7;
+  google.protobuf.Struct extensions = 8;
 }
 
 message GateResult {
@@ -169,6 +848,7 @@ message GateResult {
   optional string reason = 4;
   google.protobuf.Struct evidence = 5;
   google.protobuf.Struct extensions = 6;
+  FailureClass failure_class = 7;
 }
 
 message RunOutcome {
@@ -199,3 +879,512 @@ message RunContext {
   repeated string labels = 6;
   google.protobuf.Struct extensions = 7;
 }
+
+// RunnerCapabilities declares the stable machine-facing features a runner can
+// advertise when joining the control plane.
+message RunnerCapabilities {
+  string platform = 1;
+  string runtime = 2;
+  // Legacy enum-based supported roles. Prefer supported_role_ids for new
+  // producers and consumers.
+  repeated AgentRole supported_roles = 3;
+  repeated string supported_task_versions = 4;
+  repeated string labels = 5;
+  bool supports_interactive_pty = 6;
+  bool supports_resume = 7;
+  google.protobuf.Struct extensions = 8;
+  repeated string supported_role_ids = 9;
+  repeated string supported_models = 10;
+  repeated string supported_reasoning_efforts = 11;
+  repeated string supported_runner_capabilities = 12;
+  repeated string supported_providers = 13;
+}
+
+// LeaseRef is the canonical identity for a runner-owned execution lease. The
+// fencing_token must change whenever orchestrator ownership changes.
+message LeaseRef {
+  string lease_id = 1;
+  string fencing_token = 2;
+  string run_id = 3;
+  string plan_id = 4;
+  string step_id = 5;
+  string task_id = 6;
+}
+
+enum LeaseLifecycleState {
+  LEASE_LIFECYCLE_STATE_UNSPECIFIED = 0;
+  LEASE_ISSUED = 1;
+  LEASE_ACTIVE = 2;
+  LEASE_RELEASED = 3;
+  LEASE_EXPIRED = 4;
+  LEASE_CANCELLED = 5;
+  LEASE_REJECTED = 6;
+}
+
+enum RunLifecycleState {
+  RUN_LIFECYCLE_STATE_UNSPECIFIED = 0;
+  RUN_PENDING = 1;
+  RUN_EXECUTING = 2;
+  RUN_PAUSED = 3;
+  RUN_CANCELLING = 4;
+  RUN_CANCELLED = 5;
+  RUN_FAILED = 6;
+  RUN_COMPLETE = 7;
+  RUN_BLOCKED = 8;
+}
+
+enum StepLifecycleState {
+  STEP_LIFECYCLE_STATE_UNSPECIFIED = 0;
+  STEP_PENDING = 1;
+  STEP_READY = 2;
+  STEP_LEASED = 3;
+  STEP_RUNNING = 4;
+  STEP_COMPLETE = 5;
+  STEP_FAILED = 6;
+  STEP_CANCELLED = 7;
+  STEP_BLOCKED = 8;
+}
+
+enum LeaseRejectionReason {
+  LEASE_REJECTION_REASON_UNSPECIFIED = 0;
+  LEASE_REJECTION_STALE_FENCING_TOKEN = 1;
+  LEASE_REJECTION_EXPIRED = 2;
+  LEASE_REJECTION_SESSION_MISMATCH = 3;
+  LEASE_REJECTION_UNKNOWN_LEASE = 4;
+  LEASE_REJECTION_STEP_ALREADY_TERMINAL = 5;
+  LEASE_REJECTION_RUN_NOT_EXECUTABLE = 6;
+  LEASE_REJECTION_DEPENDENCY_BLOCKED = 7;
+  LEASE_REJECTION_LEASE_SUPERSEDED = 8;
+}
+
+enum RecoveryEventKind {
+  RECOVERY_EVENT_KIND_UNSPECIFIED = 0;
+  RECOVERY_EVENT_ORCHESTRATOR_STARTED = 1;
+  RECOVERY_EVENT_STATE_RELOADED = 2;
+  RECOVERY_EVENT_LEASE_RESTORED = 3;
+  RECOVERY_EVENT_LEASE_REJECTED = 4;
+  RECOVERY_EVENT_STEP_REQUEUED = 5;
+  RECOVERY_EVENT_STEP_BLOCKED = 6;
+  RECOVERY_EVENT_RUN_RECOVERED = 7;
+  RECOVERY_EVENT_CANCELLATION_REQUESTED = 8;
+  RECOVERY_EVENT_CANCELLATION_ACKNOWLEDGED = 9;
+}
+
+message FencingToken {
+  string token = 1;
+  uint64 issued_at_ms = 2;
+  string issuer = 3;
+  string scope = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message Lease {
+  string lease_id = 1;
+  string run_id = 2;
+  string plan_id = 3;
+  string step_id = 4;
+  string task_id = 5;
+  string runner_id = 6;
+  string session_id = 7;
+  FencingToken fencing_token = 8;
+  uint64 issued_at_ms = 9;
+  uint64 expires_at_ms = 10;
+  LeaseLifecycleState status = 11;
+  google.protobuf.Struct extensions = 12;
+}
+
+message RecoveryEvent {
+  string event_id = 1;
+  string run_id = 2;
+  string plan_id = 3;
+  optional string step_id = 4;
+  RecoveryEventKind kind = 5;
+  uint64 occurred_at_ms = 6;
+  string actor = 7;
+  google.protobuf.Struct details = 8;
+  string contract_version = 9;
+  optional RunLifecycleState run_state = 10;
+  optional StepLifecycleState step_state = 11;
+  optional LeaseRejectionReason lease_rejection_reason = 12;
+}
+
+message LeaseStatus {
+  LeaseRef lease = 1;
+  string state = 2;
+  uint64 updated_at_ms = 3;
+  optional FailureDetail failure = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message CancellationIntent {
+  LeaseRef lease = 1;
+  string reason = 2;
+  uint64 requested_at_ms = 3;
+  bool force = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message LeaseAssignment {
+  LeaseRef lease = 1;
+  Task task = 2;
+  uint64 issued_at_ms = 3;
+  uint64 lease_ttl_ms = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message RegisterRunnerRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  RunnerCapabilities capabilities = 3;
+  uint32 max_parallel_leases = 4;
+  google.protobuf.Struct extensions = 5;
+  optional AuthContext auth_context = 6;
+}
+
+message RegisterRunnerResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  string session_id = 3;
+  uint64 heartbeat_interval_ms = 4;
+  uint64 lease_poll_interval_ms = 5;
+  google.protobuf.Struct extensions = 6;
+}
+
+message HeartbeatRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  repeated LeaseStatus active_leases = 4;
+  google.protobuf.Struct extensions = 5;
+  optional AuthContext auth_context = 6;
+}
+
+message HeartbeatResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  uint64 next_heartbeat_ms = 3;
+  repeated CancellationIntent cancellations = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message AcquireLeaseRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  uint32 available_slots = 4;
+  repeated string active_lease_ids = 5;
+  google.protobuf.Struct extensions = 6;
+  optional AuthContext auth_context = 7;
+}
+
+message AcquireLeaseResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  LeaseAssignment assignment = 3;
+  uint64 retry_after_ms = 4;
+  repeated CancellationIntent cancellations = 5;
+  google.protobuf.Struct extensions = 6;
+}
+
+message RenewLeaseRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  LeaseRef lease = 4;
+  google.protobuf.Struct extensions = 5;
+  optional AuthContext auth_context = 6;
+}
+
+message RenewLeaseResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  bool accepted = 3;
+  uint64 lease_ttl_ms = 4;
+  repeated CancellationIntent cancellations = 5;
+  optional FailureDetail failure = 6;
+  google.protobuf.Struct extensions = 7;
+}
+
+message ResumeLeaseRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  LeaseRef lease = 4;
+  google.protobuf.Struct extensions = 5;
+  optional AuthContext auth_context = 6;
+}
+
+message ResumeLeaseResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  bool accepted = 3;
+  Lease lease = 4;
+  uint64 expires_at_ms = 5;
+  string current_fencing_token = 6;
+  LeaseRejectionReason reason = 7;
+  string message = 8;
+  google.protobuf.Struct extensions = 9;
+}
+
+message ReportStepStartedRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  LeaseRef lease = 4;
+  string started_at = 5;
+  google.protobuf.Struct extensions = 6;
+  optional AuthContext auth_context = 7;
+}
+
+message ReportStepStartedResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  bool accepted = 3;
+  optional FailureDetail failure = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message ReportStepProgressRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  LeaseRef lease = 4;
+  repeated Event events = 5;
+  repeated Artifact artifacts = 6;
+  google.protobuf.Struct extensions = 7;
+  optional AuthContext auth_context = 8;
+}
+
+message ReportStepProgressResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  bool accepted = 3;
+  repeated CancellationIntent cancellations = 4;
+  optional FailureDetail failure = 5;
+  google.protobuf.Struct extensions = 6;
+}
+
+message ReportStepOutcomeRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  LeaseRef lease = 4;
+  PlanStatus status = 5;
+  repeated Event events = 6;
+  repeated Artifact artifacts = 7;
+  optional RunOutcome run_outcome = 8;
+  optional FailureDetail failure = 9;
+  string finished_at = 10;
+  google.protobuf.Struct extensions = 11;
+  optional AuthContext auth_context = 12;
+}
+
+message ReportStepOutcomeResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  bool accepted = 3;
+  optional FailureDetail failure = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+message AckCancellationRequest {
+  string contract_version = 1;
+  string runner_id = 2;
+  string session_id = 3;
+  LeaseRef lease = 4;
+  string status = 5;
+  optional string message = 6;
+  google.protobuf.Struct extensions = 7;
+  optional AuthContext auth_context = 8;
+}
+
+message AckCancellationResponse {
+  string contract_version = 1;
+  string orchestrator_id = 2;
+  bool accepted = 3;
+  optional FailureDetail failure = 4;
+  google.protobuf.Struct extensions = 5;
+}
+
+enum ControlPlaneRunAction {
+  CONTROL_PLANE_RUN_ACTION_UNSPECIFIED = 0;
+  CONTROL_PLANE_RUN_ACTION_PAUSE = 1;
+  CONTROL_PLANE_RUN_ACTION_RESUME = 2;
+  CONTROL_PLANE_RUN_ACTION_INTERRUPT = 3;
+  CONTROL_PLANE_RUN_ACTION_CANCEL = 4;
+}
+
+message ControlPlaneScope {
+  optional string organization = 1;
+  optional string user = 2;
+  optional string default_project = 3;
+}
+
+message RunOperatorSignals {
+  bool prompt_needed = 1;
+  optional string prompt_summary = 2;
+  bool pause_requested = 3;
+  bool interrupt_requested = 4;
+  bool cancel_requested = 5;
+}
+
+message ControlPlaneRunSummary {
+  string project_key = 1;
+  string run_id = 2;
+  optional string run_dir = 3;
+  optional RunLifecycleState lifecycle_state = 4;
+  string status = 5;
+  optional string updated_label = 6;
+  optional uint64 updated_epoch = 7;
+  optional string meaningful_status = 8;
+  optional double meaningful_score = 9;
+  repeated string meaningful_reasons = 10;
+  optional uint64 total_runs = 11;
+  optional uint64 total_success = 12;
+  optional uint64 total_failed = 13;
+  optional uint64 message_count = 14;
+  optional uint64 unresolved_required_ack_count = 15;
+  bool alert_stale = 16;
+  bool alert_low_score = 17;
+  RunOperatorSignals operator_signals = 18;
+}
+
+message ControlPlaneRunActivityCursor {
+  optional uint64 after_sequence = 1;
+  optional string resume_token = 2;
+}
+
+message ListControlPlaneRunsRequest {
+  string contract_version = 1;
+  ControlPlaneScope scope = 2;
+  optional string project_key = 3;
+  optional uint32 limit = 4;
+  google.protobuf.Struct extensions = 5;
+  optional AuthContext auth_context = 6;
+}
+
+message ListControlPlaneRunsResponse {
+  string contract_version = 1;
+  repeated ControlPlaneRunSummary runs = 2;
+  google.protobuf.Struct extensions = 3;
+}
+
+message GetControlPlaneRunRequest {
+  string contract_version = 1;
+  ControlPlaneScope scope = 2;
+  optional string project_key = 3;
+  string run_id = 4;
+  google.protobuf.Struct extensions = 5;
+  optional AuthContext auth_context = 6;
+}
+
+message GetControlPlaneRunResponse {
+  string contract_version = 1;
+  ControlPlaneRunSummary run = 2;
+  google.protobuf.Struct extensions = 3;
+}
+
+message GetControlPlaneRunActivityPageRequest {
+  string contract_version = 1;
+  ControlPlaneScope scope = 2;
+  optional string project_key = 3;
+  string run_id = 4;
+  optional uint32 limit = 5;
+  ControlPlaneRunActivityCursor cursor = 6;
+  google.protobuf.Struct extensions = 7;
+  optional AuthContext auth_context = 8;
+}
+
+message GetControlPlaneRunActivityPageResponse {
+  string contract_version = 1;
+  repeated RunEventRecord records = 2;
+  ControlPlaneRunActivityCursor next_cursor = 3;
+  google.protobuf.Struct extensions = 4;
+}
+
+message ApplyControlPlaneRunActionRequest {
+  string contract_version = 1;
+  ControlPlaneScope scope = 2;
+  string run_id = 3;
+  ControlPlaneRunAction action = 4;
+  optional string reason = 5;
+  google.protobuf.Struct extensions = 6;
+  optional AuthContext auth_context = 7;
+}
+
+message ApplyControlPlaneRunActionResponse {
+  string contract_version = 1;
+  string run_id = 2;
+  ControlPlaneRunAction action = 3;
+  bool accepted = 4;
+  optional RunLifecycleState lifecycle_state = 5;
+  optional string message = 6;
+  google.protobuf.Struct extensions = 7;
+}
+
+message ApplyControlPlaneReviewDispositionRequest {
+  string contract_version = 1;
+  ControlPlaneScope scope = 2;
+  string project_key = 3;
+  optional string plan_id = 4;
+  string actor = 5;
+  ReviewDisposition decision = 6;
+  string reason = 7;
+  google.protobuf.Struct extensions = 8;
+  optional AuthContext auth_context = 9;
+}
+
+message ApplyControlPlaneReviewDispositionResponse {
+  string contract_version = 1;
+  string project_key = 2;
+  optional string plan_id = 3;
+  bool accepted = 4;
+  optional ReviewDecision review_decision = 5;
+  optional PrLifecycleState pr_lifecycle_state = 6;
+  optional string message = 7;
+  google.protobuf.Struct extensions = 8;
+}
+
+message EnsureControlPlaneWorkerRequest {
+  string contract_version = 1;
+  ControlPlaneScope scope = 2;
+  string project_key = 3;
+  google.protobuf.Struct extensions = 4;
+  optional AuthContext auth_context = 5;
+}
+
+message EnsureControlPlaneWorkerResponse {
+  string contract_version = 1;
+  string project_key = 2;
+  bool accepted = 3;
+  optional string worker_id = 4;
+  optional string message = 5;
+  google.protobuf.Struct extensions = 6;
+}
+
+// RunnerControlService is the canonical machine-to-machine control-plane
+// contract. It is transport-oriented and intentionally protobuf-only; JSON
+// schema support in this repository remains limited to portable object payloads.
+service RunnerControlService {
+  rpc RegisterRunner(RegisterRunnerRequest) returns (RegisterRunnerResponse);
+  rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);
+  rpc AcquireLease(AcquireLeaseRequest) returns (AcquireLeaseResponse);
+  rpc RenewLease(RenewLeaseRequest) returns (RenewLeaseResponse);
+  rpc ResumeLease(ResumeLeaseRequest) returns (ResumeLeaseResponse);
+  rpc ReportStepStarted(ReportStepStartedRequest) returns (ReportStepStartedResponse);
+  rpc ReportStepProgress(ReportStepProgressRequest) returns (ReportStepProgressResponse);
+  rpc ReportStepOutcome(ReportStepOutcomeRequest) returns (ReportStepOutcomeResponse);
+  rpc AckCancellation(AckCancellationRequest) returns (AckCancellationResponse);
+}
+
+// ClientControlService is the canonical client-facing control-plane RPC
+// contract. It carries scoped run summaries, activity pages, and operator
+// control actions without encoding local workspace compatibility concerns.
+service ClientControlService {
+  rpc ListRuns(ListControlPlaneRunsRequest) returns (ListControlPlaneRunsResponse);
+  rpc GetRun(GetControlPlaneRunRequest) returns (GetControlPlaneRunResponse);
+  rpc GetRunActivityPage(GetControlPlaneRunActivityPageRequest) returns (GetControlPlaneRunActivityPageResponse);
+  rpc ApplyRunAction(ApplyControlPlaneRunActionRequest) returns (ApplyControlPlaneRunActionResponse);
+  rpc ApplyReviewDisposition(ApplyControlPlaneReviewDispositionRequest) returns (ApplyControlPlaneReviewDispositionResponse);
+  rpc EnsureWorker(EnsureControlPlaneWorkerRequest) returns (EnsureControlPlaneWorkerResponse);
+}