openclaw/reporting-governance-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

spec: add reporting governance event model

Browse Source
This commit is contained in:
Eve
2026-05-07 15:55:53 +08:00
parent 299ded3cdf
commit 6921217ca3
3 changed files with 1243 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
schemas/reporting-governance/event-envelope.schema.json Normal file
View File

@@ -0,0 +1,169 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://cowbay.org/schemas/reporting-governance/event-envelope.schema.json",
"title": "Reporting Governance Event Envelope",
"description": "Canonical top-level envelope for reporting-governance plugin events.",
"type": "object",
"additionalProperties": false,
"required": [
"event_id",
"event_type",
"runtime",
"adapter_version",
"agent_id",
"task_id",
"correlation_id",
"timestamp",
"payload",
"evidence_refs",
"operator_context"
],
"properties": {
"event_id": {
"type": "string",
"minLength": 1,
"description": "Unique event identifier."
},
"event_type": {
"type": "string",
"enum": [
"task_started",
"task_checkpoint_due",
"task_checkpoint_sent",
"task_status_changed",
"task_claimed_complete",
"task_evidence_attached",
"subagent_spawned",
"subagent_spawn_failed",
"subagent_completed",
"subagent_result_forwarded",
"subagent_result_not_forwarded",
"silence_timeout",
"watchdog_fired",
"operator_review_requested",
"report_anchor_missing",
"forced_operator_update"
],
"description": "Canonical reporting-governance event type."
},
"runtime": {
"type": "string",
"minLength": 1
},
"adapter_version": {
"type": "string",
"minLength": 1
},
"agent_id": {
"type": "string",
"minLength": 1
},
"task_id": {
"type": "string",
"minLength": 1
},
"correlation_id": {
"type": "string",
"minLength": 1
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"payload": {
"type": "object",
"description": "Event-specific payload validated by the event catalog schema."
},
"evidence_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/evidenceRef"
}
},
"operator_context": {
"$ref": "#/$defs/operatorContext"
}
},
"$defs": {
"evidenceRef": {
"type": "object",
"additionalProperties": true,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"type": "string",
"minLength": 1
},
"ref": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string"
},
"sha256": {
"type": "string"
},
"mime_type": {
"type": "string"
}
}
},
"reportAnchor": {
"type": "object",
"additionalProperties": true,
"required": [
"present"
],
"properties": {
"present": {
"type": "boolean"
},
"anchor_id": {
"type": "string"
},
"anchor_kind": {
"type": "string"
}
}
},
"operatorContext": {
"type": "object",
"additionalProperties": true,
"required": [
"channel",
"report_anchor",
"reporting_mode",
"silent_task"
],
"properties": {
"channel": {
"type": "string",
"minLength": 1
},
"operator_id": {
"type": "string"
},
"report_anchor": {
"$ref": "#/$defs/reportAnchor"
},
"reporting_mode": {
"type": "string",
"minLength": 1
},
"silent_task": {
"type": "boolean"
},
"checkpoint_policy_id": {
"type": "string"
},
"watchdog_policy_id": {
"type": "string"
}
}
}
}
}

453
schemas/reporting-governance/events.schema.json Normal file
View File

