atlas-iac/services/hermes/contracts/hux/event.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hermes.bstein.dev/contracts/hux/v1/event.schema.json",
  "title": "HUX activity event",
  "description": "One entry in the per-conversation activity stream (HUX-01). seq is strictly monotonic per conversation; consumers resume with after_seq. Every other HUX record that changes state emits exactly one event.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "id",
    "seq",
    "ts",
    "conversation_id",
    "kind",
    "summary",
    "provenance",
    "sensitivity",
    "redaction",
    "turn",
    "identity"
  ],
  "properties": {
    "schema": {
      "const": "hux.event.v1"
    },
    "id": {
      "$ref": "common.schema.json#/$defs/id"
    },
    "seq": {
      "type": "integer",
      "minimum": 0
    },
    "ts": {
      "$ref": "common.schema.json#/$defs/timestamp"
    },
    "conversation_id": {
      "$ref": "common.schema.json#/$defs/id"
    },
    "run_id": {
      "type": "string",
      "maxLength": 120
    },
    "parent_event_id": {
      "$ref": "common.schema.json#/$defs/id"
    },
    "correlation_id": {
      "type": "string",
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "enum": [
        "message.user",
        "message.assistant",
        "decision.route",
        "decision.plan",
        "tool.call",
        "tool.result",
        "approval.requested",
        "approval.resolved",
        "memory.proposed",
        "memory.committed",
        "memory.forgotten",
        "artifact.created",
        "artifact.version",
        "artifact.promoted",
        "citation.attached",
        "mode.changed",
        "run.started",
        "run.cancelled",
        "run.completed",
        "run.failed",
        "privacy.notice",
        "suggestion.shown",
        "suggestion.dismissed",
        "release.transition",
        "delegation.started",
        "delegation.completed",
        "delegation.failed",
        "memory.suppressed",
        "memory.retrieval_removed",
        "budget.exhausted",
        "side_effect.blocked",
        "side_effect.released"
      ]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 280
    },
    "detail": {
      "type": "object",
      "description": "Kind-specific payload restricted to the allowlisted keys for that kind. Raw tool arguments, logs, credentials and tokens are never stored here; the redaction pipeline drops unknown keys and scrubs secret patterns before the event is written."
    },
    "evidence": {
      "type": "array",
      "maxItems": 64,
      "items": {
        "$ref": "common.schema.json#/$defs/evidence_ref"
      }
    },
    "provenance": {
      "$ref": "common.schema.json#/$defs/provenance"
    },
    "sensitivity": {
      "$ref": "common.schema.json#/$defs/sensitivity"
    },
    "redaction": {
      "$ref": "common.schema.json#/$defs/redaction"
    },
    "turn": {
      "type": "integer",
      "description": "User-visible turn number within the conversation; several events share a turn.",
      "minimum": 0
    },
    "idempotency_key": {
      "$ref": "common.schema.json#/$defs/idempotency_key"
    },
    "identity": {
      "$ref": "common.schema.json#/$defs/identity"
    }
  }
}