Integrate/Realtime

Realtime & delivery

Frontends and observability tools subscribe to Ether’s realtime hub to show live progress and finished results without polling.

Connect

wss://api.tryether.ai/api/realtime?token={access_token}

Local: ws://127.0.0.1:8080/api/realtime?token=…

Subscribe to the task topic from the execution bundle:

{ "action": "subscribe", "topics": ["tasks/task_abc123"] }

Events integrators care about

Event	When	UI action
os.harness.step	Harness reported a step	Show user_message (human narration)
task.interrupted	Harness needs input	Show parked state + question
task.delivered	Task succeeded	Transition to delivery view in place
activity.list_updated	Task status changed	Refresh task grid row
task.timeline	Timeline append	Optional detailed log

Harness step payload

{
  "event": "os.harness.step",
  "task_id": "task_…",
  "phase": "coding_agent",
  "user_message": "Making the changes…",
  "internal_label": "coding_agent",
  "run_id": "run_…"
}

Render user_message in product UI. Hide internal_label unless debug mode.

Delivery (task.delivered)

When a harness submits status: "submitted", Ether:

1. Marks the task Completed
2. Composes a delivery payload (ordered typed blocks)
3. Publishes task.delivered on tasks/{task_id}
4. Persists payload for replay on page load

Wireframe shape (simplified):

{
  "type": "task.delivered",
  "task_id": "task_…",
  "blocks": [
    { "type": "outcome", "…": "…" },
    { "type": "hero", "…": "…" },
    { "type": "actions", "…": "…" }
  ]
}

Full block taxonomy: ether-app design_handoff_ether_product_v2/05_delivery_system/.

Closing the loop

sequenceDiagram
  participant H as Harness
  participant API as ether-api
  participant WS as WebSocket
  participant UI as Frontend

  H->>API: POST .../steps
  API->>WS: os.harness.step
  WS->>UI: live narration

  H->>API: POST .../result (submitted)
  API->>WS: task.delivered
  WS->>UI: render delivery card

Paused tasks

If the harness sends blocked or interrupt, the task pauses. The user answers in the product UI; your harness claims again (or continues under the same lease) with updated context.

Fallback transport

SSE replay exists for activity detail pages. Prefer WebSocket when realtime.prefer_websocket is true (default for product).

Contract reference: ether-core docs/ether-app-harness-contract.md.