Add a background subscription

When to subscribe

Subscribe when completion or durable activity must remain observable after the request that started the work has ended. Keep the live stream() for request-scoped rendering.

Create the subscription

const events = agent.subscribe(
  {
    sessionId: "kestrel-session-001",
    eventTypes: ["task.updated"],
  },
  context,
);
await events.ready;
 
for await (const event of events) {
  console.log(event.type, event.sessionId);
}

Every subscription must include a session, run, thread, or event filter. The root SDK does not expose an unfiltered global event stream. Await events.ready before triggering work whose events must be observed; it settles only after the remote runner or Local Core has accepted the filtered subscription.

The subscription observes persisted events independently of the browser or request that started the work. It does not replace the live stream used to respond to that request.

Use cursors

Persist the last accepted cursor with the consumer's own checkpoint. Cursors define the restart position; event sequence and identity define ordering. Do not treat a cursor as user-supplied authority.

Consume idempotently

Record processed event identifiers, tolerate duplicate delivery, and make terminal handling idempotent. Unknown event names must be retained or skipped safely rather than coerced into a known event.

Reconnect safely

Reconnect from the last committed cursor, not the last event merely received in memory. This prevents missing an event after a consumer crashes between receipt and persistence.

Authorize the subscriber

Resolve tenant, actor, and allowed session, run, or thread filters on the server. The root SDK intentionally exposes no unfiltered global stream.

Verify

Stop a consumer after persisting an event, restart from its cursor, and confirm no durable work is missed or applied twice.

Continue with observability or the SDK reference.