# Events (https://docs.neuralisapp.com/agent-core/events)

agent-core declares eight **events** in its manifest. Each one travels over
the workspace's single realtime connection and can raise a notification; the
contract (data schema, subject, `requires`, `notify`) is on
[package-system events](https://docs.neuralisapp.com/package-system/events.md).

Every event is filtered to its audience before it is sent: the caller must hold
the event's feature, and the subject decides who it concerns — a workflow event
reaches the people who may see that workflow, a device event reaches the
device's owner, a `platform.users` holder, or a member who sees one of the
device's sources in that project. Each user can turn
any notification on or off; the table gives the default.

## Workflow events [#workflow-events]

Gated by `workflow.read`. Each carries the workflow id, the run id, its status,
a short title, and a link that opens the run in the Calendar.

| Event | When | Notification by default |
| --- | --- | --- |
| `workflow.run.started` | A run of a workflow you created began. | off |
| `workflow.run.finished` | A run of a workflow you created completed. | on (success) |
| `workflow.run.failed` | A run ended without success and will not be retried; it names the failure class (`failed`, `timed_out`, `interrupted`). | on (error) |
| `workflow.paused` | The platform paused a workflow you created; it needs your attention before it runs again. | on (warning) |

## Device events [#device-events]

Gated by `core.agents`. They carry the device id and its name as the notice
title — never a path — and open the Admin widget's Devices tab.

| Event | When | Notification by default |
| --- | --- | --- |
| `device.paired` | A machine was paired as your device; it appears in the Devices list and can carry sources and terminals once it is online. | on |
| `device.offline` | Your device lost its link and stayed away past the grace period; its sources serve their indexed copy until it is back. | off |
| `device.online` | Your device linked back. Clears an open `device.offline` notice. | off |
| `device.revoked` | Your device was revoked: its link, terminals and background runs ended, and it must be paired again to return. | on |

The offline grace period and how often a viewer's right to these signals is
re-checked are [platform settings](https://docs.neuralisapp.com/agent-core/config-settings.md). Pairing and
devices themselves are described on [devices](https://docs.neuralisapp.com/getting-started/devices.md).

Conversations use the same realtime connection: a turn no browser is driving —
a scheduled run, a background subagent reporting back, a message from another
agent — appears in an open tab without a reload. That feed is a conversation
channel, not a declared event, and it follows the conversation's own read rule.
