#Event Types

Every action in the rebuno kernel produces events that form an immutable audit trail. Events are persisted in the event store and can be queried via the API or the rebuno CLI.

#Event Structure

Every event has the following fields:

#Event Categories

Events are classified into three categories:

• State-mutating: Change the state of an execution or step. These are the primary events that drive the state machine.
• Decisional: Record policy decisions (accept/deny) on intents.
• Informational: Record notable occurrences that do not change state.

#Persisted vs. Transient Events

Persisted events are stored in the event store and can be queried via GET /v0/executions/{id}/events. All event types listed below are persisted.

Transient SSE push events are sent over Server-Sent Events connections but are not stored in the event store:

These transient events are delivery mechanisms. The underlying state changes are captured by persisted events (e.g., execution.started, step.completed).

#Execution Events

#execution.created

Emitted when a new execution is created via POST /v0/executions.

{
  "agent_id": "researcher",
  "input": {"query": "what is event sourcing?"},
  "labels": {"env": "dev"}
}

#execution.started

Emitted when the kernel assigns an execution to an agent via SSE.

{
  "session_id": "sess-abc123",
  "consumer_id": "researcher-x8f2k"
}

#execution.blocked

Emitted when an execution enters the blocked state, waiting for a tool result or signal.

{
  "reason": "tool",
  "ref": "step-abc123"
}

#execution.resumed

Emitted when a blocked execution returns to running state.

{
  "reason": "step completed"
}

#execution.completed

Emitted when an agent submits a complete intent.

{
  "output": {"answer": "Event sourcing is..."}
}

#execution.failed

Emitted when an execution fails (agent submits fail intent, timeout, etc.).

{
  "error": "Tool execution failed: web.search returned 500"
}

#execution.reset

Emitted when the kernel resets an execution back to pending (e.g., after agent disconnect or recovery).

{
  "reason": "agent_disconnect",
  "from_status": "running"
}

#execution.cancelled

Emitted when an execution is cancelled via POST /v0/executions/{id}/cancel.

{
  "reason": "user requested cancellation"
}

#Intent Events

#intent.accepted

Emitted when the kernel accepts an intent (policy allows it or it is a lifecycle intent).

{
  "intent_type": "invoke_tool",
  "details": {"tool_id": "web.search", "step_id": "step-abc123"}
}

#intent.denied

Emitted when the kernel denies an intent due to policy.

{
  "intent_type": "invoke_tool",
  "tool_id": "shell.exec",
  "arguments": {"command": "rm -rf /"},
  "idempotency_key": "exec-123:shell.exec:a1b2c3d4",
  "reason": "Shell commands denied by default",
  "rule_id": "deny-shell"
}

#Step Events

#step.created

Emitted when a tool invocation intent is accepted and a step is created.

{
  "tool_id": "web.search",
  "tool_version": 1,
  "arguments": {"query": "event sourcing"},
  "max_attempts": 3,
  "attempt": 1
}

#step.dispatched

Emitted when the kernel dispatches a step to a runner for remote execution.

{
  "runner_id": "my-runner",
  "job_id": "job-xyz789",
  "deadline": "2025-01-15T10:30:00Z"
}

#step.started

Emitted when a runner reports that it has begun executing the step.

{
  "runner_id": "my-runner"
}

#step.completed

Emitted when a step finishes successfully.

{
  "result": {"results": [{"title": "Event Sourcing", "url": "..."}]}
}

#step.failed

Emitted when a step fails.

{
  "error": "web.search returned HTTP 500",
  "retryable": true
}

#step.timed_out

Emitted when a step exceeds its deadline. The payload is empty.

{}

#step.retried

Emitted when a failed step is retried.

{
  "next_attempt": 2
}

#step.cancelled

Emitted when a step is cancelled (e.g., when the parent execution is cancelled).

{
  "reason": "execution cancelled"
}

#step.approval_required

Emitted when a step requires human approval before it can proceed. This is an informational event.

{
  "tool_id": "deploy.production",
  "arguments": {"service": "api", "version": "v2.1.0"},
  "remote": false,
  "reason": "Production deployments require approval"
}

#Other Events

#signal.received

Emitted when a signal is delivered to a blocked execution via POST /v0/executions/{id}/signal.

{
  "signal_type": "approval",
  "payload": {"approved": true, "reviewer": "alice"}
}

#agent.timeout

Emitted when an agent's session times out due to connectivity loss.

{
  "session_id": "sess-abc123"
}