Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

10.2 KB
Raw Blame
import {
  type AgentBridgeEvent,
  type ApprovalOutcome,
  EVICTION_TAKEN_OVER,
  type SessionCommand,
  type SwitchEventStreamDeps,
} from '@sandboxaq/switch-agent-runtime';
import { z } from 'zod';
import type { AgentEventStream, AgentStreamDeps, OpenAgentStream } from './agent-host';

/**
 * The agent controller's hub, over a WebSocket on the controller's loopback
 * relay: how an agent host in a process of its own (an `isolated` agent) hears
 * its agent's events. The controller holds the agent's connection to Switch
 * and hands each event to the hub; the hub hands it here, one at a time, and
 * counts it taken once this side's handler has resolved, exactly as it does
 * for an agent host in the controller's own process.
 *
 * Every request the hub makes carries an `id` and is answered with `done`;
 * `placements` from this side is answered with `result`. The agent is the one
 * the bearer token names.
 */
export const HUB_PATH = '/hub';
export const HUB_PROTOCOL = 1;

/** Closes the hub sends. */
export const HUB_CLOSE = {
  /** The controller is stopping or restarting: reconnect soon. */
  restarting: 1012,
  /** A newer agent host for the same agent took the hub over: stand down. */
  takenOver: 4409,
  /** The hello was missing, malformed, or named a protocol the hub does not speak. */
  refused: 4400,
} as const;

const placementsSchema = z.record(z.string().min(1), z.string().min(1));

export const hubClientMessageSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('hello'),
    protocol: z.number().int(),
    startCursor: z.number().int().nonnegative().nullable(),
    placements: placementsSchema,
  }),
  z.object({ type: z.literal('done'), id: z.number().int(), error: z.string().optional() }),
  z.object({ type: z.literal('placements'), id: z.number().int(), placements: placementsSchema }),
]);
export type HubClientMessage = z.infer<typeof hubClientMessageSchema>;

export type HubGap = Parameters<SwitchEventStreamDeps['onGap']>[0];

export type HubServerMessage =
  | { type: 'connected' }
  | { type: 'disconnected'; error: string }
  | { type: 'event'; id: number; event: AgentBridgeEvent }
  | { type: 'gap'; id: number; gap: HubGap }
  | { type: 'session_command'; id: number; command: SessionCommand }
  | { type: 'approval_outcome'; id: number; outcome: ApprovalOutcome }
  | { type: 'room_gone'; id: number; roomId: string; sessionId: string }
  | { type: 'result'; id: number; error?: string; refusedRooms?: string[] };

/** Node's WebSocket, which, unlike a browser's, takes request headers. */
type HeaderedWebSocket = new (url: string, init: { headers: Record<string, string> }) => WebSocket;

const INITIAL_BACKOFF_MS = 250;
const MAX_BACKOFF_MS = 5_000;

/**
 * Opens the agent's stream on the controller's hub at `url`
 * (`ws://127.0.0.1:<relay port>/hub`), with the relay token the agent host
 * was given.
 */
export function openHubStream(url: string): OpenAgentStream {
  return (deps) => new HubEventStream(url, deps);
}

class HubEventStream implements AgentEventStream {
  /** The agent host, not Switch, tells a room when it starts a session for it. */
  readonly announcesSessionStarts = true;
  /** The controller's relay names each call's room from the placements. */
  readonly placementsNameCallRooms = true;
  private started = false;
  private socket: WebSocket | null = null;
  /** The last sequence this side has handled; sent on every hello. */
  private cursor: number | null;
  private placements: Record<string, string> = {};
  private nextId = 0;
  private readonly placementCalls = new Map<
    number,
    (answer: { error?: string; refusedRooms?: string[] }) => void
  >();
  /** Requests are handled one at a time, in the order they came. */
  private handling: Promise<void> = Promise.resolve();
  private standingDown = false;

  constructor(
    private readonly url: string,
    private readonly deps: AgentStreamDeps
  ) {
    this.cursor = deps.startCursor ?? null;
  }

  start(): void {
    if (this.started) return;
    this.started = true;
    void this.run();
  }

  // Switch decides who may start a session from the agent's binding.
  setSpawnCapable(): void {}

  async replacePlacements(placements: Record<string, string>): Promise<{ refusedRooms: string[] }> {
    this.placements = { ...placements };
    const socket = this.socket;
    // Not connected: the next hello carries them, but until then the relay
    // names no room for the sessions they move.
    if (!socket || socket.readyState !== WebSocket.OPEN)
      throw new Error(
        'the agent controller hub is not connected; the placements are stated when it reconnects'
      );
    const id = ++this.nextId;
    const answer = await new Promise<{ error?: string; refusedRooms?: string[] }>((resolve) => {
      this.placementCalls.set(id, resolve);
      socket.send(JSON.stringify({ type: 'placements', id, placements }));
    });
    if (answer.error !== undefined) throw new Error(answer.error);
    return { refusedRooms: answer.refusedRooms ?? [] };
  }

