Skip to content

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

14.2 KB
Raw Blame
import { setTimeout as delay } from 'node:timers/promises';
import type {
  AgentBridgeEvent,
  ApprovalOutcome,
  SessionCommand,
  SwitchEventStreamDeps,
} from '@sandboxaq/switch-agent-runtime';
import type { AgentStreamDeps } from '@switch-console/agent-providers';
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { AgentHub } from './agent-hub';
import { silentLogger } from './log';
import type { AgentEventFrame } from './schemas';

const AGENT = 'agent-1';

function message(seq: number, addressed: boolean, room = 'room-a'): AgentEventFrame {
  return {
    agent_id: AGENT,
    seq,
    event: {
      type: 'message',
      room_id: room,
      payload: { addressed, message_id: `$m${seq}`, body: `hello ${seq}` },
    },
  };
}

async function waitFor(condition: () => boolean, what: string): Promise<void> {
  const deadline = Date.now() + 5_000;
  while (!condition()) {
    if (Date.now() > deadline) throw new Error(`Timed out waiting for ${what}.`);
    await delay(5);
  }
}

let hub: AgentHub;
let saved: [string, number][];
let changes: number;

beforeEach(() => {
  saved = [];
  changes = 0;
  hub = new AgentHub({
    log: silentLogger,
    onCursor: (agentId, cursor) => saved.push([agentId, cursor]),
    onChange: () => changes++,
    bufferLimit: 5,
  });
});

/** A watcher as `runAgentHost` opens its stream, recording what it hears. */
function watcher(overrides: Partial<AgentStreamDeps> = {}) {
  const seen = {
    events: [] as AgentBridgeEvent[],
    gaps: [] as Parameters<SwitchEventStreamDeps['onGap']>[0][],
    commands: [] as SessionCommand[],
    outcomes: [] as ApprovalOutcome[],
    connected: 0,
    disconnected: [] as string[],
  };
  const controller = new AbortController();
  const stream = hub.open(AGENT, {
    creds: { agentId: AGENT, apiEndpoint: 'http://127.0.0.1:1', token: 'swlr_x' },
    connectionId: 'connection-1',
    scope: 'all',
    filter: 'addressed',
    spawnCapable: true,
    rooms: [],
    onEvent: (event) => void seen.events.push(event),
    onGap: (gap) => void seen.gaps.push(gap),
    onEvicted: () => {},
    onSessionCommand: (command) => void seen.commands.push(command),
    onApprovalOutcome: (outcome) => void seen.outcomes.push(outcome),
    onConnected: () => void seen.connected++,
    onDisconnected: ({ error }) => void seen.disconnected.push(error),
    log: { debug: () => {}, warn: () => {}, error: () => {} },
    signal: controller.signal,
    ...overrides,
  });
  return { stream, seen, stop: () => controller.abort() };
}

