Event lifecycle and reply timing

LoreOS replies are asynchronous. POST /messages does not return the character’s reply — it accepts the user’s message, returns a cursor, and the reply lands later on the session event log. This is not request/response; it is messenger-style. This page is the precise contract for the sequence an adapter sees, the timing to design for, and the failure and recovery behavior.

If you are wiring a bot or chat UI on top of LoreOS, read this before you build your polling or webhook loop. For the transport options (poll vs SSE vs webhook) see Delivery, metering, and observability.

The ordered sequence

One user message produces this ordered sequence of events on the session log. Each event carries a monotonic cursor; you advance your poll cursor as you consume them.

  adapter                         LoreOS
  ───────                         ──────
   │  POST /v1/sessions/{id}/messages {"text": "..."}
   ├──────────────────────────────────▶
   │                                    · record the user turn
   │                                    · write durability job (atomic)
   │   200  {schema_version, data:{      · kick off the reply (async)
   │          accepted, cursor: N,
   │          sent_turn_index, run_ref,
   │          reply_mode}, next_actions}
   ◀──────────────────────────────────┤
   │
   │                       (the log now has, in order:)
   │   cursor N    message.created   role=user        ← your message, echoed
   │   cursor N+1  run.status        role=character    {status:"generating", run_ref}
   │                                                    └─ emitted synchronously on accept
   │
   │   GET /v1/sessions/{id}/events?since=N
   ├──────────────────────────────────▶
   │   data:{ events:[ run.status, ... ], next_cursor }
   ◀──────────────────────────────────┤   (render a typing indicator off run.status)
   │
   │            ··· seconds-to-tens-of-seconds pass; the engine runs ···
   │
   │   cursor N+2  message.created   role=character    {text, bubbles:[...], turn_index}
   │   (and/or)    image.ready       role=character    {image_url, servable, ...}
   │
   │   GET /v1/sessions/{id}/events?since=N+1
   ├──────────────────────────────────▶
   │   data:{ events:[ message.created(character), ... ], next_cursor }
   ◀──────────────────────────────────┤   (clear typing; render the reply bubbles)
   │
   │   (optional) GET /v1/sessions/{id}/trace   ← settled per-turn cost + delivery, keyed by run_ref

In words:

1. You send. POST /v1/sessions/{id}/messages with {text} (optionally reply_mode).
2. You get an accept envelope — not the reply. It tells you the cursor your message landed at and the run_ref that correlates this whole turn.
3. message.created (role user) appears on the log at that cursor — your own message, echoed back as an event so the log is the single source of truth.
4. run.status {status:"generating"} (role character) appears next. It is emitted synchronously, the instant the send is accepted — render a typing indicator off it.
5. message.created (role character) appears when the reply is ready, seconds to tens of seconds later, carrying the reply text and its ordered bubbles. Clear the typing indicator on this event.
6. (Optional) settle the cost via GET /v1/sessions/{id}/trace or /runs, filtered by the run_ref you got in step 2.

What the send response actually contains

POST /v1/sessions/{id}/messages returns the standard versioned envelope. The data object:

1
{
2
  "schema_version": "v0",
3
  "data": {
4
    "accepted": true,
5
    "cursor": 41,
6
    "sent_turn_index": 12,
7
    "run_ref": "0f4c1b9e-...",
8
    "reply_mode": "fast"
9
  },
10
  "next_actions": [
11
    { "command": "GET /v1/sessions/{id}/events?since=41", "description": "Poll for the character's reply" },
12
    { "command": "GET /v1/sessions/{id}/trace", "description": "Per-turn settled cost + latency + delivery (filter by run_ref)" }
13
  ]
14
}

The events, field by field

Each entry in GET /v1/sessions/{id}/events is one log event:

1
{
2
  "id": "…",
3
  "schema_version": "v0",
4
  "cursor": 42,
5
  "session_id": "…",
6
  "type": "run.status",
7
  "event_type": "run.status",
8
  "role": "character",
9
  "trace_id": "0f4c1b9e-...",
10
  "created_at": "2026-06-05T09:14:02.118Z",
11
  "payload": { "status": "generating", "run_ref": "0f4c1b9e-..." },
12
  "source_ref": { … }
13
}

type and event_type are the same string (both are present for client convenience). The event types you will see for the send flow:

Does run.status always arrive?

