Skip to content

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

20.2 KB
Raw Blame
import type { ChildProcess } from 'node:child_process';
import { EventEmitter } from 'node:events';
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { connect } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PassThrough } from 'node:stream';
import { afterEach, expect, it, vi } from 'vitest';
import { z } from 'zod';
import { AttachmentTransfers } from './attachment-transfers';
import { CONTROL_FILE, ControlClient, ensureSessions, serveControl } from './control';
import type { Supervision } from './launch';
import { SessionHostFailedError, SessionLinks } from './session-channel';
import { WatcherControl } from './watcher-tools';

const paths = vi.hoisted(() => ({ base: '' }));
const launched = vi.hoisted(() => ({ ensureSharedProcess: vi.fn() }));
vi.mock('./launch', () => ({
  ensureSharedProcess: launched.ensureSharedProcess,
  sharedSessionRoot: (id: string) => join(paths.base, id),
  liveSupervisor: async (root: string) =>
    (await readFile(join(root, 'running'), 'utf8').catch(() => null)) ? { build: 'b' } : null,
}));

const roots: string[] = [];
afterEach(async () => {
  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true });
});

const event = (sequence: number) => ({
  contractVersion: 1,
  eventId: `event-${sequence}`,
  sessionId: 'session',
  sequence,
  occurredAt: '2026-09-24T12:00:00.000Z',
  body: { type: 'notice', level: 'info', code: 'X', message: 'hi' },
});

/** A session host child answering snapshots with its own name. */
function host() {
  const child = new EventEmitter() as EventEmitter & {
    connected: boolean;
    send: (message: unknown, callback: (error: Error | null) => void) => boolean;
  };
  child.connected = true;
  child.send = (message, callback) => {
    callback(null);
    const { id } = message as { id: number };
    setImmediate(() => child.emit('message', { kind: 'reply', id, ok: true, value: 'snapshot' }));
    return true;
  };
  return child;
}

/** Gives `sessionId` a saved configuration naming `agentId`, as its host's launch writes it. */
async function saved(base: string, sessionId: string, agentId: string): Promise<void> {
  await mkdir(join(base, sessionId), { recursive: true });
  await writeFile(
    join(base, sessionId, 'config.json'),
    JSON.stringify({ session: { sessionId, agentId } })
  );
}

async function started() {
  const base = await mkdtemp(join(tmpdir(), 'control-'));
  roots.push(base);
  paths.base = base;
  for (const id of ['session', 'stopped', 'gone', 'elsewhere']) await saved(base, id, 'agent');
  await saved(base, 'theirs', 'other');
  const links = new SessionLinks();
  const ensure = vi.fn(async () => ({ created: true }));
  const stop = new AbortController();
  const watcher = new WatcherControl();
  const transfers = new AttachmentTransfers(base);
  const serving = serveControl(
    base,
    { agentId: 'agent', links, ensure, watcher, transfers },
    stop.signal
  );
  await vi.waitFor(async () =>
    expect(await readFile(join(base, CONTROL_FILE), 'utf8')).toBeTruthy()
  );
  const control = JSON.parse(await readFile(join(base, CONTROL_FILE), 'utf8')) as {
    port: number;
    token: string;
  };
  const client = (token = control.token) => {
    const socket = connect(control.port, '127.0.0.1');
    return new ControlClient(socket, token);
  };
  return { base, links, ensure, stop, serving, client, watcher, control };
}

it('relays requests to a session host and its events back', async () => {
  const { base, links, ensure, stop, serving, client } = await started();
  const sessionRoot = join(base, 'session');
  await mkdir(sessionRoot, { recursive: true });
  await writeFile(join(sessionRoot, 'running'), 'yes');
  const child = host();
  links.attach(sessionRoot, child as unknown as ChildProcess);
  child.emit('message', { kind: 'ready' });

  const console = client();
  await console.ready;
  expect(await console.request('session', { type: 'snapshot' })).toBe('snapshot');

  const heard: number[] = [];
  const unsubscribe = await console.subscribe(
    'session',
    (pushed) => heard.push(pushed.sequence),
    () => {}
  );
  child.emit('message', { kind: 'event', event: event(1) });
  await vi.waitFor(() => expect(heard).toEqual([1]));
  unsubscribe();

  expect(
    await console.ensure({ config: {}, resuming: false, restart: false, startSource: 'room' })
  ).toEqual({
    created: true,
  });
  expect(ensure).toHaveBeenCalledWith({
    config: {},
    resuming: false,
    restart: false,
    startSource: 'room',
  });

  console.close();
  stop.abort();
  await serving;
  await expect(readFile(join(base, CONTROL_FILE))).rejects.toMatchObject({ code: 'ENOENT' });
});

