Streaming events

Status: Durable run streaming is available against the partner-preview gateway. Exact browser approval events remain pending production activation. Cancellation-reconciliation code is deployed, but final-status behavior remains pending a separate live canary. The SDK is source-available but is not published to npm.

Use streamRunEvents() for GET /v1/runs/:id/events. Each event has this shared envelope:

{
  apiVersion: "v1";
  run_id: string;
  sequence: number;
  at: string;
  type: string;
}

Durable event vocabulary

Event	Meaning
`run.accepted`	Billing reservation was recorded.
`run.started`	The durable workflow claimed the task.
`run.progress`	A non-terminal lifecycle update.
`approval.required`	Pending activation: an exact recorded browser action needs a digest-bound decision.
`approval.resolved`	Pending activation: a digest-bound approval decision was recorded.
`run.completed`	Terminal successful outcome.
`run.failed`	Terminal failed outcome.
`run.cancelled`	Terminal cancelled outcome.

Only run.completed, run.failed, and run.cancelled are terminal. Rich candidate model, text, tool, memory, output, usage, and request.* turn events in the source repository are offline schemas. They are not emitted by the public task projector and have no public streaming method.

Consume events

for await (const event of client.streamRunEvents(runId, {
  signal: controller.signal,
})) {
  switch (event.type) {
    case "run.completed":
    case "run.failed":
    case "run.cancelled":
      console.log("terminal", event.type);
      break;
    default:
      console.log(event.sequence, event.type);
  }
}

Aborting the local stream stops that read. It does not cancel the durable run. Call cancelRun() separately if you intend to request cancellation.

Reconnect with `Last-Event-ID`

Persist a sequence only after your event handler commits its work. Pass that sequence as lastEventId when reconnecting:

let cursor = 17;

for await (const event of client.streamRunEvents(runId, {
  lastEventId: cursor,
  signal: controller.signal,
})) {
  await persistEvent(event);
  cursor = event.sequence;
}

The client sends Last-Event-ID and verifies that every returned SSE id is numeric and equals the event’s sequence. It also verifies the run_id, strictly increasing sequences, terminal ordering, and EOF behavior. Reconnect explicitly after a transport failure; the SDK does not retry a stream automatically.

Reconciliation final-status contract

The migration and compatible Workers are deployed, but this path remains pending a separate live canary. Once that gate clears, reconciliation uses run.progress; it does not add a status or event type. The stream remains open while the run projects as running. Treat this exact message as a no-retry signal:

The run is reconciling an uncertain execution outcome. Do not retry or resubmit it.

Successful recovery emits:

Run reconciliation completed; execution is resuming.

If Praxa cannot verify a committing outcome, the stream ends with run.failed, failure.code: "run_outcome_unknown", and retryable: false. Inspect the external system before submitting replacement work.

Approval events after activation

approval.required contains the exact server-issued summary and action digest. Render the summary unchanged. Return the digest through approveRun() or denyRun(). The server re-derives the presentation and rejects a missing, stale, unsupported, foreign, or mismatched digest. Continue with Errors and retries for request failures and cancellation semantics.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Streaming events

Durable event vocabulary

Consume events

Reconnect with `Last-Event-ID`

Reconciliation final-status contract

Approval events after activation

​Durable event vocabulary

​Consume events

​Reconnect with Last-Event-ID

​Reconciliation final-status contract

​Approval events after activation

Durable event vocabulary

Consume events

Reconnect with `Last-Event-ID`

Reconciliation final-status contract

Approval events after activation