  private async run(): Promise<void> {
    const { signal, log } = this.deps;
    let backoff = INITIAL_BACKOFF_MS;
    let failures = 0;
    while (!signal.aborted && !this.standingDown) {
      const { code, reason, helloed } = await this.connectOnce();
      if (signal.aborted) return;
      if (code === HUB_CLOSE.takenOver) {
        this.standingDown = true;
        this.deps.onEvicted({
          code: EVICTION_TAKEN_OVER,
          reason: reason || 'another agent host for this agent took the controller hub over',
          roomId: null,
        });
        return;
      }
      const error = reason || `the agent controller hub closed (${code})`;
      this.deps.onDisconnected?.({ error });
      if (helloed) {
        backoff = INITIAL_BACKOFF_MS;
        failures = 0;
      }
      failures++;
      // The first failure, then powers of two: a long outage costs a few lines.
      if ((failures & (failures - 1)) === 0)
        log.warn(`The agent controller hub is unreachable (${error}); retrying.`);
      const wait = code === HUB_CLOSE.restarting ? INITIAL_BACKOFF_MS : backoff;
      await sleep(Math.round(wait * (0.5 + Math.random() * 0.5)), signal);
      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
    }
  }

  /** One socket, from open to close. */
  private connectOnce(): Promise<{ code: number; reason: string; helloed: boolean }> {
    return new Promise((resolve) => {
      const Socket = (globalThis as { WebSocket?: HeaderedWebSocket }).WebSocket;
      if (!Socket) throw new Error('The agent controller hub needs Node 22 or newer.');
      const socket = new Socket(this.url, {
        headers: { Authorization: `Bearer ${this.deps.creds.token}` },
      });
      this.socket = socket;
      let helloed = false;
      const abort = () => socket.close(1000, 'the agent host is stopping');
      this.deps.signal.addEventListener('abort', abort, { once: true });
      socket.addEventListener('open', () => {
        helloed = true;
        socket.send(
          JSON.stringify({
            type: 'hello',
            protocol: HUB_PROTOCOL,
            startCursor: this.cursor,
            placements: this.placements,
          })
        );
      });
      socket.addEventListener('message', (message) => {
        let parsed: HubServerMessage;
        try {
          parsed = JSON.parse(String(message.data)) as HubServerMessage;
        } catch {
          this.deps.log.error('Dropped a message from the agent controller hub that is not JSON');
          return;
        }
        if (parsed.type === 'result') {
          const call = this.placementCalls.get(parsed.id);
          this.placementCalls.delete(parsed.id);
          call?.({ error: parsed.error, refusedRooms: parsed.refusedRooms });
          return;
        }
        this.handling = this.handling.then(() => this.handle(socket, parsed));
      });
      socket.addEventListener('close', (event) => {
        this.deps.signal.removeEventListener('abort', abort);
        if (this.socket === socket) this.socket = null;
        // The placements a call was sending go again with the next hello.
        for (const call of this.placementCalls.values())
          call({
            error:
              'the agent controller hub closed before it took the placements; they are stated again when it reconnects',
          });
        this.placementCalls.clear();
        resolve({ code: event.code, reason: event.reason, helloed });
      });
      // A failed handshake also closes; the close says what happened.
      socket.addEventListener('error', () => {});
    });
  }

  private async handle(socket: WebSocket, message: HubServerMessage): Promise<void> {
    const { deps } = this;
    if (message.type === 'connected') return deps.onConnected?.();
    if (message.type === 'disconnected') return deps.onDisconnected?.({ error: message.error });
    if (message.type === 'result') return;
    let error: string | undefined;
    try {
      switch (message.type) {
        case 'event':
          await deps.onEvent(message.event);
          if (typeof message.event.sequence === 'number')
            this.cursor = Math.max(this.cursor ?? 0, message.event.sequence);
          break;
        case 'gap':
          await deps.onGap(message.gap);
          if (message.gap.resumedAt !== undefined) this.cursor = message.gap.resumedAt;
          break;
        case 'session_command':
          await deps.onSessionCommand?.(message.command);
          break;
        case 'approval_outcome':
          await deps.onApprovalOutcome?.(message.outcome);
          break;
        case 'room_gone':
          await deps.onRoomGone?.({ roomId: message.roomId, sessionId: message.sessionId });
          break;
      }
    } catch (failure) {
      error = failure instanceof Error ? failure.message : String(failure);
    }
    if (socket.readyState === WebSocket.OPEN)
      socket.send(JSON.stringify({ type: 'done', id: message.id, ...(error ? { error } : {}) }));
  }
}

function sleep(ms: number, signal: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal.aborted) return resolve();
    const timer = setTimeout(done, ms);
    function done() {
      clearTimeout(timer);
      signal.removeEventListener('abort', done);
      resolve();
    }
    signal.addEventListener('abort', done, { once: true });
  });
}