Skip to content

The VS Code of video editing, built for agents.

TypeScript
8.9 KB
Raw Blame
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

// The browser side of the wire: one WebSocket, request/response by id,
// per-chat subscriptions, and reconnection with backoff. The endpoint is
// re-resolved on every attempt, which covers a host that came back on a
// new port. On reconnect every subscribed chat is re-opened, and its
// listener gets the fresh snapshot — there is no replay protocol.

import type {
  ChatEvent,
  ChatSnapshot,
  ClientMsg,
  HarnessInfo,
  HostError,
  HostMsg,
  Method,
  MethodParams,
  MethodResult,
} from "./protocol";

export type ConnectionState = "connecting" | "open" | "closed" | "unavailable";

export type ChatListener = (message: { type: "snapshot"; snapshot: ChatSnapshot } | { type: "event"; seq: number; event: ChatEvent }) => void;

export class AgentChatError extends Error {
  readonly code: HostError["code"] | "disconnected";

  constructor(code: AgentChatError["code"], message: string) {
    super(message);
    this.name = "AgentChatError";
    this.code = code;
  }
}

type Pending = { resolve(value: unknown): void; reject(error: Error): void };

type Subscription = {
  listener: ChatListener;
  /** Seq of the last snapshot delivered; events at or below it are skipped. */
  seq: number;
  /** Set once the snapshot has been delivered for the current socket. */
  opened: boolean;
};

export type AgentChatClientOptions = {
  /** Where the host is right now; null when there is none (web build without a host). */
  resolveEndpoint(): Promise<string | null>;
  /** For tests and Node: defaults to the global WebSocket. */
  WebSocket?: typeof WebSocket;
  minBackoffMs?: number;
  maxBackoffMs?: number;
};

const REQUEST_TIMEOUT_MS = 60_000;

export class AgentChatClient {
  private readonly options: AgentChatClientOptions;
  private socket: WebSocket | null = null;
  private pending = new Map<string, Pending>();
  private subscriptions = new Map<string, Subscription>();
  private stateListeners = new Set<(state: ConnectionState) => void>();
  private harnessListeners = new Set<(harnesses: HarnessInfo[]) => void>();
  private backoff: number;
  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
  private stopped = true;
  private nextId = 0;
  private _state: ConnectionState = "closed";
  private _harnesses: HarnessInfo[] = [];

  constructor(options: AgentChatClientOptions) {
    this.options = options;
    this.backoff = options.minBackoffMs ?? 500;
  }

  get state(): ConnectionState {
    return this._state;
  }

  get harnesses(): HarnessInfo[] {
    return this._harnesses;
  }

  onState(listener: (state: ConnectionState) => void): () => void {
    this.stateListeners.add(listener);
    return () => void this.stateListeners.delete(listener);
  }

  onHarnesses(listener: (harnesses: HarnessInfo[]) => void): () => void {
    this.harnessListeners.add(listener);
    return () => void this.harnessListeners.delete(listener);
  }

  /** Starts connecting; idempotent. */
  connect(): void {
    if (!this.stopped) return;
    this.stopped = false;
    void this.attempt();
  }

  /** Closes the socket and stops reconnecting. Subscriptions are kept for a later `connect()`. */
  close(): void {
    this.stopped = true;
    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
    this.reconnectTimer = null;
    this.socket?.close();
    this.socket = null;
    this.setState("closed");
  }

  /** Subscribes to a chat. The listener gets a snapshot first, then events; on reconnect, a snapshot again. */
  open(chatId: string, listener: ChatListener): () => void {
    const subscription: Subscription = { listener, seq: -1, opened: false };
    this.subscriptions.set(chatId, subscription);
    if (this._state === "open") void this.openOne(chatId, subscription);
    return () => {
      if (this.subscriptions.get(chatId) !== subscription) return;
      this.subscriptions.delete(chatId);
      if (this._state === "open") void this.request("chats.close", { chatId }).catch(() => {});
    };
  }

  /** A subscription's listener applies the snapshot; this is what lets `turn.send` auto-subscribe a new chat. */
  subscribed(chatId: string): boolean {
    return this.subscriptions.has(chatId);
  }