On the /v1 send path, yes. run.status {status:"generating"} is written to the log synchronously, in the same transaction that accepts the message — before POST /messages returns. So for any send you make through POST /v1/sessions/{id}/messages, the run.status event is already on the log by the time you start polling.

It is an additive event type. Build your client to ignore unknown event types (so the contract can grow) and to act only on the types you handle — typically message.created and image.ready. run.status is a progress hint, not a delivery: it is the signal you turn a typing indicator on with.

When does message.failed arrive, and is it retryable?

message.failed (role system) is emitted when the reply pipeline itself errors for a turn — so your poll/SSE loop sees a terminal outcome instead of waiting forever. Its payload:

1
{ "turn_index": 12, "reason": "generation_failed", "recoverable": true }

• reason is a redacted enum — generation_failed or timed_out. It is never the raw internal error (that stays server-side; see the PII note in observability).
• recoverable is true: the user turn is recorded, so you can resend the message (a new POST /messages) to try again. Treat message.failed as “this attempt failed, you may retry,” and surface a retry affordance in your UI.

Withheld / no-reply turns

A reply is not guaranteed for every user message. The character may deliberately withhold a reply (an emission decision — for example it is mid-task, or chose silence), or it may exit the session. So:

• A run.status for a turn is not a promise that a message.created (character) follows.
• If the character withheld, no character message.created appears for that turn — and there is no message.failed either (nothing failed; it was a deliberate decision). Your typing indicator should time out on its own (see latency UX below), not hang forever.
• If the character exited, you get a session.exited event. After that, sends to the session return 409 session_exited; start a new session to continue.

Design your client so a turn that produces no character reply is a normal, handled outcome — clear the typing indicator on a timeout and move on.

How far to advance the polling cursor

Always advance since to the maximum cursor you have seen across all event types — not just the cursor of the last message you rendered. The events endpoint returns next_cursor (the cursor of the last event in the page, or your since if the page was empty); poll again with since=next_cursor. Because you advance past run.status, image.ready, and every other event too, you never re-read events you have already consumed, and you never skip one.

The cursor is also your dedupe key for at-least-once delivery: if you use the webhook projection (which is at-least-once with retry), dedupe incoming events by cursor (or by the x-auto-dating-event-id header) so a redelivered event is not rendered twice.

The durability safety net (the reply lands even if the process dies)

When you send a message, LoreOS writes a small durability job in the same transaction that records your user turn and the message.created + run.status events. The reply then runs in-process. If the API process restarts, deploys, or crashes after accepting your message but before the reply lands, the in-process work dies — but the durability job does not. A background watchdog finds reply jobs that never reached a decision (no character turn followed, past a staleness threshold) and re-runs them on a durable worker.

What this means for you as an adapter:

• A momentary API restart/deploy mid-reply does not lose the reply. It arrives on the event log a bit later, via recovery — your normal poll/SSE loop picks it up with no special handling.
• The recovery is designed to land before the SSE connection window closes, so even a streaming client generally sees the recovered reply on the same connection.
• You do not need to implement your own “did the reply get dropped?” reconciliation for process death. Keep your message-send retries idempotent (the Idempotency-Key header) and let the event log be your source of truth.

Latency: what to design for

Because replies are asynchronous and go through the full character engine (grounding, safety, knowledge, emission, and — in deep mode — a voice-quality critic and rewrite), a reply takes seconds to tens of seconds, not milliseconds. This is the central UX fact to design around: it is messenger latency, not API latency.

reply_mode: fast vs deep

POST /messages takes an optional reply_mode:

Either way, the deeper world-model / relational update runs asynchronously after the reply is sent, so it never blocks the reply you show the user. Default to fast for chat; reach for deep when voice quality matters more than latency for a given turn.

Recommended client behavior

A robust adapter treats the wait as a first-class state:

Putting it together

The minimal correct loop, regardless of transport:

1. POST /messages → keep cursor and run_ref.
2. Poll GET /events?since=<max cursor seen> (or open the SSE stream / receive webhooks).
3. On run.status → show typing. On character message.created → render bubbles, clear typing. On image.ready (with servable:true) → render image_url. On session.exited → end the session. On message.failed → offer retry.
4. Advance your cursor to the largest cursor you have seen, every time.
5. Don’t block on a stopwatch — the event log is the truth, the durability net guarantees the reply lands, and a withheld turn is a normal outcome you time out gracefully.

For the per-turn cost and delivery view keyed by run_ref, and exactly what you can and cannot inspect, see Delivery, metering, and observability.