it('passes on why a session host failed, to a waiting request and to subscribers', async () => {
  const { base, links, stop, serving, client } = await started();
  const sessionRoot = join(base, 'session');
  await mkdir(join(sessionRoot, 'supervisor'), { recursive: true });
  await writeFile(join(sessionRoot, 'running'), 'yes');
  const child = host();
  links.attach(sessionRoot, child as unknown as ChildProcess);

  const console = client();
  await console.ready;
  const failures: (string | null)[] = [];
  const unsubscribe = await console.subscribe(
    'session',
    () => {},
    (failure) => failures.push(failure)
  );
  expect(failures).toEqual([null]);
  const request = console.request('session', { type: 'snapshot' });
  const refused = expect(request).rejects.toBeInstanceOf(SessionHostFailedError);
  await writeFile(
    join(sessionRoot, 'supervisor', 'failure.json'),
    JSON.stringify({ message: 'Sign in on the execution machine with claude auth login.' })
  );
  child.emit('exit', 1, null);
  await refused;
  await vi.waitFor(() =>
    expect(failures).toEqual([null, 'Sign in on the execution machine with claude auth login.'])
  );
  unsubscribe();

  // A subscriber arriving after the failure hears it too.
  const late: (string | null)[] = [];
  const unsubscribeLate = await console.subscribe(
    'session',
    () => {},
    (failure) => late.push(failure)
  );
  expect(late).toEqual(['Sign in on the execution machine with claude auth login.']);
  // And hears it cleared once a host comes up again.
  const next = host();
  links.attach(sessionRoot, next as unknown as ChildProcess);
  next.emit('message', { kind: 'ready' });
  await vi.waitFor(() =>
    expect(late).toEqual(['Sign in on the execution machine with claude auth login.', null])
  );
  unsubscribeLate();

  console.close();
  stop.abort();
  await serving;
});

it('answers at once for a session nothing is running', async () => {
  const { stop, serving, client } = await started();
  const console = client();
  await console.ready;
  await expect(console.request('stopped', { type: 'snapshot' })).rejects.toThrow('not running');
  console.close();
  stop.abort();
  await serving;
});

it('never reads or commands a session of another agent', async () => {
  const { base, links, stop, serving, client, watcher } = await started();
  const sessionRoot = join(base, 'theirs');
  await writeFile(join(sessionRoot, 'running'), 'yes');
  const child = host();
  const sent = vi.spyOn(child, 'send');
  links.attach(sessionRoot, child as unknown as ChildProcess);
  child.emit('message', { kind: 'ready' });
  const placed = vi.fn();
  const forgot = vi.fn();
  const unbind = watcher.bind({ place: placed, forget: forgot, warm: vi.fn() });

  const console = client();
  await console.ready;
  const refused = 'not a session of agent agent';
  for (const id of ['theirs', 'unknown']) {
    await expect(console.request(id, { type: 'snapshot' })).rejects.toThrow(refused);
    if (id === 'theirs')
      await expect(
        console.subscribe(
          id,
          () => {},
          () => {}
        )
      ).rejects.toThrow(refused);
    // No public method sends these two; the port must still refuse them.
    await expect(console['call']({ journal: id })).rejects.toThrow(refused);
    const chunk = {
      transferId: 't1',
      sessionId: id,
      name: 'a.txt',
      mimeType: 'text/plain',
      size: 1,
      sha256: '0'.repeat(64),
      index: 0,
      count: 1,
      chunk: 'YQ==',
    };
    await expect(console['call']({ attachment: chunk })).rejects.toThrow(refused);
    await expect(console.place(id, 'room')).rejects.toThrow(refused);
    if (id === 'theirs') await expect(console.forget(id)).rejects.toThrow(refused);
    await expect(console.reasoning(id, null)).rejects.toThrow(refused);
  }
  expect(sent).not.toHaveBeenCalled();
  expect(placed).not.toHaveBeenCalled();
  expect(forgot).not.toHaveBeenCalledWith('theirs');

  unbind();
  console.close();
  stop.abort();
  await serving;
});