  request<M extends Method>(method: M, params: MethodParams<M>): Promise<MethodResult<M>> {
    const socket = this.socket;
    if (!socket || socket.readyState !== socket.OPEN) {
      return Promise.reject(new AgentChatError("disconnected", "Agent host is not connected"));
    }
    const id = String(++this.nextId);
    const message: ClientMsg = { t: "req", id, method, params };
    return new Promise<MethodResult<M>>((resolve, reject) => {
      const timer = setTimeout(() => {
        if (this.pending.delete(id)) reject(new AgentChatError("internal", `${method} timed out`));
      }, REQUEST_TIMEOUT_MS);
      this.pending.set(id, {
        resolve: (value) => {
          clearTimeout(timer);
          resolve(value as MethodResult<M>);
        },
        reject: (error) => {
          clearTimeout(timer);
          reject(error);
        },
      });
      socket.send(JSON.stringify(message));
    });
  }

  private setState(state: ConnectionState): void {
    if (this._state === state) return;
    this._state = state;
    for (const listener of this.stateListeners) listener(state);
  }

  private async attempt(): Promise<void> {
    if (this.stopped) return;
    this.setState("connecting");
    let url: string | null = null;
    try {
      url = await this.options.resolveEndpoint();
    } catch {
      url = null;
    }
    if (this.stopped) return;
    if (!url) {
      this.setState("unavailable");
      this.scheduleReconnect();
      return;
    }
    const WS = this.options.WebSocket ?? globalThis.WebSocket;
    let socket: WebSocket;
    try {
      socket = new WS(url);
    } catch {
      this.setState("closed");
      this.scheduleReconnect();
      return;
    }
    this.socket = socket;
    socket.onopen = () => {
      if (this.socket !== socket) return;
      this.backoff = this.options.minBackoffMs ?? 500;
      this.setState("open");
      for (const [chatId, subscription] of this.subscriptions) {
        subscription.opened = false;
        void this.openOne(chatId, subscription);
      }
    };
    socket.onmessage = (event) => {
      if (this.socket !== socket) return;
      this.handle(String(event.data));
    };
    socket.onclose = () => {
      if (this.socket !== socket) return;
      this.socket = null;
      this.failPending(new AgentChatError("disconnected", "Agent host disconnected"));
      this.setState("closed");
      this.scheduleReconnect();
    };
    socket.onerror = () => {
      // `onclose` follows and does the work.
    };
  }

  private scheduleReconnect(): void {
    if (this.stopped || this.reconnectTimer) return;
    const delay = this.backoff;
    this.backoff = Math.min(this.backoff * 2, this.options.maxBackoffMs ?? 5000);
    this.reconnectTimer = setTimeout(() => {
      this.reconnectTimer = null;
      void this.attempt();
    }, delay);
  }

  private failPending(error: Error): void {
    const pending = [...this.pending.values()];
    this.pending.clear();
    for (const entry of pending) entry.reject(error);
  }

  private async openOne(chatId: string, subscription: Subscription): Promise<void> {
    try {
      const snapshot = await this.request("chats.open", { chatId });
      if (this.subscriptions.get(chatId) !== subscription) return;
      subscription.seq = snapshot.seq;
      subscription.opened = true;
      subscription.listener({ type: "snapshot", snapshot });
    } catch (error) {
      // A deleted chat, or a socket that went away: the next reconnect retries, a
      // `not-found` means the subscription is dead.
      if (error instanceof AgentChatError && error.code === "not-found") {
        this.subscriptions.delete(chatId);
      }
    }
  }

  private handle(raw: string): void {
    let message: HostMsg;
    try {
      message = JSON.parse(raw) as HostMsg;
    } catch {
      return;
    }
    switch (message.t) {
      case "res": {
        const entry = this.pending.get(message.id);
        if (!entry) return;
        this.pending.delete(message.id);
        if (message.ok) entry.resolve(message.data);
        else entry.reject(new AgentChatError(message.error.code, message.error.message));
        return;
      }
      case "event": {
        const subscription = this.subscriptions.get(message.chatId);
        if (!subscription || !subscription.opened || message.seq <= subscription.seq) return;
        subscription.seq = message.seq;
        subscription.listener({ type: "event", seq: message.seq, event: message.event });
        return;
      }
      case "harnesses": {
        this._harnesses = message.harnesses;
        for (const listener of this.harnessListeners) listener(message.harnesses);
        return;
      }
    }
  }
}