describe('handing events to the watcher', () => {
  it('connects once the agent is attached, then hands over addressed events in order and confirms each', async () => {
    const { stream, seen } = watcher();
    stream.start();
    expect(seen.connected).toBe(0);
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    expect(seen.connected).toBe(1);
    expect(hub.attached(AGENT)).toBe(true);
    hub.ingest(message(1, true));
    hub.ingest(message(2, false));
    hub.ingest(message(3, true));
    await waitFor(() => saved.length === 3, 'every event confirmed');
    expect(seen.events.map((event) => event.sequence)).toEqual([1, 3]);
    expect(seen.events[0]).toMatchObject({ type: 'message', room_id: 'room-a' });
    expect(saved).toEqual([
      [AGENT, 1],
      [AGENT, 2],
      [AGENT, 3],
    ]);
    expect(hub.cursors()).toEqual({ [AGENT]: 3 });
  });

  it('confirms an event only once the watcher has taken it', async () => {
    let release: () => void = () => {};
    const taken = new Promise<void>((resolve) => (release = resolve));
    const { stream } = watcher({ onEvent: () => taken });
    stream.start();
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    hub.ingest(message(1, true));
    await delay(20);
    expect(saved).toEqual([]);
    release();
    await waitFor(() => saved.length === 1, 'the event confirmed');
  });

  it('holds events while no watcher runs, and hands them over from its own cursor when it starts', async () => {
    hub.setCursor(AGENT, 2);
    hub.streamAttached();
    hub.attach(AGENT, 2, ['room-a']);
    hub.ingest(message(3, true));
    hub.ingest(message(4, true));
    expect(hub.attached(AGENT)).toBe(false);
    const { stream, seen } = watcher({ startCursor: 3 });
    stream.start();
    await waitFor(() => seen.events.length === 1, 'the event past its cursor');
    expect(seen.events[0]!.sequence).toBe(4);
    expect(seen.connected).toBe(1);
  });

  it("hands a new agent's first watcher what arrived while it was starting", async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    // A template's kickoff, posted the moment the agent exists, before its
    // host is up and with no cursor of its own.
    hub.ingest(message(1, true));
    const { stream, seen } = watcher();
    stream.start();
    await waitFor(() => seen.events.length === 1, 'the kickoff');
    expect(seen.events[0]!.sequence).toBe(1);
    expect(seen.gaps).toEqual([]);
  });

  it('starts a later watcher with no cursor at the newest event, as before', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    const first = watcher();
    first.stream.start();
    hub.ingest(message(1, true));
    await waitFor(() => first.seen.events.length === 1, 'the first event');
    first.stop();
    hub.ingest(message(2, true));
    const second = watcher();
    second.stream.start();
    hub.ingest(message(3, true));
    await waitFor(() => second.seen.events.length === 1, 'the event after it started');
    expect(second.seen.events[0]!.sequence).toBe(3);
  });

  it('tells a watcher starting from before what is held that it missed events', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    for (let seq = 1; seq <= 8; seq++) hub.ingest(message(seq, true));
    const { stream, seen } = watcher({ startCursor: 0 });
    stream.start();
    await waitFor(() => seen.events.length === 5, 'the five events still held');
    expect(seen.gaps).toEqual([
      expect.objectContaining({ fromSequence: 0, resumedAt: 3, cursorReset: false }),
    ]);
    expect(seen.events.map((event) => event.sequence)).toEqual([4, 5, 6, 7, 8]);
  });

  it('drops what a reattached stream replays, and a gap behind what it holds', async () => {
    const { stream, seen } = watcher();
    stream.start();
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    hub.ingest(message(1, true));
    hub.ingest(message(2, true));
    await waitFor(() => seen.events.length === 2, 'both events');
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    hub.ingest(message(1, true));
    hub.ingest(message(2, true));
    hub.gap({ agent_id: AGENT, from_sequence: 0, resumed_at: 1, reason: 'replayed' });
    hub.ingest(message(3, true));
    await waitFor(() => seen.events.length === 3, 'the new event');
    expect(seen.events.map((event) => event.sequence)).toEqual([1, 2, 3]);
    expect(seen.gaps).toEqual([]);
  });

  it('passes a gap ahead of what it holds in order, and a reset as a cursor reset', async () => {
    const { stream, seen } = watcher();
    stream.start();
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    hub.ingest(message(1, true));
    hub.gap({ agent_id: AGENT, from_sequence: 1, resumed_at: 4, reason: 'lost' });
    hub.ingest(message(5, true));
    await waitFor(() => seen.events.length === 2, 'the event after the gap');
    expect(seen.gaps).toEqual([
      expect.objectContaining({ fromSequence: 1, resumedAt: 4, reason: 'lost' }),
    ]);

    hub.gap({
      agent_id: AGENT,
      from_sequence: 5,
      resumed_at: 2,
      all_rooms: true,
      rooms: ['room-a'],
      reason: 'switch restarted',
    });
    await waitFor(() => seen.gaps.length === 2, 'the reset');
    expect(seen.gaps[1]).toMatchObject({ resumedAt: 2, cursorReset: true });
    expect(saved.at(-1)).toEqual([AGENT, 2]);
    hub.ingest(message(3, true));
    await waitFor(() => seen.events.length === 3, 'the event after the reset');
    expect(seen.events.at(-1)!.sequence).toBe(3);
  });
});

describe('the connection', () => {
  it('tells the watcher when Switch detaches the agent or the controller stream drops, and when it is back', () => {
    const { stream, seen } = watcher();
    stream.start();
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    hub.detach(AGENT, 'unassigned');
    expect(seen.disconnected).toEqual(['Switch detached the agent from this controller.']);
    hub.attach(AGENT, 0, ['room-a']);
    hub.setUpstream(false);
    expect(seen.disconnected.at(-1)).toBe('The controller is reconnecting to Switch.');
    expect(hub.attached(AGENT)).toBe(false);
    hub.streamAttached();
    expect(hub.attached(AGENT)).toBe(false);
    hub.attach(AGENT, 0, ['room-a']);
    expect(seen.connected).toBe(3);
  });

  it('hears nothing more once replaced by a newer watcher of the agent, or once stopped', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    const first = watcher();
    first.stream.start();
    const second = watcher();
    second.stream.start();
    hub.ingest(message(1, true));
    await waitFor(() => second.seen.events.length === 1, 'the newer watcher');
    expect(first.seen.events).toEqual([]);
    second.stop();
    hub.ingest(message(2, true));
    await delay(20);
    expect(second.seen.events).toHaveLength(1);
    expect(hub.attached(AGENT)).toBe(false);
  });
});