it('forgets a session with no config and waits on one until its config is saved', async () => {
  const { base, links, stop, serving, client, watcher } = await started();
  const forgot = vi.fn();
  const unbind = watcher.bind({ place: vi.fn(), forget: forgot, warm: vi.fn() });
  const console = client();
  await console.ready;

  await console.forget('deleted');
  expect(forgot).toHaveBeenCalledWith('deleted');

  const watch = async (id: string) => {
    const root = join(base, id);
    await mkdir(root, { recursive: true });
    const child = host();
    links.attach(root, child as unknown as ChildProcess);
    const heard: number[] = [];
    const failures: (string | null)[] = [];
    const off = await console.subscribe(
      id,
      (pushed) => heard.push(pushed.sequence),
      (failure) => failures.push(failure)
    );
    return { child, heard, failures, off };
  };

  const mine = await watch('starting');
  expect(mine.failures).toEqual([null]);
  mine.child.emit('message', { kind: 'event', event: event(1) });
  await new Promise((resolve) => setTimeout(resolve, 20));
  expect(mine.heard).toEqual([]);
  await saved(base, 'starting', 'agent');
  mine.child.emit('message', { kind: 'event', event: event(2) });
  await vi.waitFor(() => expect(mine.heard).toEqual([2]));
  mine.off();

  const foreign = await watch('claimed');
  await saved(base, 'claimed', 'other');
  foreign.child.emit('message', { kind: 'event', event: event(1) });
  await vi.waitFor(() =>
    expect(foreign.failures).toEqual([null, 'Session claimed is not a session of agent agent.'])
  );
  foreign.child.emit('message', { kind: 'event', event: event(2) });
  await new Promise((resolve) => setTimeout(resolve, 20));
  expect(foreign.heard).toEqual([]);
  await expect(console.place('claimed', 'room')).rejects.toThrow('not a session of agent agent');

  unbind();
  console.close();
  stop.abort();
  await serving;
});

it('refuses a client without the secret', async () => {
  const { stop, serving, client } = await started();
  await expect(client('wrong').ready).rejects.toThrow();
  stop.abort();
  await serving;
});

it('moves a room to a session through the watcher, and says why when it cannot', async () => {
  const { stop, serving, client, watcher } = await started();
  const console = client();
  await console.ready;
  await expect(console.place('session', 'room')).rejects.toThrow('room watcher is not running');
  const placed = vi.fn(async (sessionId: string, roomId: string) => ({
    sessionId,
    roomId,
    previous: null,
    displaced: 'other',
  }));
  const forgot = vi.fn(async () => {});
  const warmed = vi.fn(async (roomId: string) => `session-for-${roomId}`);
  const unbind = watcher.bind({ place: placed, forget: forgot, warm: warmed });
  await console.forget('gone');
  expect(forgot).toHaveBeenCalledWith('gone');
  expect(await console.warm('room')).toBe('session-for-room');
  expect(warmed).toHaveBeenCalledWith('room');
  expect(await console.place('session', 'room')).toEqual({
    sessionId: 'session',
    roomId: 'room',
    previous: null,
    displaced: 'other',
  });
  expect(placed).toHaveBeenCalledWith('session', 'room');
  placed.mockRejectedValueOnce(new Error('Switch refused to move room room'));
  await expect(console.place('session', 'room')).rejects.toThrow('Switch refused');
  unbind();
  console.close();
  stop.abort();
  await serving;
});

it('stops serving while Console still holds its connection open', async () => {
  const { base, stop, serving, client } = await started();
  const console = client();
  await console.ready;
  stop.abort();
  await serving;
  await expect(readFile(join(base, CONTROL_FILE))).rejects.toMatchObject({ code: 'ENOENT' });
  await expect(console.request('session', { type: 'snapshot' })).rejects.toThrow();
});

