Stream Executions and Selector Events

Figranium exposes two Server-Sent Events endpoints, and the SDK surfaces both as AsyncIterable<StreamEvent>. You consume them with for await, cancel them with an AbortSignal, and read event names, IDs, and parsed data straight off each event.

Streams

Method	Endpoint	Purpose
`figranium.executions.stream()`	`/api/executions/stream`	Live execution lifecycle events
`figranium.browser.selectorStream()`	`/api/headful/selector_stream`	Selector events from a headful browser session

Both take an optional RequestOptions argument (signal, timeoutMs, headers).

StreamEvent shape

interface StreamEvent<T = unknown> {
  data: T;         // Parsed JSON payload; falls back to the raw string
  event?: string;  // SSE `event:` name, when present
  id?: string;     // SSE `id:` value, when present
  retry?: number;  // SSE `retry:` value, when present
  raw: string;     // Concatenated data lines exactly as received
}

The SDK tries JSON.parse on the data lines. If parsing fails, data is the raw string and raw still contains the original payload.

Consume execution events

Create a client

Initialize the SDK with your API key.

import { Figranium } from "@figranium/sdk";

const figranium = new Figranium({ apiKey: process.env.FIGRANIUM_API_KEY! });

Iterate the stream

Use for await to consume events as they arrive.

for await (const event of figranium.executions.stream()) {
  console.log(event.event, event.data);
}

Iteration ends when the server closes the connection or when your loop breaks. Breaking out of the loop cancels the underlying reader.

Cancel a stream

Streams honor AbortSignal. Aborting cancels the reader and terminates iteration.

const controller = new AbortController();

try {
  for await (const event of figranium.executions.stream({ signal: controller.signal })) {
    if (isTerminal(event)) controller.abort();
    handle(event);
  }
} catch (error) {
  // Aborted streams throw FigraniumError { code: "REQUEST_ABORTED" }.
}

Terminal timeouts

Streams have no default timeout. Set timeoutMs only when you want a hard deadline; the stream aborts as soon as the timer fires:

for await (const event of figranium.executions.stream({ timeoutMs: 60_000 })) {
  console.log(event.data);
}

Typed payloads

stream() accepts a generic type parameter that types the parsed data:

type ExecutionEvent =
  | { status: "queued"; runId: string }
  | { status: "running"; runId: string; step: string }
  | { status: "completed"; runId: string; result: unknown };

for await (const event of figranium.executions.stream<ExecutionEvent>()) {
  if (event.data.status === "completed") {
    console.log(event.data.result);
  }
}

Because the server may add fields over time, keep type guards defensive and treat unknown status values as forward-compatible additions.

Selector stream from a headful browser

The selector stream reports element highlights from a headful browser session. Use it to power visual inspectors:

for await (const event of figranium.browser.selectorStream()) {
  console.log(event.event, event.data);
}

See Browser resource for opening, inspecting, and stopping headful sessions.

Errors

Streams throw FigraniumError in the same conditions as regular requests, plus:

EMPTY_STREAM: the response arrived with no body.
REQUEST_ABORTED: the caller aborted, or the terminal timeoutMs fired.

See Errors for the full error surface.

For long-running streams, prefer AbortSignal over timeoutMs so you can stop cleanly when your application state changes.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

Stream Executions and Selector Events

Streams

StreamEvent shape

Consume execution events

Cancel a stream

Terminal timeouts

Typed payloads

Selector stream from a headful browser

Errors

​Streams

​StreamEvent shape

​Consume execution events

​Cancel a stream

​Terminal timeouts

​Typed payloads

​Selector stream from a headful browser

​Errors

Streams

StreamEvent shape

Consume execution events

Cancel a stream

Terminal timeouts

Typed payloads

Selector stream from a headful browser

Errors