describe('placements', () => {
  it('names a session’s room from its agent host, and forgets it when the agent host stops', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a', 'room-b']);
    const { stream, stop } = watcher();
    stream.start();
    await stream.replacePlacements({ 'session-1': 'room-b', 'session-2': 'room-a' });
    expect(hub.roomFor(AGENT, 'session-1')).toBe('room-b');
    expect(hub.roomFor(AGENT, 'session-9')).toBeNull();
    expect(hub.roomFor(AGENT, null)).toBeNull();
    await stream.replacePlacements({ 'session-1': 'room-b' });
    expect(hub.roomFor(AGENT, null)).toBe('room-b');
    expect(changes).toBeGreaterThan(0);
    stop();
    expect(hub.roomFor(AGENT, 'session-1')).toBeNull();
  });

  it('places the sessions in rooms the agent is in, leaving out and naming one that is gone, every time', async () => {
    const warn = vi.spyOn(silentLogger, 'warn');
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    const { stream } = watcher();
    stream.start();
    for (let i = 0; i < 3; i++) {
      // A session left placed in a room since deleted, beside one in a live room.
      await expect(
        stream.replacePlacements({ 'session-old': 'room-deleted', 'session-1': 'room-a' })
      ).resolves.toEqual({ refusedRooms: ['room-deleted'] });
      // The live session's room tools carry its room.
      expect(hub.roomFor(AGENT, 'session-1')).toBe('room-a');
      expect(hub.roomFor(AGENT, 'session-old')).toBeNull();
    }
    // Said once for the room, not on every statement.
    expect(warn.mock.calls.filter(([message]) => String(message).includes('not in'))).toHaveLength(
      1
    );
    warn.mockRestore();
  });

  it('tells the agent host when a room a session is placed in stops being the agent’s', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a', 'room-b']);
    const gone: { roomId: string; sessionId: string }[] = [];
    const { stream } = watcher({ onRoomGone: (info) => void gone.push(info) });
    stream.start();
    await stream.replacePlacements({ 'session-1': 'room-a', 'session-2': 'room-b' });
    // The chat in room-b was deleted: Switch's rooms for the agent no longer have it.
    hub.setRooms(AGENT, ['room-a']);
    expect(gone).toEqual([{ roomId: 'room-b', sessionId: 'session-2' }]);
    expect(hub.roomFor(AGENT, 'session-2')).toBeNull();
    expect(hub.roomFor(AGENT, 'session-1')).toBe('room-a');
  });

  it('refuses placements from an agent host a newer one replaced, rather than dropping them', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    const older = watcher();
    older.stream.start();
    const newer = watcher();
    newer.stream.start();
    await expect(older.stream.replacePlacements({ 'session-1': 'room-a' })).rejects.toThrow(
      /a newer one does/
    );
    expect(hub.roomFor(AGENT, 'session-1')).toBeNull();
  });

  it('refuses one room for two sessions', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    const { stream } = watcher();
    stream.start();
    await expect(
      stream.replacePlacements({ 'session-1': 'room-a', 'session-2': 'room-a' })
    ).rejects.toThrow(/more than one session/);
  });
});

describe('room controls and approvals', () => {
  it('hands a room control to the agent host with its room, for it to pick the session', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a', 'room-b']);
    const { stream, seen } = watcher();
    stream.start();
    hub.sessionCommand({
      agent_id: AGENT,
      room_id: 'room-a',
      command: { commandId: 'command-1', sessionId: null, body: { type: 'session.reset' } },
    });
    hub.sessionCommand({
      agent_id: AGENT,
      room_id: null,
      command: { commandId: 'command-2', origin: { roomId: 'room-b' } },
    });
    hub.sessionCommand({ agent_id: AGENT, room_id: null, command: { commandId: 'command-3' } });
    await waitFor(() => seen.commands.length === 2, 'both room controls');
    await delay(20);
    expect(seen.commands).toEqual([
      expect.objectContaining({ commandId: 'command-1', sessionId: null, roomId: 'room-a' }),
      expect.objectContaining({ commandId: 'command-2', sessionId: null, roomId: 'room-b' }),
    ]);
  });

  it('passes approval outcomes to the running agent host', async () => {
    hub.streamAttached();
    hub.attach(AGENT, 0, ['room-a']);
    hub.approvalOutcome({
      agent_id: AGENT,
      outcome: { session_id: 's', request_id: 'r0', state: 'answered' },
    });
    const { stream, seen } = watcher();
    stream.start();
    hub.approvalOutcome({
      agent_id: AGENT,
      outcome: { session_id: 's', request_id: 'r1', state: 'answered', answer: 'yes' },
    });
    await waitFor(() => seen.outcomes.length === 1, 'the outcome');
    expect(seen.outcomes[0]).toEqual({
      session_id: 's',
      request_id: 'r1',
      state: 'answered',
      answer: 'yes',
      answered_by: null,
      answered_at: null,
    });
  });
});