it('answers the watcher health and pushes every change to a client watching it', async () => {
  const { stop, serving, client, watcher } = await started();
  const console = client();
  await console.ready;
  expect(await console.health()).toMatchObject({
    state: 'not-running',
    detail: null,
    placements: {},
  });

  const heard: unknown[] = [];
  const stopWatching = await console.onHealth((health) => heard.push(health));
  watcher.report({ state: 'connecting', placements: { session: 'room' } });
  watcher.report({ state: 'connected' });
  // Nothing changed: nothing pushed.
  watcher.report({ state: 'connected', placements: { session: 'room' } });
  watcher.report({ state: 'disconnected', detail: 'HTTP 502: bad gateway' });
  await vi.waitFor(() => expect(heard).toHaveLength(3));
  expect(heard).toMatchObject([
    { state: 'connecting', detail: null, placements: { session: 'room' } },
    { state: 'connected', detail: null, placements: { session: 'room' } },
    { state: 'disconnected', detail: 'HTTP 502: bad gateway', placements: { session: 'room' } },
  ]);
  expect(await console.health()).toEqual(watcher.health());

  stopWatching();
  // The sidecar hears the unwatch before the next report.
  await console.health();
  watcher.report({ state: 'connected', detail: null });
  await console.health();
  expect(heard).toHaveLength(3);

  const closed = vi.fn();
  console.onClose(closed);
  console.close();
  await vi.waitFor(() => expect(closed).toHaveBeenCalledTimes(1));
  stop.abort();
  await serving;
});

it('still starts a session for a Console that sends no start source', async () => {
  // What a Console older than start sources writes: the same message, one key short.
  const { ensure, stop, serving, control } = await started();
  const socket = connect(control.port, '127.0.0.1');
  const replies: unknown[] = [];
  let buffered = '';
  socket.on('data', (chunk: Buffer) => {
    buffered += chunk.toString();
    let end: number;
    while ((end = buffered.indexOf('\n')) >= 0) {
      replies.push(JSON.parse(buffered.slice(0, end)));
      buffered = buffered.slice(end + 1);
    }
  });
  socket.write(`${JSON.stringify({ token: control.token })}\n`);
  socket.write(
    `${JSON.stringify({ id: 1, ensure: { config: {}, resuming: false, restart: false } })}\n`
  );

  await vi.waitFor(() =>
    expect(replies).toContainEqual({ id: 1, ok: true, value: { created: true } })
  );
  expect(ensure).toHaveBeenCalledWith({ config: {}, resuming: false, restart: false });

  socket.destroy();
  stop.abort();
  await serving;
});

const sessionConfig = {
  session: {
    sessionId: 'session-1',
    agentId: 'agent',
    hostId: 'host',
    epoch: 'initial',
    provider: 'codex',
    status: 'starting',
    connectivity: 'online',
    pendingRequestIds: [],
    capabilities: {
      input: 'queue',
      approvals: true,
      questions: true,
      interrupt: true,
      reset: false,
      compact: false,
      modelChange: false,
      attachmentMimeTypes: [],
    },
  },
  start: {
    provider: 'codex',
    input: {
      sessionId: 'session-1',
      cwd: '/work',
      runtimeMode: 'approval-required',
      env: {},
      mcpServers: {},
    },
  },
};

it('starts the session a sidecar is asked for with the start source it was given', async () => {
  paths.base = '/sessions';
  launched.ensureSharedProcess.mockReset().mockResolvedValue({ created: true });
  const supervision = { build: 'b' } as unknown as Supervision;

  await ensureSessions(supervision)({
    config: sessionConfig,
    resuming: false,
    restart: false,
    startSource: 'room',
  });

  expect(launched.ensureSharedProcess).toHaveBeenCalledWith(
    expect.objectContaining({
      root: join('/sessions', 'session-1'),
      watcher: false,
      supervision,
      startSource: 'room',
    })
  );
});

