agent-relay 3.2.22 → 4.0.1

package/packages/sdk/src/relay.ts

@@ -24,15 +24,18 @@
  */
 
 import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
+import { RelayCast } from '@relaycast/sdk';
+
 import {
   AgentRelayClient,
-  AgentRelayProtocolError,
-  type AgentRelayClientOptions,
-  type SendMessageInput,
-  type SpawnPtyInput,
+  type AgentRelayBrokerInitArgs,
+  type AgentRelaySpawnOptions,
 } from './client.js';
+import { AgentRelayProtocolError } from './transport.js';
+import type { SendMessageInput, SpawnPtyInput } from './types.js';
 import type {
   AgentRuntime,
   BrokerEvent,
@@ -75,6 +78,71 @@ function buildUnsupportedOperationMessage(
   };
 }
 
+interface WorkspaceRegistryEntry {
+  relaycastApiKey?: string;
+  relayfileUrl?: string;
+  createdAt?: string;
+  agents?: string[];
+}
+
+type WorkspaceRegistry = Record<string, WorkspaceRegistryEntry>;
+
+const WORKSPACE_ID_PREFIX = 'rw_';
+const WORKSPACE_ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+
+function normalizeWorkspaceId(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function generateWorkspaceId(): string {
+  const alphabetLength = WORKSPACE_ID_ALPHABET.length;
+  const maxUnbiasedValue = Math.floor(256 / alphabetLength) * alphabetLength;
+  let suffix = '';
+
+  while (suffix.length < 8) {
+    const bytes = randomBytes(8 - suffix.length);
+    for (const byte of bytes) {
+      if (byte >= maxUnbiasedValue) continue;
+      suffix += WORKSPACE_ID_ALPHABET[byte % alphabetLength];
+      if (suffix.length === 8) break;
+    }
+  }
+
+  return `${WORKSPACE_ID_PREFIX}${suffix}`;
+}
+
+function toWorkspaceRegistryEntry(value: unknown): WorkspaceRegistryEntry {
+  if (!value || typeof value !== 'object') {
+    return {};
+  }
+
+  const record = value as Record<string, unknown>;
+  const relaycastApiKey =
+    typeof record.relaycastApiKey === 'string' && record.relaycastApiKey.trim()
+      ? record.relaycastApiKey.trim()
+      : undefined;
+  const relayfileUrl =
+    typeof record.relayfileUrl === 'string' && record.relayfileUrl.trim()
+      ? record.relayfileUrl.trim()
+      : undefined;
+  const createdAt =
+    typeof record.createdAt === 'string' && record.createdAt.trim() ? record.createdAt.trim() : undefined;
+  const agents = Array.isArray(record.agents)
+    ? record.agents
+        .filter((agent): agent is string => typeof agent === 'string')
+        .map((agent) => agent.trim())
+        .filter((agent) => agent.length > 0)
+    : undefined;
+
+  return {
+    ...(relaycastApiKey ? { relaycastApiKey } : {}),
+    ...(relayfileUrl ? { relayfileUrl } : {}),
+    ...(createdAt ? { createdAt } : {}),
+    ...(agents && agents.length > 0 ? { agents } : {}),
+  };
+}
+
 // ── Public types ────────────────────────────────────────────────────────────
 
 export interface Message {
@@ -201,7 +269,10 @@ export interface Agent {
    * @param options.stream — if provided, only invoke callback when the event stream matches (e.g. 'stdout', 'stderr')
    * @param options.mode — 'chunk' for raw string callbacks, 'structured' for { stream, chunk } callbacks. Auto-detected if omitted.
    */
-  onOutput(callback: AgentOutputCallback, options?: { stream?: string; mode?: 'chunk' | 'structured' }): () => void;
+  onOutput(
+    callback: AgentOutputCallback,
+    options?: { stream?: string; mode?: 'chunk' | 'structured' }
+  ): () => void;
 }
 
 export interface HumanHandle {
@@ -236,17 +307,24 @@ export type EventHook<T> = ((value: T) => void) | null;
 
 export interface AgentRelayOptions {
   binaryPath?: string;
-  binaryArgs?: string[];
+  binaryArgs?: AgentRelayBrokerInitArgs;
   brokerName?: string;
   channels?: string[];
   cwd?: string;
   env?: NodeJS.ProcessEnv;
   requestTimeoutMs?: number;
-  shutdownTimeoutMs?: number;
   /**
-   * Name for the auto-created Relaycast workspace.
-   * If omitted, a random name is generated.
-   * Ignored when RELAY_API_KEY is already set in env or process.env.
+   * Unified workspace ID shared across relayfile, relayauth claims, and
+   * relaycast key lookup.
+   */
+  workspaceId?: string;
+  /**
+   * Display name for an auto-created Relaycast workspace.
+   * If omitted, the unified workspace ID is used.
+   *
+   * @deprecated Since v1.x this field falls back to workspaceId when omitted,
+   * changing prior behavior where it was required for workspace naming.
+   * Callers relying on distinct naming should set this explicitly.
    */
   workspaceName?: string;
   /**
@@ -302,14 +380,17 @@ export class AgentRelay {
   readonly gemini: AgentSpawner;
   readonly opencode: AgentSpawner;
 
-  private readonly clientOptions: AgentRelayClientOptions;
+  private readonly clientOptions: AgentRelaySpawnOptions;
   private readonly defaultChannels: string[];
+  private readonly requestedWorkspaceId?: string;
   private readonly workspaceName?: string;
   private readonly relaycastBaseUrl?: string;
   private relayApiKey?: string;
+  private resolvedWorkspaceId?: string;
   private client?: AgentRelayClient;
   private startPromise?: Promise<AgentRelayClient>;
   private unsubEvent?: () => void;
+  private readonly stderrListeners = new Set<(line: string) => void>();
   private readonly knownAgents = new Map<string, Agent>();
   private readonly readyAgents = new Set<string>();
   private readonly messageReadyAgents = new Set<string>();
@@ -329,18 +410,25 @@ export class AgentRelay {
   private idleResolverSeq = 0;
 
   constructor(options: AgentRelayOptions = {}) {
+    const requestedWorkspaceId = normalizeWorkspaceId(options.workspaceId);
     this.defaultChannels = options.channels ?? ['general'];
+    this.requestedWorkspaceId = requestedWorkspaceId;
     this.workspaceName = options.workspaceName;
+    if (options.workspaceName && !options.workspaceId) {
+      console.warn(
+        '[AgentRelay] workspaceName without workspaceId is deprecated and will be removed in a future major version. ' +
+          'Set workspaceId explicitly to avoid silent behavior changes.'
+      );
+    }
     this.relaycastBaseUrl = options.relaycastBaseUrl;
     this.clientOptions = {
       binaryPath: options.binaryPath,
       binaryArgs: options.binaryArgs,
-      brokerName: options.brokerName ?? options.workspaceName,
+      brokerName: options.brokerName ?? options.workspaceName ?? requestedWorkspaceId,
       channels: this.defaultChannels,
       cwd: options.cwd,
       env: options.env,
       requestTimeoutMs: options.requestTimeoutMs,
-      shutdownTimeoutMs: options.shutdownTimeoutMs,
     };
 
     this.codex = this.createSpawner('codex', 'Codex', 'pty');
@@ -349,28 +437,122 @@ export class AgentRelay {
     this.opencode = this.createSpawner('opencode', 'OpenCode', 'headless');
   }
 
+  private getWorkspaceRegistryPath(): string {
+    return path.join(this.clientOptions.cwd ?? process.cwd(), '.relay', 'workspaces.json');
+  }
+
+  private readWorkspaceRegistry(): WorkspaceRegistry {
+    const registryPath = this.getWorkspaceRegistryPath();
+    if (!existsSync(registryPath)) {
+      return {};
+    }
+
+    let raw: string;
+    try {
+      raw = readFileSync(registryPath, 'utf8').trim();
+    } catch {
+      return {};
+    }
+    if (!raw) {
+      return {};
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // Registry file is corrupted (partial write, disk full, concurrent access).
+      // Return empty registry so callers can re-create it.
+      return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+
+    const registry: WorkspaceRegistry = {};
+    for (const [workspaceId, entry] of Object.entries(parsed as Record<string, unknown>)) {
+      const normalizedId = normalizeWorkspaceId(workspaceId);
+      if (!normalizedId) continue;
+      registry[normalizedId] = toWorkspaceRegistryEntry(entry);
+    }
+    return registry;
+  }
+
+  private writeWorkspaceRegistry(registry: WorkspaceRegistry): void {
+    const registryPath = this.getWorkspaceRegistryPath();
+    mkdirSync(path.dirname(registryPath), { recursive: true });
+    writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  }
+
+  private persistWorkspaceMapping(workspaceId: string, apiKey: string): void {
+    const registry = this.readWorkspaceRegistry();
+    const existing = registry[workspaceId] ?? {};
+    registry[workspaceId] = {
+      ...existing,
+      relaycastApiKey: apiKey,
+      relayfileUrl: existing.relayfileUrl,
+      createdAt: existing.createdAt ?? new Date().toISOString(),
+      agents: existing.agents ?? [],
+    };
+    this.writeWorkspaceRegistry(registry);
+  }
+
+  private findMappedWorkspaceIdByApiKey(apiKey: string): string | undefined {
+    const registry = this.readWorkspaceRegistry();
+    for (const [workspaceId, entry] of Object.entries(registry)) {
+      if (entry.relaycastApiKey === apiKey) {
+        return workspaceId;
+      }
+    }
+    return undefined;
+  }
+
+  private getResolvedWorkspaceId(): string | undefined {
+    return this.resolvedWorkspaceId ?? this.requestedWorkspaceId;
+  }
+
+  private getRelaycastBaseUrl(): string {
+    return (
+      this.relaycastBaseUrl ??
+      this.clientOptions.env?.RELAYCAST_BASE_URL ??
+      process.env.RELAYCAST_BASE_URL ??
+      'https://api.relaycast.dev'
+    );
+  }
+
+  private applyWorkspaceEnv(workspaceId: string, apiKey: string): void {
+    const env: NodeJS.ProcessEnv = {
+      ...(this.clientOptions.env ?? process.env),
+      RELAY_API_KEY: apiKey,
+      RELAYFILE_WORKSPACE: workspaceId,
+      RELAY_DEFAULT_WORKSPACE: workspaceId,
+      RELAY_WORKSPACE_ID: workspaceId,
+      RELAY_WORKSPACES_JSON: JSON.stringify([{ workspace_id: workspaceId, api_key: apiKey }]),
+    };
+    if (this.relaycastBaseUrl) {
+      env.RELAYCAST_BASE_URL = this.relaycastBaseUrl;
+    }
+    this.clientOptions.env = env;
+  }
+
+  private async createMappedRelaycastWorkspace(workspaceId: string): Promise<string> {
+    const created = await RelayCast.createWorkspace(
+      this.workspaceName ?? workspaceId,
+      this.getRelaycastBaseUrl()
+    );
+    return created.apiKey;
+  }
+
   /**
    * Subscribe to broker stderr output. Listener is wired immediately if the
    * client is already started, otherwise it is attached when the client starts.
    * Returns an unsubscribe function.
    */
   onBrokerStderr(listener: (line: string) => void): () => void {
-    if (this.client) {
-      return this.client.onBrokerStderr(listener);
-    }
-    // Queue it: once ensureStarted completes, wire it up
-    let unsub: (() => void) | undefined;
-    const queuedUnsub = () => {
-      unsub?.();
+    this.stderrListeners.add(listener);
+    return () => {
+      this.stderrListeners.delete(listener);
     };
-    // Use the start promise if one is pending
-    const promise = this.startPromise ?? this.ensureStarted();
-    promise
-      .then((c) => {
-        unsub = c.onBrokerStderr(listener);
-      })
-      .catch(() => {});
-    return queuedUnsub;
   }
 
   // ── Spawning ────────────────────────────────────────────────────────────
@@ -594,7 +776,7 @@ export class AgentRelay {
   /** Pre-register a batch of agents with Relaycast before steps execute. */
   async preflightAgents(agents: Array<{ name: string; cli: string }>): Promise<void> {
     const client = await this.ensureStarted();
-    await client.preflightAgents(agents);
+    await client.preflight(agents);
   }
 
   /** List agents with PIDs from the broker (for worker registration). */
@@ -939,36 +1121,39 @@ export class AgentRelay {
    */
   private async ensureRelaycastApiKey(): Promise<void> {
     if (this.relayApiKey) {
-      this.wireRelaycastBaseUrl();
+      const workspaceId = this.getResolvedWorkspaceId();
+      if (workspaceId) {
+        this.applyWorkspaceEnv(workspaceId, this.relayApiKey);
+        try { this.persistWorkspaceMapping(workspaceId, this.relayApiKey); } catch { /* non-critical */ }
+      } else {
+        this.wireRelaycastBaseUrl();
+      }
       return;
     }
 
     const envKey = this.clientOptions.env?.RELAY_API_KEY ?? process.env.RELAY_API_KEY;
-    if (envKey) {
-      this.relayApiKey = envKey;
-      // Ensure the broker subprocess inherits the full process env + the key.
-      // Without this, spawning with an explicit binaryPath but no env option
-      // would cause the broker to start with an empty environment (no PATH,
-      // no RELAY_API_KEY), making connect_relay() hang and triggering the
-      // hello-handshake timeout.
-      if (!this.clientOptions.env) {
-        this.clientOptions.env = { ...process.env, RELAY_API_KEY: envKey };
-      } else if (!this.clientOptions.env.RELAY_API_KEY) {
-        this.clientOptions.env.RELAY_API_KEY = envKey;
-      }
-      this.wireRelaycastBaseUrl();
+    const requestedWorkspaceId = this.requestedWorkspaceId;
+    if (requestedWorkspaceId) {
+      const registry = this.readWorkspaceRegistry();
+      const mappedKey = registry[requestedWorkspaceId]?.relaycastApiKey;
+      const resolvedKey =
+        mappedKey ?? envKey ?? (await this.createMappedRelaycastWorkspace(requestedWorkspaceId));
+      this.relayApiKey = resolvedKey;
+      this.resolvedWorkspaceId = requestedWorkspaceId;
+      this.applyWorkspaceEnv(requestedWorkspaceId, resolvedKey);
+      try { this.persistWorkspaceMapping(requestedWorkspaceId, resolvedKey); } catch { /* non-critical */ }
       return;
     }
 
-    // No API key in env — broker will create/select its own workspace.
-    // Ensure the broker process inherits the full environment (PATH, etc.)
-    // so it can connect to Relaycast. The actual workspace key will be
-    // read from the broker's hello_ack response in ensureStarted().
-    if (!this.clientOptions.env) {
-      this.clientOptions.env = { ...process.env };
-    }
+    const resolvedWorkspaceId = envKey
+      ? (this.findMappedWorkspaceIdByApiKey(envKey) ?? generateWorkspaceId())
+      : generateWorkspaceId();
+    const resolvedKey = envKey ?? (await this.createMappedRelaycastWorkspace(resolvedWorkspaceId));
 
-    this.wireRelaycastBaseUrl();
+    this.relayApiKey = resolvedKey;
+    this.resolvedWorkspaceId = resolvedWorkspaceId;
+    this.applyWorkspaceEnv(resolvedWorkspaceId, resolvedKey);
+    try { this.persistWorkspaceMapping(resolvedWorkspaceId, resolvedKey); } catch { /* non-critical */ }
   }
 
   /** Inject relaycastBaseUrl into broker env. Explicit option wins over inherited env. */
@@ -983,19 +1168,38 @@ export class AgentRelay {
     if (this.startPromise) return this.startPromise;
 
     this.startPromise = this.ensureRelaycastApiKey()
-      .then(() => AgentRelayClient.start(this.clientOptions))
+      .then(() =>
+        AgentRelayClient.spawn({
+          ...this.clientOptions,
+          onStderr: (line) => {
+            for (const listener of this.stderrListeners) {
+              try {
+                listener(line);
+              } catch {
+                /* ignore */
+              }
+            }
+          },
+        })
+      )
       .then((c) => {
-        this.client = c;
-        this.startPromise = undefined;
         // Use the workspace key the broker actually connected with.
         // This ensures SDK and workers are always on the same workspace.
         if (c.workspaceKey) {
           this.relayApiKey = c.workspaceKey;
+          const workspaceId = this.getResolvedWorkspaceId();
+          if (workspaceId) {
+            this.applyWorkspaceEnv(workspaceId, c.workspaceKey);
+            try { this.persistWorkspaceMapping(workspaceId, c.workspaceKey); } catch { /* non-critical */ }
+          }
         }
         this.wireEvents(c);
+        this.client = c;
+        this.startPromise = undefined;
         return c;
       })
       .catch((err) => {
+        this.client = undefined;
         this.startPromise = undefined;
         throw err;
       });
@@ -1332,7 +1536,10 @@ export class AgentRelay {
       async unsubscribe(channelsToRemove: string[]) {
         await relay.unsubscribe({ agent: name, channels: channelsToRemove });
       },
-      onOutput(callback: AgentOutputCallback, options?: { stream?: string; mode?: 'chunk' | 'structured' }): () => void {
+      onOutput(
+        callback: AgentOutputCallback,
+        options?: { stream?: string; mode?: 'chunk' | 'structured' }
+      ): () => void {
         let listeners = relay.outputListeners.get(name);
         if (!listeners) {
           listeners = new Set();

package/packages/sdk/src/transport.ts

@@ -0,0 +1,216 @@
+/**
+ * BrokerTransport — HTTP/WS transport layer for communicating with the
+ * agent-relay broker. Used internally by AgentRelayClient.
+ *
+ * Handles:
+ * - HTTP requests with API key auth and structured error parsing
+ * - WebSocket connection for real-time event streaming
+ * - Event buffering, replay, and query (mirrors stdio client behavior)
+ */
+
+import WebSocket from 'ws';
+import type { BrokerEvent } from './protocol.js';
+
+export class AgentRelayProtocolError extends Error {
+  code: string;
+  retryable: boolean;
+  data?: unknown;
+
+  constructor(payload: { code: string; message: string; retryable?: boolean; data?: unknown }) {
+    super(payload.message);
+    this.name = 'AgentRelayProtocolError';
+    this.code = payload.code;
+    this.retryable = payload.retryable ?? false;
+    this.data = payload.data;
+  }
+}
+
+export interface BrokerTransportOptions {
+  baseUrl: string;
+  apiKey?: string;
+  /** Timeout in ms for HTTP requests. Default: 30000. */
+  requestTimeoutMs?: number;
+  /** Maximum number of events to buffer in memory for queryEvents/getLastEvent */
+  maxBufferSize?: number;
+}
+
+export class BrokerTransport {
+  private readonly baseUrl: string;
+  private readonly apiKey?: string;
+  private readonly requestTimeoutMs: number;
+  private readonly maxBufferSize: number;
+
+  private ws: WebSocket | null = null;
+  private eventListeners = new Set<(event: BrokerEvent) => void>();
+  private eventBuffer: BrokerEvent[] = [];
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private sinceSeq = 0;
+  private _connected = false;
+  private _intentionalClose = false;
+
+  constructor(options: BrokerTransportOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, '');
+    this.apiKey = options.apiKey;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    this.maxBufferSize = options.maxBufferSize ?? 1000;
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  get wsUrl(): string {
+    return this.baseUrl.replace(/^http/, 'ws') + '/ws';
+  }
+
+  // ── HTTP ─────────────────────────────────────────────────────────────
+
+  async request<T = unknown>(path: string, init?: RequestInit): Promise<T> {
+    const headers = new Headers(init?.headers);
+    if (!headers.has('Content-Type')) {
+      headers.set('Content-Type', 'application/json');
+    }
+    if (this.apiKey) {
+      headers.set('X-API-Key', this.apiKey);
+    }
+
+    const signal = init?.signal ?? AbortSignal.timeout(this.requestTimeoutMs);
+    const res = await fetch(`${this.baseUrl}${path}`, { ...init, headers, signal });
+
+    if (!res.ok) {
+      let body: { code?: string; message?: string; error?: string } | undefined;
+      try {
+        body = (await res.json()) as { code?: string; message?: string; error?: string };
+      } catch {
+        // non-JSON error
+      }
+      throw new AgentRelayProtocolError({
+        code: body?.code ?? `http_${res.status}`,
+        message: body?.message ?? body?.error ?? res.statusText,
+        retryable: res.status >= 500,
+      });
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  // ── WebSocket events ─────────────────────────────────────────────────
+
+  connect(sinceSeq?: number): void {
+    if (this.ws) return;
+    // Clear any pending reconnect timer to avoid duplicate connections
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.sinceSeq = sinceSeq ?? this.sinceSeq;
+    this._connect();
+  }
+
+  private _connect(): void {
+    this._intentionalClose = false;
+    const url = `${this.wsUrl}?sinceSeq=${this.sinceSeq}`;
+    const headers: Record<string, string> = {};
+    if (this.apiKey) {
+      headers['X-API-Key'] = this.apiKey;
+    }
+
+    this.ws = new WebSocket(url, { headers });
+
+    this.ws.on('open', () => {
+      this._connected = true;
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+      }
+    });
+
+    this.ws.on('message', (data) => {
+      try {
+        const event = JSON.parse(data.toString()) as BrokerEvent & { seq?: number };
+        // Track sequence for replay on reconnect
+        if (typeof event.seq === 'number' && event.seq > this.sinceSeq) {
+          this.sinceSeq = event.seq;
+        }
+        // Buffer the event
+        this.eventBuffer.push(event);
+        if (this.eventBuffer.length > this.maxBufferSize) {
+          this.eventBuffer = this.eventBuffer.slice(-this.maxBufferSize);
+        }
+        // Notify listeners
+        for (const listener of this.eventListeners) {
+          try {
+            listener(event);
+          } catch {
+            // don't let a bad listener break the stream
+          }
+        }
+      } catch {
+        // ignore non-JSON frames (ping/pong)
+      }
+    });
+
+    this.ws.on('close', () => {
+      this._connected = false;
+      this.ws = null;
+      // Auto-reconnect after 2s unless intentionally closed
+      if (!this._intentionalClose) {
+        this.reconnectTimer = setTimeout(() => this._connect(), 2000);
+      }
+    });
+
+    this.ws.on('error', () => {
+      // error always followed by close
+    });
+  }
+
+  disconnect(): void {
+    this._intentionalClose = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this._connected = false;
+  }
+
+  onEvent(listener: (event: BrokerEvent) => void): () => void {
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
+  }
+
+  queryEvents(filter?: { kind?: string; name?: string; since?: number; limit?: number }): BrokerEvent[] {
+    let events = [...this.eventBuffer];
+    if (filter?.kind) {
+      events = events.filter((e) => e.kind === filter.kind);
+    }
+    if (filter?.name) {
+      events = events.filter((e) => 'name' in e && e.name === filter.name);
+    }
+    if (filter?.since !== undefined) {
+      const since = filter.since;
+      events = events.filter(
+        (e) => 'timestamp' in e && typeof e.timestamp === 'number' && e.timestamp >= since
+      );
+    }
+    if (filter?.limit !== undefined) {
+      events = events.slice(-filter.limit);
+    }
+    return events;
+  }
+
+  getLastEvent(kind: string, name?: string): BrokerEvent | undefined {
+    for (let i = this.eventBuffer.length - 1; i >= 0; i -= 1) {
+      const event = this.eventBuffer[i];
+      if (event.kind === kind && (!name || ('name' in event && event.name === name))) {
+        return event;
+      }
+    }
+    return undefined;
+  }
+}