API

Event catalog

Mobius has two event planes. Source events are durable project events that event triggers and wait_for_event steps can match. Run-stream events are per-run timeline records for operators, server-sent events (SSE), and the run detail page.

Do not use run-stream events as triggers directly. When a run reaches a terminal state, Mobius emits a separate source event such as run.completed for loop-to-loop reactions.

Source event envelope

Source events use one normalized envelope:

{
  "event_type": "table.row.inserted",
  "source_kind": "table_row",
  "source_id": "tbl_01...",
  "event": {
    "table_id": "tbl_01...",
    "row_id": "row_01..."
  },
  "meta": {
    "event_type": "table.row.inserted",
    "table_id": "tbl_01...",
    "row_id": "row_01..."
  }
}

Event triggers start runs with the normalized event at inputs.event and routing fields at inputs.meta. wait_for_event conditions and payload mappings evaluate against { event, meta }.

Public source events

Event	Source kind	Triggerable	Waitable	Sent when	Meta fields
`artifact.created`	`artifact`	Yes	Yes	An artifact is produced during a run.	`artifact_id`, `loop_run_id`, `kind`, `content_type`
`email.received`	`email`	Yes	Yes	Email arrives at a Mobius agent address.	`agent_id`
`http_trigger.received`	`http_trigger`	Yes	Yes	An inbound request reaches an HTTP trigger URL.	`trigger_id`, `http_handle`
`interaction.resolved`	`interaction`	No	Yes	An interaction resolves from a participant response.	`interaction_id`, `kind`, `status`, `responder_id`, `resolving_response_id`
`run.cancelled`	`loop_run`	Yes	Yes	A loop run reaches `cancelled`.	`run_id`, `loop_id`
`run.completed`	`loop_run`	Yes	Yes	A loop run reaches `completed`.	`run_id`, `loop_id`
`run.failed`	`loop_run`	Yes	Yes	A loop run reaches `failed`.	`run_id`, `loop_id`
`session.message.created`	`session`	Yes	Yes	A new message is posted in an agent session.	`session_id`, `agent_id`, `message_id`, `role`
`signal.<name>`	`signal`	No	Yes	A signal is sent to a run-scoped wait.	`run_id`, `signal_name`
`table.row.deleted`	`table_row`	Yes	Yes	A table row is deleted.	`table_name`, `table_id`, `row_id`
`table.row.inserted`	`table_row`	Yes	Yes	A table row is inserted.	`table_name`, `table_id`, `row_id`
`table.row.updated`	`table_row`	Yes	Yes	A table row is updated.	`table_name`, `table_id`, `row_id`

interaction.resolved and signal.<name> are waitable but not triggerable. Use them to resume an existing run, not to start a new one.

Integration source events

Integration events are provider-scoped and project-aware. The event catalog in the app and API is the source of truth for which provider events are active in your project.

Provider events follow this pattern:

<provider>.<resource>.<verb>

Examples:

github.pull_request.opened
github.pull_request.closed
linear.issue.created
slack.event
gmail.message.received
jira.issue.updated

Use exact names for narrow triggers. Use a trailing wildcard only when every event below a prefix should match:

triggers:
  - kind: event
    config:
      event_type: github.pull_request.*

Internal source events

These event types exist in the source_events table for runtime processing, but they are internal. Do not use them in authored triggers or waits.

Event	Why it exists
`interaction.http_subscriber.dispatch`	Dispatches an interaction callback to an HTTP subscriber.
`loop.http_trigger.received`	Starts the asynchronous handler for an HTTP trigger.
`loop.run_allocation.completed`	Records a worker-reported completed run allocation.
`loop.run_allocation.failed`	Records a worker-reported failed run allocation.
`loop.schedule.tick`	Starts the asynchronous handler for a schedule trigger.
`loop_run.continue`	Re-executes a run after a step lease expires.
`loop_run.resume`	Resumes a run when a timer or signal is due.
`run.progress_initial`	Starts server-side progression for a newly persisted run.
`run.resume`	Resumes a suspended run from the older resume path.
`schedule.tick`	Records a schedule tick before the public loop handler runs.

If you need to react to a schedule, add a schedule trigger. If you need to react to an HTTP request, add an http trigger.

Run-stream events

Run-stream events are stored on a single run and replayed by the run events API and SSE stream. They are what the Timeline tab renders.

Event	Sent when	Payload to expect
`run.started`	The run is created and execution begins.	Run ID, loop/version identifiers, source fields.
`run.suspended`	The run is waiting on a timer, event, interaction, or worker-owned work.	Step key, wait kind, wait details.
`run.resumed`	A suspended run starts moving again.	Step key and resume reason.
`run.completed`	The run reaches `completed`.	Final result context.
`run.failed`	The run reaches `failed`.	Error text, step key when known, error type.
`run.cancelled`	The run is cancelled.	Reason and cancellation metadata.
`step.started`	A step begins.	Step key and step kind.
`step.suspended`	A step opens a wait.	Step key, wait kind, subscription or interaction details.
`step.resumed`	A suspended step resumes.	Step key and kind.
`step.completed`	A step finishes successfully.	Step key and output.
`step.failed`	A step fails.	Step key, error, and error type.
`step.retried`	A step failure has attempts remaining.	Step key, attempt, and retry metadata.
`step.skipped`	A conditional `loop` step does not start its child run.	Step key and kind.
`wait.opened`	A `sleep`, `wait_for_event`, or `interaction` wait is registered.	Wait kind, subject, deadline, and step key.
`wait.resumed`	A wait receives the payload that resumes it.	Resolved event, signal, or interaction payload.
`wait.timed_out`	A wait reaches its timeout.	Step key, wait kind, and timeout reason.
`interaction.requested`	An `interaction` step creates an interaction.	Interaction ID, protocol, targets, and prompt facts.
`interaction.responded`	A run-backed interaction resolves and resumes the step.	Interaction ID, response value, and responder facts.
`action.called`	An `action` step dispatches a server, worker, or environment action.	Action name, step key, and parameters metadata.
`action.completed`	An action returns successfully.	Action name, step key, and result.
`action.failed`	An action attempt fails.	Action name, step key, error, and error type.
`action.retried`	A worker-executed action is requeued for another attempt.	Action name, attempt, max attempts.
`action.result`	Legacy compatibility record for action result rendering.	Same result shape as the action completion path.
`artifact.created`	A run-linked artifact is available.	Artifact ID, name, content type, run and step lineage.
`generation.delta`	A live generation stream emits partial text.	Provider-specific delta payload.
`limit.reached`	A runtime or billing cap stops the run.	Limit kind, configured cap, and observed usage.
`usage.recorded`	Usage attribution is recorded for the run.	Category, quantity, and attribution metadata.

Prefer action.completed for new consumers. Keep action.result handling only for compatibility with older run records.

Example run stream

event: run.started
event: step.started
event: action.called
event: action.completed
event: step.completed
event: usage.recorded
event: run.completed

The stream is replayable by sequence number. If a client reconnects, ask for events after the last sequence it saw so the timeline stays complete.

Match events from triggers.
Resume runs from steps.
Inspect timelines from runs.