Skip to content
Kindgi

Event

@kindgi/specs/event.schema.json, schema version 1.0.0.

The causal glue between runs. Emitted by kernel, memory, tools, agents, supervisor, HITL. Consumed by subscriptions to trigger new runs or resume in-flight waits. Every event has an ID for idempotent delivery; every subscription is policy-scoped. Delivery is at-least-once with idempotent handlers.

  • id (string, required): Unique event ID. Enables dedup on the consumer side (at-least-once delivery).
  • type (string, required): Dotted event type (e.g. 'run.started', 'run.completed', 'guardrail.violated', 'fact.written', 'entity.deleted', 'tool.invoked', 'fix.proposed', 'approval.requested'). Convention: '<subject>.<past-tense-verb>'.
  • tenantId (string, required): Tenant that owns this event. Cross-tenant delivery is denied by policy.
  • timestamp (string (date-time), required)
  • actor (string): Who emitted this event (agent id, tool id, subsystem name, user id).
  • subject (object): The primary object the event is about.
    • kind (string): Object kind (e.g. 'run', 'agent', 'fact', 'entity', 'tool', 'guardrail').
    • id (string)
  • causedBy (array of string): Zero or more IDs (event IDs or provenance node IDs) that caused this event. Extends the causal DAG across the reactive boundary — an agent that runs because of an event has provenance edges back through the event to its emitter.
  • scope (map of any): Optional additional scoping (project, thread, session). Interpreted by subscriptions.
  • payload (object): Event-type-specific payload. Consumers must tolerate unknown fields for forward compatibility.
  • attributes (map of any): Non-structural annotations useful for filter predicates (e.g. severity, kind hints, feature flags).