{
  "$id": "https://glide.co/schemas/agent-banking/draft/agent-activity-event.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AgentActivityEvent",
  "description": "Trust Console event taxonomy. Producers (router, policy-engine, MCP server, kill-switch) emit one of these per agent action; consumers (Trust Console UI, audit:stream subscribers, ops dashboards) tail them. Forward-compatible: the `eventKind` enum may grow additively in minor releases. Backward-compatible: the original placeholder shape `{eventType, timestamp, agentId}` remains valid — `eventType` is retained alongside the new `eventKind`.",
  "channel": "v1",
  "examples": [
    {
      "eventType": "tool_call",
      "eventKind": "tool_call",
      "eventId": "11111111-1111-4111-8111-111111111111",
      "timestamp": "2026-04-25T00:00:00.000Z",
      "agentId": "22222222-2222-4222-8222-222222222222",
      "principalId": "33333333-3333-4333-8333-333333333333",
      "vaultId": "44444444-4444-4444-8444-444444444444",
      "summary": "Initiated $250 USDC payment via payments.initiate",
      "extra": {}
    }
  ],
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "schemaVersion": {
        "type": "string",
        "const": "v1",
        "description": "Schema major version. Pinned to 'v1'. Optional at draft for backward compat; consumers SHOULD treat absence as v1 and SHOULD refuse events with a non-'v1' value."
      },
      "eventType": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64,
        "description": "Free-text event-kind label retained for backward compat with the original /draft/ placeholder. Producers SHOULD also set `eventKind` to a closed-enum value; if both are present they MUST match. New code SHOULD prefer `eventKind`."
      },
      "eventKind": {
        "$ref": "_types.json#/$defs/agentActivityEventKind",
        "description": "Closed enum of event kinds. See _types.json#/$defs/agentActivityEventKind for the canonical vocabulary; new values require an additive schema migration. Optional at v1 to keep backward compat with the bare-`eventType` shape."
      },
      "eventId": {
        "$ref": "_types.json#/$defs/uuidV4",
        "description": "Unique identifier for this event row. Consumers de-duplicate on this; producers MUST NOT reuse an eventId across emissions. Optional at v1 (older streams used DB row id); new producers SHOULD always set it."
      },
      "timestamp": {
        "$ref": "_types.json#/$defs/isoDateTimeUtc",
        "description": "When the event occurred (UTC instant). Server-stamped at producer side; never trust a clock value supplied by an upstream agent runtime."
      },
      "agentId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "description": "agent_principal_id — the synthetic principal representing the agent acting on behalf of a human. UUIDv4 in production; the looser string type at v1 keeps backward compat with placeholder draft data and operator-emitted events."
      },
      "principalId": {
        "anyOf": [{ "$ref": "_types.json#/$defs/uuidV4" }, { "type": "null" }],
        "description": "Human principal whose vault is being acted on. Combined with `vaultId` defines tenant isolation per RFC 8707 audience binding. Null for system-emitted events (kill-switch, scheduled jobs)."
      },
      "vaultId": {
        "anyOf": [{ "$ref": "_types.json#/$defs/uuidV4" }, { "type": "null" }],
        "description": "Vault the action targets. Together with `principalId` forms the audience binding. Null for system-emitted events not tied to a specific vault."
      },
      "grantId": {
        "anyOf": [{ "$ref": "_types.json#/$defs/uuidV4" }, { "type": "null" }],
        "description": "JTI of the grant that authorized this action. Null for events not tied to a specific grant (e.g. operator-initiated kill-switch)."
      },
      "toolCallId": {
        "anyOf": [{ "$ref": "_types.json#/$defs/uuidV4" }, { "type": "null" }],
        "description": "ID of the MCP tool call this event describes. Null for non-tool-call events (e.g. consent_granted)."
      },
      "summary": {
        "type": "string",
        "description": "Human-readable one-line summary suitable for a list row in the Trust Console. Plain text, no markdown, no PII unless the principal already has access to it.",
        "minLength": 1,
        "maxLength": 280
      },
      "extra": {
        "type": "object",
        "description": "Open-ended bag for kind-specific fields (risk_verdict reason text, anomaly score, etc.). Producers MUST keep this <4kB; consumers MUST treat unknown keys as opaque. Exists to allow event-shape evolution without bumping schemaVersion.",
        "additionalProperties": true,
        "default": {}
      }
    },
    "required": ["eventType", "timestamp", "agentId"],
    "additionalProperties": false
  }
}