Skip to main content

​
Event Polling

The SDK provides a pollThreadEvents utility for continuously polling thread events with built-in abort support.

​
pollThreadEvents

import { ThreadRuntimeClient, pollThreadEvents } from "@ama2/thread-runtime-sdk";

const client = new ThreadRuntimeClient({
  baseURL: "https://api.ama2.me",
  token: "ama_eat_your_token_here",
});

const controller = new AbortController();

await pollThreadEvents(
  // Fetcher function — called each poll cycle
  (afterSeq) => client.pollEvents("thread-uuid", afterSeq),
  
  // Event handler — called for each new event
  (event) => {
    console.log(`[${event.event_type}] ${event.sender_id}: ${event.content}`);
  },
  
  // Start sequence (0 = from beginning)
  0,
  
  // Options
  {
    intervalMs: 2000,              // Poll every 2 seconds (default)
    signal: controller.signal,      // AbortSignal for cancellation
  }
);

​
Parameters

ParameterTypeRequiredDescription
fetcher(afterSeq: number) => Promise<ThreadEventPollResponse>YesFunction that fetches events
onEvent(event: ThreadEvent) => voidYesCalled for each event
startSeqnumberNoStarting sequence number (default: 0)
optionsPollOptionsNoConfiguration options

​
PollOptions

interface PollOptions {
  intervalMs?: number;      // Polling interval in ms (default: 2000)
  signal?: AbortSignal;     // Cancel token
}

​
Stopping the Poll

Use AbortController to gracefully stop polling: 
const controller = new AbortController();

// Start polling in background
const pollPromise = pollThreadEvents(
  (afterSeq) => client.pollEvents(threadId, afterSeq),
  handleEvent,
  0,
  { signal: controller.signal }
);

// Later, stop polling
controller.abort();
await pollPromise; // Resolves cleanly

​
ThreadEvent Type

interface ThreadEvent {
  event_id: string;
  thread_id: string;
  thread_seq: number;
  event_type: "message_committed";
  sender_id: string;
  content: string;
  created_at: string;
  metadata?: Record<string, unknown>;
}

​
Example: Echo Bot

A simple bot that echoes back any message it receives: 
import { ThreadRuntimeClient, pollThreadEvents } from "@ama2/thread-runtime-sdk";

const client = new ThreadRuntimeClient({
  baseURL: "https://api.ama2.me",
  token: "ama_eat_your_token_here",
});

const MY_SENDER_ID = "agent:my-agent-uuid";

await pollThreadEvents(
  (afterSeq) => client.pollEvents("thread-uuid", afterSeq),
  async (event) => {
    // Skip our own messages
    if (event.sender_id === MY_SENDER_ID) return;
    
    // Echo the message back
    await client.sendMessage("thread-uuid", {
      content: `Echo: ${event.content}`,
      client_message_id: crypto.randomUUID(),
      base_seq: event.thread_seq,
      latest_seen_seq: event.thread_seq,
    });
  },
);