Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
import { createServer, type Server } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import type { AgentBridgeEvent } from '@sandboxaq/switch-agent-runtime';
import { callOperation, SESSION_SELECTOR_HEADERS } from '@sandboxaq/switch-agent-runtime/hosted';
import { openHubStream, sealProviderLogin } from '@switch-console/agent-providers';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import {
type ControllerDeps,
type ControllerExit,
ensureRelayCredentials,
runController,
} from './controller';
import { ConfigurationError } from './errors';
import { adoptIdentity } from './handover';
import { silentLogger } from './log';
import { ProviderRechecks } from './provider-rechecks';
import type { LocalRelay } from './relay';
import type { AgentAssignment, StatusReport } from './schemas';
import { CONTROLLER_CREDENTIAL, FileSecretStore, MemorySecretStore } from './secrets';
import { type ReleaseInstaller, SelfUpdater, type UpdateAttempt } from './self-update';
import { ControllerStore } from './store';
import { buildWatcherTemplate } from './template';
import { FakeCore } from './testing/fake-core';
import { FakeLocator, FakeRuntime } from './testing/fake-runtime';
function agent(revision: number, overrides: Partial<AgentAssignment> = {}): AgentAssignment {
return {
agent_id: 'agent-1',
revision,
desired_state: 'running',
definition: {
name: 'scout',
display_name: null,
icon_url: null,
provider: 'claude',
model: null,
advanced_config: {},
instructions: '',
auto_approve: false,
auto_mode: false,
directory: null,
isolation: 'shared',
},
...overrides,
};
}
async function waitFor(condition: () => boolean, what: string, timeoutMs = 15_000): Promise<void> {
const deadline = Date.now() + timeoutMs;
while (!condition()) {
if (Date.now() > deadline) throw new Error(`Timed out waiting for ${what}.`);
await delay(10);
}
}
let dir: string;
let core: FakeCore;
let store: ControllerStore;
let secrets: FileSecretStore;
let runtime: FakeRuntime;
let stop: AbortController;
let running: Promise<ControllerExit> | null;
let watchers: AbortController[];
let blockers: Server[];
function deps(server = core.url): ControllerDeps {
store.saveIdentity({
controllerId: core.controllerId,
server,
name: 'test-box',
enrolledAt: '2026-01-01T00:00:00Z',
});
return {
store,
secrets,
runtime: runtime.build,
locator: new FakeLocator(),
rechecks: new ProviderRechecks(),
refreshPath: async () => {},
providerSeed: [],
sessionStarted: () => {},
tools: async () => [],
fetch,
openWebSocket: core.openWebSocket,
log: silentLogger,
dataDir: dir,
workspacesFor: () => join(dir, 'workspaces'),
version: '0.1.0',
updatedBy: 'self',
selfUpdate: null,
now: Date.now,
random: () => 0,
timing: {
resyncMs: 60_000,
statusPollMs: 20,
statusMinGapMs: 10,
defaultReportWithinS: 60,
streamIdleMs: 2_000,
streamInitialBackoffMs: 10,
streamMaxBackoffMs: 50,
eventBufferLimit: 100,
},
};
}
const quiet = { debug: () => {}, warn: () => {}, error: () => {} };
/** The agent's watcher, as the runtime runs it in the controller's process: its stream comes from the controller. */
function watcher(agentId = 'agent-1') {
const events: AgentBridgeEvent[] = [];
const controller = new AbortController();
watchers.push(controller);
const credentials = runtime.credentials.get(agentId)!;
const stream = runtime.openStream!(agentId)({
creds: { agentId, apiEndpoint: credentials.endpoint, token: credentials.token },
connectionId: `controller-${agentId}`,
scope: 'all',
filter: 'addressed',
spawnCapable: true,
rooms: [],
onEvent: (event) => void events.push(event),
onGap: () => {},
onEvicted: () => {},
log: quiet,
signal: controller.signal,
});
stream.start();
return { stream, events };
}
function addressed(sequence: number) {
return {
type: 'message',
room_id: 'room-a',
bridge_id: null,
channel_type: null,
payload: {
addressed: true,
sender: '@person:example.org',
sender_name: 'Person',
message_id: `$m${sequence}`,
body: 'hi',
timestamp: sequence,
},
missed: { count: 0, reason: null },
};
}
/** What the watcher of `agent(1)` was launched from. */
function runtimeTemplate() {
return buildWatcherTemplate({
agentId: 'agent-1',
provider: 'claude',
definition: agent(1).definition,
cwd: '/data/workspaces/scout',
credentialsPath: '/data/agents/agent-1/credentials.json',
binaryPath: '/usr/bin/claude',
});
}
async function freePort(): Promise<number> {
const server = createServer();
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
const port = (server.address() as { port: number }).port;
await new Promise<void>((resolve) => server.close(() => resolve()));
return port;
}
function reportsFor(agentId: string): StatusReport['agents'] {
return core.statusReports.flatMap((report) =>
report.agents.filter((entry) => entry.agent_id === agentId)
);
}
beforeEach(async () => {
dir = mkdtempSync(join(tmpdir(), 'controller-loop-'));
core = new FakeCore();
await core.start();
store = ControllerStore.open(join(dir, 'controller.db'));
secrets = new FileSecretStore(join(dir, 'secrets'));
await secrets.set(CONTROLLER_CREDENTIAL, core.credential);
runtime = new FakeRuntime();
stop = new AbortController();
running = null;
watchers = [];
blockers = [];
core.rooms.set('agent-1', ['room-a']);
});
afterEach(async () => {
for (const controller of watchers) controller.abort();
for (const blocker of blockers) blocker.close();
stop.abort();
await running?.catch(() => {});
await core.stop();
store.close();
rmSync(dir, { recursive: true, force: true });
});
describe('runController', () => {
it('starts the agent pointed at its relay, relays its events, confirms them upstream, and exits when revoked', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
const credentials = runtime.credentials.get('agent-1')!;
expect(credentials.endpoint).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
expect(credentials.token).toMatch(/^swlr_/);
expect(store.relayPort()).toBe(Number(new URL(credentials.endpoint).port));
// Nothing assigned yet when the stream first opened: every agent starts at head.
expect(core.opens[0]).toEqual({});
const { events } = watcher();
await waitFor(
() => reportsFor('agent-1').some((entry) => entry.process === 'running' && entry.attached),
'a status report with the agent attached'
);
core.pushEvent('agent-1', 1, addressed(1));
await waitFor(() => events.length === 1, 'the event at the watcher');
expect(events[0]).toMatchObject({ type: 'message', room_id: 'room-a', sequence: 1 });
await waitFor(
() => core.beats.some((beat) => beat['agent-1'] === 1),
'the watcher’s confirmation beaten upstream'
);
expect(store.cursors().get('agent-1')).toBe(1);
const forwarded = await callOperation(
{
identity: { endpoint: credentials.endpoint, agentId: 'agent-1', token: credentials.token },
connectionId: 'controller-agent-1',
selector: { [SESSION_SELECTOR_HEADERS.sessionId]: 'session-1' },
room: null,
mediaDir: dir,
cwd: dir,
deadConnection: () => 'dead',
},
'post_message',
{ body: 'hello' }
);
expect(forwarded.isError).toBeFalsy();
const op = core.requests.findLast((r) => r.path === '/agents/agent-1/ops/post_message')!;
expect(op.headers['x-switch-agent-id']).toBe('agent-1');
expect(op.headers.authorization).toMatch(/^Bearer access-token-/);
core.revoke();
expect(await running).toBe('revoked');
expect(runtime.calls).toEqual(
expect.arrayContaining([
{ kind: 'stop', agentId: 'agent-1', wait: false },
{ kind: 'deleteCredentials', agentId: 'agent-1' },
])
);
expect(await secrets.get(CONTROLLER_CREDENTIAL)).toBeNull();
expect(store.revokedAt()).not.toBeNull();
expect(runtime.closed).toBe(true);
await expect(fetch(`${credentials.endpoint}/version`)).rejects.toThrow();
}, 20_000);
it('serves an isolated agent its events on the hub over the relay, and moves it in-process when that changes', async () => {
const isolatedAgent = agent(1);
isolatedAgent.definition.isolation = 'isolated';
core.setAssignment({ revision: 1, agents: [isolatedAgent] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
expect(runtime.launches('agent-1')[0]!.options.isolation).toBe('isolated');
const credentials = runtime.credentials.get('agent-1')!;
const events: AgentBridgeEvent[] = [];
const own = new AbortController();
watchers.push(own);
openHubStream(credentials.hub)({
creds: { agentId: 'agent-1', apiEndpoint: credentials.endpoint, token: credentials.token },
connectionId: 'isolated-host',
scope: 'all',
filter: 'addressed',
rooms: [],
onEvent: (event) => void events.push(event),
onGap: () => {},
onEvicted: () => {},
log: quiet,
signal: own.signal,
}).start();
await waitFor(
() => reportsFor('agent-1').at(-1)?.attached === true,
'the isolated host attached'
);
core.pushEvent('agent-1', 1, addressed(1));
await waitFor(() => events.length === 1, 'the event on the hub');
await waitFor(() => store.cursors().get('agent-1') === 1, 'its cursor confirmed');
core.setAssignment({ revision: 2, agents: [agent(2)] });
core.push('assignment.changed', { revision: 2 });
await waitFor(() => runtime.launches('agent-1').length === 2, 'a restart in-process');
expect(runtime.launches('agent-1')[1]!.options.isolation).toBe('shared');
const { events: inProcess } = watcher();
core.pushEvent('agent-1', 2, addressed(2));
await waitFor(() => inProcess.length === 1, 'the next event at the host in the controller');
expect(inProcess[0]!.sequence).toBe(2);
expect(events).toHaveLength(1);
stop.abort();
expect(await running).toBe('stopped');
}, 20_000);
it('reopens the stream with the confirmed cursors, and follows attach and detach live', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
const { stream, events } = watcher();
await waitFor(() => reportsFor('agent-1').at(-1)?.attached === true, 'the watcher attached');
core.pushEvent('agent-1', 5, addressed(5));
await waitFor(() => events.length === 1, 'the event');
await waitFor(() => store.cursors().get('agent-1') === 5, 'the cursor confirmed');
await stream.replacePlacements({ 'session-1': 'room-a' });
core.forgetConnection();
await waitFor(() => core.opens.length === 2, 'a new connection');
expect(core.opens[1]).toEqual({ 'agent-1': 5 });
await waitFor(() => core.streamCount === 1, 'the new stream attached');
core.pushEvent('agent-1', 6, addressed(6));
await waitFor(() => events.length === 2, 'the next event, once');
expect(events.map((event) => event.sequence)).toEqual([5, 6]);
await waitFor(() => reportsFor('agent-1').at(-1)?.attached === true, 'attached');
core.push('agent.detached', { agent_id: 'agent-1', reason: 'unassigned' });
await waitFor(() => reportsFor('agent-1').at(-1)?.attached === false, 'detached');
core.push('agent.attached', { agent_id: 'agent-1', from_seq: 6, rooms: ['room-a'] });
await waitFor(() => reportsFor('agent-1').at(-1)?.attached === true, 'attached again');
core.setAssignment({ revision: 2, agents: [agent(2)] });
core.assignment.agents[0]!.definition.model = 'opus';
core.push('assignment.changed', { revision: 2 });
await waitFor(
() => runtime.launches('agent-1').length === 2,
'the new revision handed to the agent host'
);
expect(runtime.launches('agent-1')[1]!.options.restart).toBe(false);
expect(runtime.launches('agent-1')[1]!.template.start.input.model).toEqual({ id: 'opus' });
stop.abort();
expect(await running).toBe('stopped');
}, 20_000);
it('restarts an agent host whose credentials predate the hub, so it comes back on the hub', async () => {
const port = await freePort();
core.setAssignment({ revision: 1, agents: [agent(1)] });
store.saveRelayPort(port);
store.saveAssignment(core.assignment, '"1"', '2026-01-01T00:00:00Z');
store.recordApplied('agent-1', 1, '2026-01-01T00:00:00Z');
await runtime.launch('agent-1', runtimeTemplate(), {
isolation: 'isolated',
restart: false,
replaceIdentity: false,
clearTakenOver: false,
});
// As a controller from before the hub wrote them: the relay and a token, no hub.
await runtime.writeCredentials('agent-1', {
endpoint: `http://127.0.0.1:${port}`,
token: 'swlr_old',
hub: '',
providerLogin: null,
});
runtime.calls.length = 0;
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'a restart');
expect(runtime.launches('agent-1')[0]!.options.restart).toBe(true);
expect(runtime.credentials.get('agent-1')).toMatchObject({
endpoint: `http://127.0.0.1:${port}`,
hub: `ws://127.0.0.1:${port}/hub`,
});
stop.abort();
expect(await running).toBe('stopped');
});
it('points a watcher at the relay’s new port, and restarts it, when its old one is taken', async () => {
const port = await freePort();
const blocker = createServer();
blockers.push(blocker);
await new Promise<void>((resolve) => blocker.listen(port, '127.0.0.1', resolve));
core.setAssignment({ revision: 1, agents: [agent(1)] });
store.saveRelayPort(port);
store.saveAssignment(core.assignment, '"1"', '2026-01-01T00:00:00Z');
store.recordApplied('agent-1', 1, '2026-01-01T00:00:00Z');
await runtime.launch('agent-1', runtimeTemplate(), {
isolation: 'shared',
restart: false,
replaceIdentity: false,
clearTakenOver: false,
});
await runtime.writeCredentials('agent-1', {
endpoint: `http://127.0.0.1:${port}`,
token: 'swlr_old',
hub: `ws://127.0.0.1:${port}/hub`,
providerLogin: null,
});
runtime.calls.length = 0;
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'a restart');
expect(runtime.launches('agent-1')[0]!.options.restart).toBe(true);
expect(runtime.credentials.get('agent-1')!.endpoint).not.toBe(`http://127.0.0.1:${port}`);
expect(store.relayPort()).not.toBe(port);
stop.abort();
expect(await running).toBe('stopped');
});
it('exits as taken over when another instance opens the controller stream', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => core.streamCount === 1, 'the controller stream');
const token = await (
await fetch(`${core.url}/v1/management/controllers/${core.controllerId}/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ credential: core.credential }),
})
).json();
await fetch(`${core.url}/v1/controllers/${core.controllerId}/connection`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token.access_token}`,
},
body: JSON.stringify({ client: 'other', client_version: '0', cursors: {} }),
});
expect(await running).toBe('taken_over');
expect(runtime.calls.filter((call) => call.kind === 'stop')).toEqual([]);
});
it('checks every provider again on request, with a fresh PATH, and reports it before answering', async () => {
const locator = new FakeLocator();
locator.missing.add('codex');
const rechecks = new ProviderRechecks();
let pathRefreshes = 0;
core.setAssignment({ revision: 1, agents: [] });
running = runController(
{
...deps(),
locator,
rechecks,
refreshPath: async () => {
pathRefreshes += 1;
},
},
stop.signal
);
const codexIn = (report: StatusReport | undefined) =>
report?.providers.find((entry) => entry.provider === 'codex')?.installed;
await waitFor(() => codexIn(core.statusReports.at(-1)) === false, 'codex reported missing');
// Installed since: only a recheck finds it before the check goes stale.
locator.missing.delete('codex');
await rechecks.run();
expect(pathRefreshes).toBe(1);
expect(codexIn(core.statusReports.at(-1))).toBe(true);
});
it('refuses a recheck while the controller is not running', async () => {
await expect(new ProviderRechecks().run()).rejects.toThrow(/not connected/);
});
it('runs pending operations when nudged', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the first start');
const probesBefore = runtime.probes;
core.addOperation({
id: 'op-restart',
kind: 'agent.restart',
agent_id: 'agent-1',
params: {},
created_at: '2026-01-01T00:00:00Z',
});
core.addOperation({
id: 'op-recheck',
kind: 'provider.recheck',
agent_id: null,
params: { provider: 'claude' },
created_at: '2026-01-01T00:00:00Z',
});
core.addOperation({
id: 'op-login',
kind: 'provider.login',
agent_id: null,
params: { provider: 'claude', method: 'device_code' },
created_at: '2026-01-01T00:00:00Z',
});
core.push('operation.pending', {
operation_id: 'op-restart',
kind: 'agent.restart',
agent_id: 'agent-1',
});
await waitFor(() => core.results.size === 3, 'three operation results');
expect(core.results.get('op-restart')).toEqual({ outcome: 'succeeded' });
expect(core.results.get('op-recheck')).toMatchObject({ outcome: 'succeeded' });
expect(core.results.get('op-login')).toMatchObject({
outcome: 'failed',
error: { code: 'operation_unsupported' },
});
expect(runtime.launches('agent-1')).toHaveLength(2);
expect(runtime.launches('agent-1')[1]!.options).toMatchObject({
restart: true,
clearTakenOver: true,
});
expect(runtime.probes).toBeGreaterThan(probesBefore);
stop.abort();
expect(await running).toBe('stopped');
});
it('warms the agent host for a room when Switch asks, and only warns when it cannot', async () => {
const warnings: string[] = [];
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(
{ ...deps(), log: { ...silentLogger, warn: (message) => void warnings.push(message) } },
stop.signal
);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
await waitFor(() => core.streamCount === 1, 'the stream attached');
runtime.warmFailure = new Error('not running here');
core.push('agent.warm', { agent_id: 'agent-1', room_id: 'room-a' });
await waitFor(() => warnings.some((w) => w.includes('warm')), 'the warning');
runtime.warmFailure = null;
core.push('agent.warm', { agent_id: 'agent-1', room_id: 'room-a' });
await waitFor(() => runtime.warms.length === 1, 'the warm');
expect(runtime.warms).toEqual([{ agentId: 'agent-1', roomId: 'room-a' }]);
stop.abort();
expect(await running).toBe('stopped');
});
it('takes up a login given to the machine on demand, and moves its agent onto it', async () => {
runtime.readiness = { status: 'unauthenticated', message: 'Not signed in.', models: [] };
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the first start');
await waitFor(() => core.publicKey !== null, 'the machine registering its key');
expect(runtime.launches('agent-1')[0]!.options.isolation).toBe('shared');
expect(runtime.credentials.get('agent-1')?.providerLogin).toBeNull();
core.sealedLogins.set('claude', {
revision: 1,
sealed: sealProviderLogin({
publicKey: core.publicKey!,
controllerId: core.controllerId,
provider: 'claude',
login: { kind: 'setup-token', credential: 'sk-ant-oat-given' },
}),
});
core.addOperation({
id: 'op-give',
kind: 'provider.login',
agent_id: null,
params: { provider: 'claude', method: 'sealed', revision: 1 },
created_at: '2026-01-01T00:00:00Z',
});
core.push('operation.pending', {
operation_id: 'op-give',
kind: 'provider.login',
agent_id: null,
});
await waitFor(() => core.results.has('op-give'), 'the login taken up');
expect(core.results.get('op-give')).toMatchObject({
outcome: 'succeeded',
output: { provider: { auth: 'ok', auth_source: 'sealed' } },
});
await waitFor(() => runtime.launches('agent-1').length === 2, 'the agent moved onto it');
const moved = runtime.launches('agent-1')[1]!;
expect(moved.options).toMatchObject({ isolation: 'isolated', restart: true });
expect(moved.template.start.input.env).toMatchObject({
CLAUDE_CODE_OAUTH_TOKEN: 'sk-ant-oat-given',
});
expect(runtime.credentials.get('agent-1')?.providerLogin).toMatchObject({
provider: 'claude',
revision: '1',
});
await waitFor(
() =>
core.statusReports.some(
(report) =>
report.providers.find((entry) => entry.provider === 'claude')?.auth_source === 'sealed'
),
'a status report saying Claude is ready through the given login'
);
stop.abort();
expect(await running).toBe('stopped');
});
it('resyncs after the stream drops and reconnects', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the first start');
core.setAssignment({ revision: 2, agents: [agent(2)] });
core.closeStreams();
await waitFor(() => runtime.launches('agent-1').length === 2, 'a resync on reconnect');
stop.abort();
expect(await running).toBe('stopped');
});
it('reconciles the cached assignment while the server is unreachable', async () => {
store.saveAssignment({ revision: 1, agents: [agent(1)] }, '"1"', '2026-01-01T00:00:00Z');
store.recordApplied('agent-1', 1, '2026-01-01T00:00:00Z');
await runtime.writeCredentials('agent-1', {
endpoint: 'http://127.0.0.1:1',
token: 'swlr_k',
hub: 'ws://127.0.0.1:1/hub',
providerLogin: null,
});
runtime.calls.length = 0;
await core.stop();
running = runController(deps('http://127.0.0.1:1'), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent restored from cache');
expect(runtime.launches('agent-1')[0]!.options.restart).toBe(false);
expect(runtime.credentials.get('agent-1')!.endpoint).not.toBe('http://127.0.0.1:1');
stop.abort();
expect(await running).toBe('stopped');
});
it('exits as revoked when the credential exchange is refused as revoked', async () => {
core.revoked = true;
running = runController(deps(), stop.signal);
expect(await running).toBe('revoked');
expect(await secrets.get(CONTROLLER_CREDENTIAL)).toBeNull();
});
it('runs on an adopted identity with the credential in memory, and writes it nowhere', async () => {
const handedDir = mkdtempSync(join(tmpdir(), 'controller-handed-'));
const handed = ControllerStore.open(join(handedDir, 'controller.db'));
try {
adoptIdentity(
handed,
{
controllerId: core.controllerId,
server: core.url,
name: 'console-box',
now: new Date('2026-01-01T00:00:00Z'),
},
handedDir
);
const memory = new MemorySecretStore(
{ [CONTROLLER_CREDENTIAL]: core.credential },
'handed over on stdin'
);
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(
{ ...deps(), store: handed, secrets: memory, dataDir: handedDir },
stop.signal
);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
core.revoke();
expect(await running).toBe('revoked');
expect(await memory.get(CONTROLLER_CREDENTIAL)).toBeNull();
expect(handed.revokedAt()).not.toBeNull();
expect(existsSync(join(handedDir, 'secrets'))).toBe(false);
for (const name of readdirSync(handedDir))
if (!name.startsWith('controller.db'))
throw new Error(`The controller wrote ${name} into its data directory.`);
for (const name of readdirSync(handedDir))
expect(readFileSync(join(handedDir, name)).includes(core.credential)).toBe(false);
} finally {
handed.close();
rmSync(handedDir, { recursive: true, force: true });
}
});
it('runs against the server URL its parent moved it to', async () => {
const moved = deps('https://old-address.example.com');
expect(
adoptIdentity(
store,
{ controllerId: core.controllerId, server: core.url, name: 'test-box', now: new Date() },
dir
)
).toBe('server_changed');
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(moved, stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
expect(store.identity()?.server).toBe(core.url);
});
it('refuses to run without an identity or a credential', async () => {
const empty = ControllerStore.open(join(dir, 'empty.db'));
try {
const unenrolled = runController({ ...deps(), store: empty }, stop.signal);
await expect(unenrolled).rejects.toThrow(/not enrolled/);
await expect(unenrolled).rejects.toBeInstanceOf(ConfigurationError);
} finally {
empty.close();
}
const enrolled = deps();
await secrets.delete(CONTROLLER_CREDENTIAL);
store.markRevoked('2026-01-02T00:00:00Z');
const wiped = runController(enrolled, stop.signal);
await expect(wiped).rejects.toThrow(/revoked at/);
await expect(wiped).rejects.toBeInstanceOf(ConfigurationError);
});
});
describe('the release Switch names', () => {
function selfUpdate() {
const installed: string[] = [];
const installer: ReleaseInstaller = {
unavailable: null,
prepare: async () => {},
activate: async (version) => void installed.push(version),
};
let attempt: UpdateAttempt | null = null;
const updater = new SelfUpdater({
version: '0.1.0',
installer,
download: async () => join(dir, 'never-written.tgz'),
attempts: { last: () => attempt, save: (saved) => void (attempt = saved) },
supervised: true,
log: silentLogger,
now: Date.now,
});
return { updater, installed };
}
const release = {
version: '0.2.0',
url: 'https://example.invalid/switch-agent-controller-0.2.0.tgz',
sha256: 'c'.repeat(64),
};
it('is installed while no session is mid-turn, and the controller ends to restart on it', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
core.controllerRelease = release;
const { updater, installed } = selfUpdate();
running = runController({ ...deps(), selfUpdate: updater }, stop.signal);
expect(await running).toBe('restarting');
expect(installed).toEqual(['0.2.0']);
});
it('waits while an agent host that does not report busy sessions has any, and says so in the status', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
const { updater, installed } = selfUpdate();
running = runController({ ...deps(), selfUpdate: updater }, stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
runtime.observation('agent-1').health!.placements = { 'session-1': 'room-a' };
core.controllerRelease = release;
await waitFor(
() => core.statusReports.some((report) => report.update?.state === 'waiting_idle'),
'a status saying the update waits'
);
expect(core.statusReports.at(-1)?.update).toEqual({ target: '0.2.0', state: 'waiting_idle' });
expect(installed).toEqual([]);
runtime.observation('agent-1').health!.placements = {};
expect(await running).toBe('restarting');
expect(installed).toEqual(['0.2.0']);
});
it('waits only while a session is mid-turn when the agent host says which are', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
const { updater, installed } = selfUpdate();
running = runController({ ...deps(), selfUpdate: updater }, stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
const health = runtime.observation('agent-1').health!;
health.placements = { 'session-1': 'room-a', 'session-2': 'room-b' };
health.busy = ['session-1'];
core.controllerRelease = release;
await waitFor(
() => core.statusReports.some((report) => report.update?.state === 'waiting_idle'),
'a status saying the update waits'
);
expect(installed).toEqual([]);
health.busy = [];
expect(await running).toBe('restarting');
expect(installed).toEqual(['0.2.0']);
});
it('is left alone by a controller that does not update itself', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
core.controllerRelease = release;
running = runController(deps(), stop.signal);
await waitFor(() => core.statusReports.length >= 2, 'two status reports');
expect(core.statusReports.every((report) => report.update === undefined)).toBe(true);
stop.abort();
expect(await running).toBe('stopped');
});
});
describe('an agent host that outlived the controller on another bundle', () => {
const restarts = () =>
runtime.launches('agent-1').filter((call) => call.options.restart === true);
it('is restarted onto this controller’s bundle once none of its sessions is mid-turn, and only once', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
const observation = runtime.observation('agent-1');
observation.outdated = true;
observation.health!.placements = { 'session-1': 'room-a' };
observation.health!.busy = ['session-1'];
await new Promise((resolve) => setTimeout(resolve, 200));
expect(restarts()).toEqual([]);
observation.health!.busy = [];
await waitFor(() => restarts().length === 1, 'the outdated agent host restarted');
await new Promise((resolve) => setTimeout(resolve, 200));
expect(restarts()).toHaveLength(1);
stop.abort();
expect(await running).toBe('stopped');
});
it('is not restarted again while it stays on another bundle, within the retry wait', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
runtime.observation('agent-1').outdated = true;
await waitFor(() => restarts().length === 1, 'the outdated agent host restarted');
runtime.observation('agent-1').outdated = true;
await new Promise((resolve) => setTimeout(resolve, 200));
expect(restarts()).toHaveLength(1);
stop.abort();
expect(await running).toBe('stopped');
});
it('is left alone when it runs this controller’s bundle', async () => {
core.setAssignment({ revision: 1, agents: [agent(1)] });
running = runController(deps(), stop.signal);
await waitFor(() => runtime.launches('agent-1').length === 1, 'the agent started');
await new Promise((resolve) => setTimeout(resolve, 200));
expect(restarts()).toEqual([]);
stop.abort();
expect(await running).toBe('stopped');
});
});
describe('ensureRelayCredentials', () => {
const login = {
status: 'connected' as const,
provider: 'claude' as const,
revision: '1',
kind: 'setup-token' as const,
credential: 'sk-ant-oat-given',
};
function fakeRelay() {
const registered = new Map<string, string>();
let minted = 0;
return {
registered,
relay: {
endpoint: 'http://127.0.0.1:43210',
hubUrl: 'ws://127.0.0.1:43210/hub',
isRegistered: (agentId: string, token: string) => registered.get(agentId) === token,
register: (agentId: string, token: string) => void registered.set(agentId, token),
mint: (agentId: string) => {
const token = `swlr_${++minted}`;
registered.set(agentId, token);
return token;
},
} as unknown as LocalRelay,
};
}
it('rewrites the file, keeping its token, when the given login changes', async () => {
const runtime = new FakeRuntime();
const { relay } = fakeRelay();
const deps = { runtime, relay, log: silentLogger };
expect(await ensureRelayCredentials('agent-1', null, deps)).toBe(true);
expect(await ensureRelayCredentials('agent-1', null, deps)).toBe(false);
expect(await ensureRelayCredentials('agent-1', login, deps)).toBe(true);
expect(runtime.credentials.get('agent-1')).toMatchObject({
token: 'swlr_1',
providerLogin: login,
});
expect(await ensureRelayCredentials('agent-1', login, deps)).toBe(false);
// The same login with its fields in another order is the same login.
const reordered = {
credential: login.credential,
kind: login.kind,
revision: login.revision,
provider: login.provider,
status: login.status,
};
expect(await ensureRelayCredentials('agent-1', reordered, deps)).toBe(false);
expect(await ensureRelayCredentials('agent-1', { ...login, revision: '2' }, deps)).toBe(true);
expect(await ensureRelayCredentials('agent-1', null, deps)).toBe(true);
expect(runtime.credentials.get('agent-1')).toMatchObject({
token: 'swlr_1',
providerLogin: null,
});
});
});