it('records a start source an older Console did not send as not known', async () => {
  launched.ensureSharedProcess.mockReset().mockResolvedValue({ created: true });

  await ensureSessions({ build: 'b' } as unknown as Supervision)({
    config: sessionConfig,
    resuming: false,
    restart: false,
  });

  expect(launched.ensureSharedProcess.mock.calls[0]![0]).toMatchObject({ startSource: null });
});

it('carries a start source Console could not name as null, which a resume always does', async () => {
  const { ensure, stop, serving, client } = await started();
  const console = client();
  await console.ready;

  await console.ensure({ config: {}, resuming: true, restart: false, startSource: null });

  expect(ensure).toHaveBeenCalledWith({
    config: {},
    resuming: true,
    restart: false,
    startSource: null,
  });
  console.close();
  stop.abort();
  await serving;
});

it('starts a session whose start source is newer than this sidecar, as not known', async () => {
  const { ensure, stop, serving, control } = await started();
  const socket = connect(control.port, '127.0.0.1');
  const replies: unknown[] = [];
  let buffered = '';
  socket.on('data', (chunk: Buffer) => {
    buffered += chunk.toString();
    let end: number;
    while ((end = buffered.indexOf('\n')) >= 0) {
      replies.push(JSON.parse(buffered.slice(0, end)));
      buffered = buffered.slice(end + 1);
    }
  });
  socket.write(`${JSON.stringify({ token: control.token })}\n`);
  socket.write(
    `${JSON.stringify({
      id: 1,
      ensure: { config: {}, resuming: false, restart: false, startSource: 'scheduled' },
    })}\n`
  );

  await vi.waitFor(() =>
    expect(replies).toContainEqual({ id: 1, ok: true, value: { created: true } })
  );
  expect(ensure).toHaveBeenCalledWith({
    config: {},
    resuming: false,
    restart: false,
    startSource: null,
  });

  socket.destroy();
  stop.abort();
  await serving;
});

it('answers a reasoning ask from the session host, and from no host with none', async () => {
  const { base, links, stop, serving, client, watcher } = await started();
  const sessionRoot = join(base, 'session');
  const list = { epoch: 'epoch', turns: [] };
  const child = host();
  const asked: unknown[] = [];
  child.send = (message, callback) => {
    callback(null);
    const { id, request } = message as { id: number; request: unknown };
    asked.push(request);
    setImmediate(() => child.emit('message', { kind: 'reply', id, ok: true, value: list }));
    return true;
  };
  links.attach(sessionRoot, child as unknown as ChildProcess);
  child.emit('message', { kind: 'ready' });

  const console = client();
  await console.ready;
  expect(await console.reasoning('session', ['turn'])).toEqual(list);
  expect(asked).toEqual([{ type: 'reasoning', turnIds: ['turn'] }]);
  expect(await console.reasoning('elsewhere', null)).toBeNull();
  expect(await console.request('session', { type: 'reasoning', turnIds: null })).toEqual(list);
  // A plain health ask is still a health ask.
  expect(await console.health()).toEqual(watcher.health());

  console.close();
  stop.abort();
  await serving;
});

it('reads as a health ask to a sidecar that predates reasoning, so its connection stays up', async () => {
  const stream = new PassThrough();
  const toSidecar: string[] = [];
  const duplex = Object.assign(stream, {
    write: (line: string) => {
      toSidecar.push(line);
      const message = JSON.parse(line) as Record<string, unknown>;
      // What an older sidecar parses the line as: its plain health message.
      const old = z.object({ id: z.number().int(), health: z.literal(true) }).safeParse(message);
      if ('token' in message) setImmediate(() => stream.emit('data', '{"authenticated":true}\n'));
      else if (old.success)
        setImmediate(() =>
          stream.emit(
            'data',
            `${JSON.stringify({ id: old.data.id, ok: true, value: { state: 'connected' } })}\n`
          )
        );
      return true;
    },
  });
  const console = new ControlClient(duplex, 'token');
  await console.ready;
  expect(await console.reasoning('session', null)).toEqual({ state: 'connected' });
  expect(console.isClosed).toBe(false);
  expect(toSidecar).toHaveLength(2);
});