@@ -0,0 +1,453 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://cowbay.org/schemas/reporting-governance/events.schema.json",
"title": "Reporting Governance Events",
"description": "Validation schema for canonical reporting-governance events, including envelope and event-specific payload rules.",
"allOf": [
{
"$ref": "./event-envelope.schema.json"
},
{
"oneOf": [
{
"$ref": "#/$defs/taskStartedEvent"
},
{
"$ref": "#/$defs/taskCheckpointDueEvent"
},
{
"$ref": "#/$defs/taskCheckpointSentEvent"
},
{
"$ref": "#/$defs/taskStatusChangedEvent"
},
{
"$ref": "#/$defs/taskClaimedCompleteEvent"
},
{
"$ref": "#/$defs/taskEvidenceAttachedEvent"
},
{
"$ref": "#/$defs/subagentSpawnedEvent"
},
{
"$ref": "#/$defs/subagentSpawnFailedEvent"
},
{
"$ref": "#/$defs/subagentCompletedEvent"
},
{
"$ref": "#/$defs/subagentResultForwardedEvent"
},
{
"$ref": "#/$defs/subagentResultNotForwardedEvent"
},
{
"$ref": "#/$defs/silenceTimeoutEvent"
},
{
"$ref": "#/$defs/watchdogFiredEvent"
},
{
"$ref": "#/$defs/operatorReviewRequestedEvent"
},
{
"$ref": "#/$defs/reportAnchorMissingEvent"
},
{
"$ref": "#/$defs/forcedOperatorUpdateEvent"
}
]
}
],
"$defs": {
"nonEmptyString": {
"type": "string",
"minLength": 1
},
"positiveInteger": {
"type": "integer",
"minimum": 1
},
"taskStartedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"task_kind",
"started_by",
"initial_status",
"silent_task",
"report_required"
],
"properties": {
"task_kind": { "$ref": "#/$defs/nonEmptyString" },
"started_by": { "$ref": "#/$defs/nonEmptyString" },
"initial_status": { "$ref": "#/$defs/nonEmptyString" },
"silent_task": { "type": "boolean" },
"report_required": { "type": "boolean" },
"plan_ref": { "type": "string" },
"checkpoint_due_at": { "type": "string", "format": "date-time" },
"owner_agent_id": { "type": "string" }
}
},
"taskCheckpointDuePayload": {
"type": "object",
"additionalProperties": true,
"required": [
"checkpoint_type",
"due_at",
"expected_report_type"
],
"properties": {
"checkpoint_type": { "$ref": "#/$defs/nonEmptyString" },
"due_at": { "type": "string", "format": "date-time" },
"expected_report_type": { "$ref": "#/$defs/nonEmptyString" },
"grace_period_ms": { "type": "integer", "minimum": 0 },
"policy_id": { "type": "string" }
}
},
"taskCheckpointSentPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"checkpoint_type",
"sent_at",
"report_type"
],
"properties": {
"checkpoint_type": { "$ref": "#/$defs/nonEmptyString" },
"sent_at": { "type": "string", "format": "date-time" },
"report_type": { "$ref": "#/$defs/nonEmptyString" },
"anchor_id": { "type": "string" },
"message_ref": { "type": "string" },
"lateness_ms": { "type": "integer", "minimum": 0 }
}
},
"taskStatusChangedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"from_status",
"to_status",
"reason"
],
"properties": {
"from_status": { "$ref": "#/$defs/nonEmptyString" },
"to_status": { "$ref": "#/$defs/nonEmptyString" },
"reason": { "$ref": "#/$defs/nonEmptyString" },
"status_source": { "type": "string" },
"blocked": { "type": "boolean" },
"gate_id": { "type": "string" }
}
},
"taskClaimedCompletePayload": {
"type": "object",
"additionalProperties": true,
"required": [
"claimed_status"
],
"properties": {
"claimed_status": { "$ref": "#/$defs/nonEmptyString" },
"verification_state": { "type": "string" },
"claim_basis": { "type": "string" },
"pending_review": { "type": "boolean" }
}
},
"taskEvidenceAttachedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"evidence_count",
"evidence_role"
],
"properties": {
"evidence_count": { "$ref": "#/$defs/positiveInteger" },
"evidence_role": { "$ref": "#/$defs/nonEmptyString" }
}
},
"operatorReviewRequestedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"review_reason",
"review_scope"
],
"properties": {
"review_reason": { "$ref": "#/$defs/nonEmptyString" },
"review_scope": { "$ref": "#/$defs/nonEmptyString" },
"requested_status": { "type": "string" },
"deadline": { "type": "string", "format": "date-time" }
}
},
"subagentSpawnedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"subagent_id",
"subagent_label",
"dispatch_status",
"report_anchor_required",
"report_anchor_present"
],
"properties": {
"subagent_id": { "$ref": "#/$defs/nonEmptyString" },
"subagent_label": { "$ref": "#/$defs/nonEmptyString" },
"dispatch_status": { "$ref": "#/$defs/nonEmptyString" },
"report_anchor_required": { "type": "boolean" },
"report_anchor_present": { "type": "boolean" },
"spawn_session_id": { "type": "string" },
"parent_agent_id": { "type": "string" },
"task_summary": { "type": "string" },
"worktree": { "type": "string" }
}
},
"subagentSpawnFailedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"failure_reason",
"failure_stage",
"immediate_report_required"
],
"properties": {
"failure_reason": { "$ref": "#/$defs/nonEmptyString" },
"failure_stage": { "$ref": "#/$defs/nonEmptyString" },
"immediate_report_required": { "type": "boolean" },
"attempted_subagent_label": { "type": "string" },
"error_code": { "type": "string" },
"retryable": { "type": "boolean" }
}
},
"subagentCompletedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"subagent_id",
"completion_state",
"result_available"
],
"properties": {
"subagent_id": { "$ref": "#/$defs/nonEmptyString" },
"completion_state": { "$ref": "#/$defs/nonEmptyString" },
"result_available": { "type": "boolean" },
"result_ref": { "type": "string" },
"completed_at": { "type": "string", "format": "date-time" },
"exit_reason": { "type": "string" }
}
},
"subagentResultForwardedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"subagent_id",
"forwarded_at",
"forward_target"
],
"properties": {
"subagent_id": { "$ref": "#/$defs/nonEmptyString" },
"forwarded_at": { "type": "string", "format": "date-time" },
"forward_target": { "$ref": "#/$defs/nonEmptyString" },
"source_result_ref": { "type": "string" },
"forward_message_ref": { "type": "string" },
"integrity_status": { "type": "string" }
}
},
"subagentResultNotForwardedPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"subagent_id",
"detected_at",
"reason",
"result_ref"
],
"properties": {
"subagent_id": { "$ref": "#/$defs/nonEmptyString" },
"detected_at": { "type": "string", "format": "date-time" },
"reason": { "$ref": "#/$defs/nonEmptyString" },
"result_ref": { "$ref": "#/$defs/nonEmptyString" },
"forward_deadline": { "type": "string", "format": "date-time" },
"watchdog_window_ms": { "$ref": "#/$defs/positiveInteger" },
"operator_notified": { "type": "boolean" }
}
},
"silenceTimeoutPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"duration_ms",
"expected_report_type"
],
"properties": {
"duration_ms": { "$ref": "#/$defs/positiveInteger" },
"expected_report_type": { "$ref": "#/$defs/nonEmptyString" },
"last_report_at": { "type": "string", "format": "date-time" },
"timeout_policy_id": { "type": "string" },
"blocking_action": { "type": "string" }
}
},
"watchdogFiredPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"watchdog_type",
"trigger_reason"
],
"properties": {
"watchdog_type": { "$ref": "#/$defs/nonEmptyString" },
"trigger_reason": { "$ref": "#/$defs/nonEmptyString" },
"triggered_at": { "type": "string", "format": "date-time" },
"policy_id": { "type": "string" },
"severity": { "type": "string" }
}
},
"reportAnchorMissingPayload": {
"type": "object",
"additionalProperties": true,
"required": [
"required_for",
"gate_action"
],
"properties": {
"required_for": { "$ref": "#/$defs/nonEmptyString" },
"gate_action": { "$ref": "#/$defs/nonEmptyString" },
"missing_anchor_kind": { "type": "string" },
"attempted_action": { "type": "string" },
"blocking": { "type": "boolean" }
}
},
"forcedOperatorUpdatePayload": {
"type": "object",
"additionalProperties": true,
"required": [
"reason",
"update_channel",
"trigger_event_type"
],
"properties": {
"reason": { "$ref": "#/$defs/nonEmptyString" },
"update_channel": { "$ref": "#/$defs/nonEmptyString" },
"trigger_event_type": { "$ref": "#/$defs/nonEmptyString" },
"update_ref": { "type": "string" },
"severity": { "type": "string" },
"deadline_breached": { "type": "boolean" }
}
},
"taskStartedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "task_started" },
"payload": { "$ref": "#/$defs/taskStartedPayload" }
}
},
"taskCheckpointDueEvent": {
"type": "object",
"properties": {
"event_type": { "const": "task_checkpoint_due" },
"payload": { "$ref": "#/$defs/taskCheckpointDuePayload" }
}
},
"taskCheckpointSentEvent": {
"type": "object",
"properties": {
"event_type": { "const": "task_checkpoint_sent" },
"payload": { "$ref": "#/$defs/taskCheckpointSentPayload" }
}
},
"taskStatusChangedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "task_status_changed" },
"payload": { "$ref": "#/$defs/taskStatusChangedPayload" }
}
},
"taskClaimedCompleteEvent": {
"type": "object",
"properties": {
"event_type": { "const": "task_claimed_complete" },
"payload": { "$ref": "#/$defs/taskClaimedCompletePayload" }
}
},
"taskEvidenceAttachedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "task_evidence_attached" },
"payload": { "$ref": "#/$defs/taskEvidenceAttachedPayload" },
"evidence_refs": {
"type": "array",
"minItems": 1
}
}
},
"subagentSpawnedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "subagent_spawned" },
"payload": { "$ref": "#/$defs/subagentSpawnedPayload" }
}
},
"subagentSpawnFailedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "subagent_spawn_failed" },
"payload": { "$ref": "#/$defs/subagentSpawnFailedPayload" }
}
},
"subagentCompletedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "subagent_completed" },
"payload": { "$ref": "#/$defs/subagentCompletedPayload" }
}
},
"subagentResultForwardedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "subagent_result_forwarded" },
"payload": { "$ref": "#/$defs/subagentResultForwardedPayload" }
}
},
"subagentResultNotForwardedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "subagent_result_not_forwarded" },
"payload": { "$ref": "#/$defs/subagentResultNotForwardedPayload" }
}
},
"silenceTimeoutEvent": {
"type": "object",
"properties": {
"event_type": { "const": "silence_timeout" },
"payload": { "$ref": "#/$defs/silenceTimeoutPayload" }
}
},
"watchdogFiredEvent": {
"type": "object",
"properties": {
"event_type": { "const": "watchdog_fired" },
"payload": { "$ref": "#/$defs/watchdogFiredPayload" }
}
},
"operatorReviewRequestedEvent": {
"type": "object",
"properties": {
"event_type": { "const": "operator_review_requested" },
"payload": { "$ref": "#/$defs/operatorReviewRequestedPayload" }
}
},
"reportAnchorMissingEvent": {
"type": "object",
"properties": {
"event_type": { "const": "report_anchor_missing" },
"payload": { "$ref": "#/$defs/reportAnchorMissingPayload" }
}
},
"forcedOperatorUpdateEvent": {
"type": "object",
"properties": {
"event_type": { "const": "forced_operator_update" },
"payload": { "$ref": "#/$defs/forcedOperatorUpdatePayload" }
}
}
}
}