> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> The typed events a run emits, the journal they are chained into, the --json stream, and OTLP export.

An executing workflow emits a stream of typed **events**: a run starting, a
task scheduled, started, completed or failed, a permit checked, a cost
incurred. Every event is hash-chained into the run's journal under
`.nika/traces/`, the record `nika trace verify` checks. The same events reach
you three ways:

| Surface | What you get |
| - | - |
| `nika run file.nika --json` | one JSON object per event on stdout, ending with a `run_settled` frame |
| The run's journal (`.nika/traces/<run>.ndjson`) | every event, hash-chained; a signed run ends with `run_sealed` |
| The TypeScript SDK (`run.events()`) | a normalized lifecycle vocabulary (`run.started`, `task.completed`…), with the engine frame on `event.raw` ([SDK events](https://docs.nika.sh/sdk/runtime/events.md)) |
| `nika trace export <trace>` | the recorded journal as OpenTelemetry spans (OTLP/JSON lines) |

Nothing in the journal can be edited, reordered or dropped from the middle
without breaking its chain. Events describe what happened; the
[result](https://docs.nika.sh/sdk/runtime/results.md) of a run, and its settlement, remain the source
of truth for how it ended.

## The event shape

Each line of `nika run --json` and of the journal is one event. A real
`task_completed` line from a `mock/echo` run on `nika 0.123.0`, abridged:

```json theme={"system"}
{
  "id": { "uuid": "01a16da4-ef29-708e-bd5c-ef46b9bf92bc" },
  "timestamp": 1792840888105000000,
  "kind": "task_completed",
  "run": null,
  "execution": { "uuid": "01a16da4-ef10-75cb-97fa-e0bcc8945d3c" },
  "correlation": null,
  "chain": "df29062d313b712b51bb43acceb3ef3f8d1b6d5454c6c3d390e0e72bf294374e",
  "fields": [
    { "key": "task", "value": "greeting" },
    { "key": "duration_ms", "value": 2 },
    { "key": "tokens_in", "value": 6 },
    { "key": "tokens_out", "value": 8 },
    { "key": "model", "value": "mock/echo" },
    { "key": "provider", "value": "mock" },
    { "key": "cost_unpriced", "value": "mock_provider" },
    { "key": "output", "value": "\"mock(echo) · Say hello from the Nika SDK.\"" }
  ]
}
```

| Key | Meaning |
| - | - |
| `id` | the event's UUIDv7 |
| `timestamp` | nanoseconds since the Unix epoch |
| `kind` | the event kind, in snake\_case (below) |
| `execution` | the engine's id for this execution |
| `chain` | the hash that links this event to the previous one |
| `fields` | the kind-specific facts, as key/value pairs |

The type is `nika_event::Event`, in the engine's
[`nika-event` crate](https://github.com/supernovae-st/nika/tree/v0.123.0/crates/nika-event).
`nika run --json` ends with a `run_settled` frame that is not a journal event:
it carries the run's `status`, `cause`, `tasks`, `spend`, `outputs` and
`receipt` together.

## Event kinds

Engine 0.124.4 emits 35 kinds. Most runs only produce the first two groups.

| Group | Kinds |
| - | - |
| Workflow | `workflow_started` · `workflow_completed` · `workflow_failed` · `workflow_cancelled` · `workflow_paused` |
| Task | `task_scheduled` · `task_started` · `task_completed` · `task_items` · `task_failed` · `task_skipped` · `task_retrying` · `task_recovered` · `task_cancelled` · `task_cache_hit` |
| Verbs, cost and permits | `verb_invoked` · `tool_invoked` · `checkpoint_written` · `cost_incurred` · `infer_chunk` · `permit_checked` |
| Agent | `agent_tools_selected` · `agent_nudge` · `agent_stalled` · `agent_compose_checked` · `agent_budget_checkpoint` · `agent_image_observed` |
| Seal, approval and taint | `run_sealed` · `declassify` · `approval_decided` |
| Memory | `memory_entry_rejected` · `memory_rejections_summary` |
| Notify and quarantine | `notify_delivered` · `notify_failed` · `quarantine_recorded` |

A few that explain themselves in practice:

* `task_failed` carries the typed error (`code`, message, whether it is
  transient), the shape `on_error:` routes on. A turn an agent application
  reports as failed on a [harness seat](https://docs.nika.sh/guides/harness-access.md) lands here,
  as `NIKA-1804` (transient) or `NIKA-1805`, never as a `task_completed`
  whose output is the error text.
* `task_cache_hit` marks a task a `--resume` run skipped because a journaled
  success matched it.
* `permit_checked` records a boundary decision the engine made at run time.
  On a harness seat, one frame per permission the application asked names
  its gate and the decision; a Codex command that asks to leave its sandbox
  (`sandbox · command`) is always `escalate`, so the run pauses for you
  whatever `permits.exec` grants. The keyless `provider: system` voice
  journals its synthesizer start on the `builtin` plane.
* `agent_image_observed` records each image a harness seat sent: the digest
  and size of the received bytes, the path the application reported (never
  opened) and, under `images: { save: }`, the `saved_path` Nika wrote.
* `workflow_paused` records a human gate holding the run; `approval_decided`
  records the answer that resumed it.
* `run_sealed` is the last line of a signed journal: the signature over the
  chain head.

The kind set grows additively: tolerate kinds you do not know.

## Read the stream

```bash theme={"system"}
nika run workflow.nika --json               # NDJSON on stdout
nika run workflow.nika --json > run.ndjson  # keep a copy
nika trace show                             # the latest run's final card
nika trace export .nika/traces/<run>.ndjson # OTLP/JSON lines next to the trace
```

`nika trace export` writes `<run>.otlp.jsonl` beside the journal: one span
per task, ready for any OTLP/HTTP collector (`:4318/v1/traces`) or the Jaeger
UI. Model calls carry the OpenTelemetry GenAI semantic-convention attributes
`gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.id`,
`gen_ai.response.model`, `gen_ai.usage.input_tokens`,
`gen_ai.usage.output_tokens` and `gen_ai.workflow.name`, alongside Nika's own
`nika.*` attributes (task id and hashes, tokens, permits, the chain head).
See the [OTel GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).

Over HTTP, `nika serve --bind` streams each job's lifecycle as server-sent
events (`execution.started`, `execution.settled`…), not the per-task journal
events. From TypeScript, iterate `run.events()`, then await `run.result()`.

## Kernel interfaces (for engine implementers)

The engine kernel also declares observability interfaces for alternative
engines and future adapters: `MetricsExporter`, `TracerProvider`,
`BillingSink`, `AuditSink` and `SecretResolver`. Engine 0.124.3 ships no
production implementation of them: they exist as test doubles only. What a
0.124.3 run gives you is the journal, the `--json` stream, the cost fields on
task events (`cost_incurred`, `task_completed`) and `nika trace export`.

## Related decisions

* **ADR-113**: the nine-key envelope; `workflow_started` carries the
  workflow's name.
* **ADR-028**: forward-compatibility reservations, such as
  `StopReason::Unknown(String)` in an inference response.
* **ADR-035**: the telemetry seams (`SpanGuard` parent, `SpanRef`).

## Read next

> [card] [Traces](https://docs.nika.sh/concepts/traces.md)
>
> The hash-chained journal these events form, and how to verify it.

> [card] [SDK events](https://docs.nika.sh/sdk/runtime/events.md)
>
> The normalized vocabulary `run.events()` yields.

> [card] [Observability](https://docs.nika.sh/guides/observability.md)
>
> Ship the stream to your own tools.

> [card] [Bindings](https://docs.nika.sh/concepts/bindings.md)
>
> How values move between tasks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.