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 type {
AgentBridgeEvent,
ApprovalOutcome,
SessionCommand,
} from '@sandboxaq/switch-agent-runtime';
import type { AgentEventStream, AgentStreamDeps } from '@switch-console/agent-providers';
import { errorMessage, type Logger } from './log';
import type {
AgentApprovalOutcomeFrame,
AgentEventFrame,
AgentGapFrame,
AgentSessionCommandFrame,
} from './schemas';
/**
* Hands each managed agent's events from the controller stream to its agent host,
* which runs in this process, and keeps what the controller tells Switch for
* it: how far the agent host has got (its confirmed cursor) and which room each of
* its sessions works in (its placements).
*
* Every agent's events arrive on the one controller stream, whether or not its
* host is running. They are held here until the agent host takes them, up to
* `bufferLimit`; the cursor moves only once the agent host has taken an event, so
* a controller that restarts resumes each agent from what its agent host really
* had.
*/
export type AgentHubDeps = {
log: Logger;
/** An agent's confirmed cursor moved; the controller persists it and beats it upstream. */
onCursor: (agentId: string, cursor: number) => void;
/** Something `attached()` reads changed. */
onChange: () => void;
/** The most events held per agent while its agent host is not taking them; past it the oldest go, and it is told. */
bufferLimit: number;
};
type Buffered =
| { kind: 'event'; seq: number; notifiable: boolean; data: AgentBridgeEvent }
| { kind: 'gap'; seq: number; data: GapData };
type GapData = {
from_sequence: number;
resumed_at?: number;
rooms?: string[];
all_rooms?: boolean;
reason: string;
};
/** The agent host, as the stream it opened. */
type AgentHostLink = {
deps: AgentStreamDeps;
started: boolean;
/** The last sequence handed to the agent host (or skipped); null until the agent's head is known. */
cursor: number | null;
connected: boolean;
delivering: boolean;
closed: boolean;
};
type AgentState = {
agentId: string;
/** Core attached the agent to the controller stream. */
attached: boolean;
/** The rooms the agent belongs to, as Core last said; null before it has. */
rooms: Set<string> | null;
/** The highest sequence known for this agent. */
head: number | null;
/**
* Where Switch first attached the agent to this controller. An agent host
* that starts with no cursor of its own (a new agent's first run) starts
* here, so what addressed the agent while its host was coming up (a
* template's kickoff, posted the moment the agent exists) is not skipped.
*/
attachedFrom: number | null;
/** An agent host has started for it since the controller started. */
hostStarted: boolean;
/** At or below this, nothing is held: an agent host starting there is told of a gap. */
droppedThrough: number;
/** The cursor the controller resumes the agent from upstream. */
confirmed: number | null;
buffer: Buffered[];
/** Core reset the agent's numbering (it restarted). */
reset: { reason: string; rooms: string[] } | null;
/** Each of its sessions' room, as its agent host last stated. */
placements: Map<string, string>;
/** Rooms its agent host placed a session in that it is not in, each said once. */
refusedRooms: Set<string>;
host: AgentHostLink | null;
overflowing: boolean;
};
/** Whether an agent host filtering to what addresses the agent is handed this event, as Switch decides. */
export function isNotifiable(type: string, payload: Record<string, unknown>): boolean {
if (type === 'message') return payload.addressed === true;
if (type === 'room_join') return payload.listening === true;
if (type === 'command') return false;
return type.startsWith('task_');
}
function approvalOutcome(data: Record<string, unknown>): ApprovalOutcome | null {
const text = (value: unknown) => (typeof value === 'string' ? value : null);
const sessionId = text(data.session_id);
const requestId = text(data.request_id);
if (!sessionId || !requestId || (data.state !== 'answered' && data.state !== 'expired'))
return null;
return {
session_id: sessionId,
request_id: requestId,
state: data.state,
answer: text(data.answer),
answered_by: text(data.answered_by),
answered_at: text(data.answered_at),
};
}
/** The index of the first buffered item past `cursor`. */
function firstAfter(buffer: Buffered[], cursor: number): number {
let low = 0;
let high = buffer.length;
while (low < high) {
const middle = (low + high) >> 1;
if (buffer[middle]!.seq <= cursor) low = middle + 1;
else high = middle;
}
return low;
}
export class AgentHub {
private readonly agents = new Map<string, AgentState>();
private upstream = false;
constructor(private readonly deps: AgentHubDeps) {}
// -- What the controller tells Switch ---------------------------------------
/** Where the controller resumes an agent from, as persisted. */
setCursor(agentId: string, cursor: number): void {
const agent = this.agent(agentId);
agent.confirmed = cursor;
agent.head = cursor;
agent.droppedThrough = cursor;
}
/** Each agent's confirmed cursor, for the upstream beat and reopen. */
cursors(): Record<string, number> {
const cursors: Record<string, number> = {};
for (const agent of this.agents.values())
if (agent.confirmed !== null) cursors[agent.agentId] = agent.confirmed;
return cursors;
}
/** Where Core attached the agent on the controller stream, while it is attached. */
attachment(agentId: string): { fromSeq: number; rooms: string[] } | null {
const agent = this.agents.get(agentId);
if (!agent?.attached || agent.head === null) return null;
return { fromSeq: agent.head, rooms: [...(agent.rooms ?? [])] };
}
/** The agent's events flow on the controller stream and its agent host is taking them. */
attached(agentId: string): boolean {
return this.agents.get(agentId)?.host?.connected ?? false;
}
/**
* The room a call made for the agent is made in: the calling session's
* placement when the call names a session, otherwise the agent's only
* placed room. Null when neither says, and Switch answers as it does for a
* caller bound to no room.
*/
roomFor(agentId: string, sessionId: string | null): string | null {
const agent = this.agents.get(agentId);
if (!agent) return null;
if (sessionId) return agent.placements.get(sessionId) ?? null;
const rooms = new Set(agent.placements.values());
return rooms.size === 1 ? [...rooms][0]! : null;
}
/** Forgets the agent: it is no longer assigned here. Its host has been stopped. */
forget(agentId: string): void {
const agent = this.agents.get(agentId);
if (!agent) return;
if (agent.host) agent.host.closed = true;
this.agents.delete(agentId);
this.deps.onChange();
}
// -- What arrives on the controller stream ----------------------------------
setUpstream(connected: boolean): void {
if (this.upstream === connected) return;
this.upstream = connected;
this.refreshAll();
}
/**
* The controller stream (re)attached. Switch attaches every bound agent
* afresh on each stream, with `agent.attached`, so none counts as attached
* until it says so again.
*/
streamAttached(): void {
for (const agent of this.agents.values()) agent.attached = false;
this.upstream = true;
this.refreshAll();
}
attach(agentId: string, fromSeq: number, rooms: string[]): void {
const agent = this.agent(agentId);
agent.attached = true;
agent.rooms = new Set(rooms);
if (agent.attachedFrom === null) agent.attachedFrom = fromSeq;
if (agent.head === null) agent.head = fromSeq;
else if (fromSeq > agent.head) {
// Switch starts the agent past what is held here: whatever lay between
// is not coming, and an agent host behind it is told so.
agent.head = fromSeq;
agent.droppedThrough = Math.max(agent.droppedThrough, fromSeq);
}
if (agent.host?.started && agent.host.cursor === null) agent.host.cursor = agent.head;
this.deps.log.info('Agent attached to the controller stream', { agentId, fromSeq });
this.refresh(agent);
this.pump(agent);
}
detach(agentId: string, reason: string): void {
const agent = this.agents.get(agentId);
if (!agent) return;
agent.attached = false;
this.deps.log.warn('Agent detached from the controller stream', { agentId, reason });
this.refresh(agent);
}
setRooms(agentId: string, rooms: string[]): void {
const agent = this.agent(agentId);
agent.rooms = new Set(rooms);
// A room the agent is out of (deleted, or the agent taken out), as Switch
// says: a session placed there no longer attends it, and its agent host
// forgets the placement rather than state it again and again.
for (const [sessionId, roomId] of [...agent.placements]) {
if (agent.rooms.has(roomId)) continue;
agent.placements.delete(sessionId);
this.deps.onChange();
const host = agent.host;
if (!host || host.closed) continue;
void Promise.resolve(host.deps.onRoomGone?.({ roomId, sessionId })).catch((error: unknown) =>
this.deps.log.warn('The agent host could not drop a session placement in a room it left', {
agentId,
roomId,
error: errorMessage(error),
})
);
}
}
/**
* A domain event: held until the agent host takes it. One already held (Switch
* replays from where the connection opened each time the stream
* reattaches) is dropped.
*/
ingest(frame: AgentEventFrame): void {
const { agent_id: agentId, seq } = frame;
const agent = this.agent(agentId);
if (agent.head !== null && seq <= agent.head) return;
const data = { ...frame.event, sequence: seq } as unknown as AgentBridgeEvent;
agent.buffer.push({
kind: 'event',
seq,
notifiable: isNotifiable(frame.event.type, frame.event.payload),
data,
});
if (agent.host?.started && agent.host.cursor === null) agent.host.cursor = seq - 1;
agent.head = seq;
this.pump(agent);
this.trim(agent);
}
/**
* Switch could not serve the agent's cursor. A reset (Switch restarted, so
* its numbering went back: resuming below what is held) clears what is held
* and goes to the agent host now. A gap resuming past what is held takes its
* place in the buffer, so the agent host meets it in order. One resuming at or
* below it describes events already held — a reattached stream starting
* from where the connection opened — and is not passed on.
*/
gap(frame: AgentGapFrame): void {
const { agent_id: agentId, ...rest } = frame;
const data: GapData = {
from_sequence: rest.from_sequence,
reason: rest.reason,
...(rest.resumed_at === undefined ? {} : { resumed_at: rest.resumed_at }),
...(rest.rooms === undefined ? {} : { rooms: rest.rooms }),
...(rest.all_rooms === undefined ? {} : { all_rooms: rest.all_rooms }),
};
const agent = this.agent(agentId);
const resumedAt = data.resumed_at;
if (resumedAt === undefined) {
void this.tell(agent, data);
return;
}
if (agent.head !== null && resumedAt <= agent.head && data.all_rooms !== true) {
this.deps.log.debug('Dropped a gap behind what the controller already holds', {
agentId,
resumedAt,
head: agent.head,
});
return;
}
if (agent.head !== null && resumedAt < agent.head) {
agent.buffer = [];
agent.head = resumedAt;
agent.droppedThrough = resumedAt;
agent.reset = { reason: data.reason, rooms: data.rooms ?? [] };
agent.confirmed = resumedAt;
this.deps.onCursor(agentId, resumedAt);
const host = agent.host;
if (host?.started && !host.closed) {
void this.tell(agent, data);
host.cursor = resumedAt;
}
return;
}
agent.buffer.push({ kind: 'gap', seq: resumedAt, data });
agent.head = resumedAt;
this.pump(agent);
this.trim(agent);
}
/**
* A room control (`!reset`, `!compact`, `!interrupt`), for whichever of the
* agent's sessions works in its room: the agent host decides which.
*/
sessionCommand(frame: AgentSessionCommandFrame): void {
const { agent_id: agentId, command } = frame;
const origin = command.origin as { roomId?: unknown } | undefined;
const roomId = frame.room_id ?? (typeof origin?.roomId === 'string' ? origin.roomId : null);
const agent = this.agents.get(agentId);
const host = agent ? this.running(agent) : null;
if (!roomId || !host?.deps.onSessionCommand) {
this.deps.log.warn(
roomId
? 'Dropped a room control: the agent host is not running'
: 'Dropped a room control that names no room',
{ agentId, roomId, commandId: command.commandId }
);
return;
}
const relayed = { ...command, sessionId: null, roomId } as unknown as SessionCommand;
void Promise.resolve(host.deps.onSessionCommand(relayed)).catch((error: unknown) =>
this.deps.log.error('The agent host failed a room control', {
agentId,
commandId: command.commandId,
error: errorMessage(error),
})
);
}
approvalOutcome(frame: AgentApprovalOutcomeFrame): void {
const { agent_id: agentId } = frame;
const agent = this.agents.get(agentId);
const host = agent ? this.running(agent) : null;
const outcome = approvalOutcome(frame.outcome);
if (!outcome) {
this.deps.log.warn('Dropped an unreadable approval outcome', { agentId });
return;
}
if (!host?.deps.onApprovalOutcome) {
this.deps.log.warn(
'An approval outcome arrived while the agent host is not running; Switch sends it again until it is delivered',
{ agentId, requestId: outcome.request_id }
);
return;
}
void Promise.resolve(host.deps.onApprovalOutcome(outcome)).catch((error: unknown) =>
this.deps.log.error('The agent host failed an approval outcome', {
agentId,
requestId: outcome.request_id,
error: errorMessage(error),
})
);
}
// -- The agent host's end ------------------------------------------------------
/**
* The stream the agent's host hears its events on. One agent host per agent:
* a newer one replaces an older still open, which hears nothing more.
*/
open(agentId: string, deps: AgentStreamDeps): AgentEventStream {
const agent = this.agent(agentId);
if (agent.host) agent.host.closed = true;
const host: AgentHostLink = {
deps,
started: false,
cursor: null,
connected: false,
delivering: false,
closed: false,
};
agent.host = host;
agent.placements.clear();
deps.signal.addEventListener(
'abort',
() => {
host.closed = true;
if (agent.host === host) {
agent.host = null;
agent.placements.clear();
}
this.deps.onChange();
},
{ once: true }
);
return {
// Switch keeps no record of an agent's sessions: the agent host says when it starts one.
announcesSessionStarts: true,
// The relay names each call's room from these placements (`roomFor`).
placementsNameCallRooms: true,
start: () => {
if (host.started || host.closed) return;
host.started = true;
host.cursor =
deps.startCursor ??
(!agent.hostStarted && agent.attachedFrom !== null ? agent.attachedFrom : agent.head);
agent.hostStarted = true;
if (
agent.reset &&
host.cursor !== null &&
agent.head !== null &&
host.cursor > agent.head
) {
void this.tell(agent, {
from_sequence: agent.head,
resumed_at: agent.head,
rooms: agent.reset.rooms,
all_rooms: true,
reason: agent.reset.reason,
});
host.cursor = agent.head;
}
this.refresh(agent);
this.pump(agent);
},
// Switch decides who may start a session from the agent's binding, not
// from what an agent host on this machine declares.
setSpawnCapable: () => {},
// A session placed in a room the agent is not in (any more: the room was
// deleted, or the agent taken out) is left out and named back; the rest
// are placed. Refusing the whole set for one gone room left every other
// session of the agent unplaced, and its room tools answered "not
// connected" though the session had just connected.
replacePlacements: async (placements) => {
if (host.closed || agent.host !== host)
throw new Error(
`this agent host no longer holds agent ${agentId}'s stream on the agent controller; a newer one does`
);
const refusedRooms = [...new Set(Object.values(placements))]
.filter((roomId) => agent.rooms !== null && !agent.rooms.has(roomId))
.sort();
const kept = Object.entries(placements).filter(
([, roomId]) => !refusedRooms.includes(roomId)
);
const rooms = kept.map(([, roomId]) => roomId);
const twice = [...new Set(rooms.filter((room, index) => rooms.indexOf(room) !== index))];
if (twice.length)
throw new Error(
`placements name room(s) ${twice.sort().join(', ')} for more than one session; one session of an agent acts in a room`
);
for (const roomId of refusedRooms) {
if (agent.refusedRooms.has(roomId)) continue;
agent.refusedRooms.add(roomId);
this.deps.log.warn('Left out a session placement in a room the agent is not in', {
agentId,
roomId,
});
}
agent.placements = new Map(kept);
this.deps.onChange();
return { refusedRooms };
},
};
}
// -- Internals --------------------------------------------------------------
private agent(agentId: string): AgentState {
let agent = this.agents.get(agentId);
if (!agent) {
agent = {
agentId,
attached: false,
rooms: null,
head: null,
attachedFrom: null,
hostStarted: false,
droppedThrough: 0,
confirmed: null,
buffer: [],
reset: null,
placements: new Map(),
refusedRooms: new Set(),
host: null,
overflowing: false,
};
this.agents.set(agentId, agent);
}
return agent;
}
private running(agent: AgentState): AgentHostLink | null {
const host = agent.host;
return host && host.started && !host.closed ? host : null;
}
private refreshAll(): void {
for (const agent of this.agents.values()) this.refresh(agent);
this.deps.onChange();
}
/** Tells the agent host when it gains or loses the agent's connection. */
private refresh(agent: AgentState): void {
const host = this.running(agent);
if (!host) return;
const connected = this.upstream && agent.attached;
if (connected === host.connected) return;
host.connected = connected;
if (connected) host.deps.onConnected?.();
else
host.deps.onDisconnected?.({
error: this.upstream
? 'Switch detached the agent from this controller.'
: 'The controller is reconnecting to Switch.',
});
this.deps.onChange();
}
private async tell(agent: AgentState, data: GapData): Promise<void> {
const host = this.running(agent);
if (!host) return;
const resumedAt = data.resumed_at;
try {
await host.deps.onGap({
fromSequence: data.from_sequence,
reason: data.reason,
...(data.rooms === undefined ? {} : { rooms: data.rooms }),
...(resumedAt === undefined
? {}
: { resumedAt, cursorReset: resumedAt < (host.cursor ?? 0) }),
});
} catch (error) {
this.deps.log.error('The agent host failed a gap', {
agentId: agent.agentId,
error: errorMessage(error),
});
}
}
/**
* Hands the agent host, one at a time and in order, everything past its cursor.
* Each event counts as taken once the agent host's handler resolves: it has
* queued or journalled it by then.
*/
private pump(agent: AgentState): void {
const host = this.running(agent);
if (!host || host.delivering || host.cursor === null) return;
host.delivering = true;
void (async () => {
try {
while (agent.host === host && !host.closed) {
if (host.cursor! < agent.droppedThrough) {
await this.tell(agent, {
from_sequence: host.cursor!,
resumed_at: agent.droppedThrough,
rooms: [...(agent.rooms ?? [])].sort(),
all_rooms: true,
reason:
'the agent controller no longer holds events this far back; re-read room context',
});
host.cursor = agent.droppedThrough;
}
const index = firstAfter(agent.buffer, host.cursor!);
const item = agent.buffer[index];
if (!item) break;
if (item.kind === 'gap')
await this.tell(agent, { ...item.data, from_sequence: host.cursor! });
else if (item.notifiable) await host.deps.onEvent(item.data);
if (agent.host !== host || host.closed) break;
host.cursor = item.seq;
this.confirm(agent, item.seq);
}
} catch (error) {
// The agent host has already recorded its own failure and is ending.
this.deps.log.error(
'The agent host failed an event; it stops, and resumes from its cursor',
{
agentId: agent.agentId,
error: errorMessage(error),
}
);
} finally {
host.delivering = false;
this.trim(agent);
}
})();
}
private confirm(agent: AgentState, cursor: number): void {
if (agent.confirmed !== null && cursor <= agent.confirmed) return;
agent.confirmed = cursor;
this.deps.onCursor(agent.agentId, cursor);
}
/** Drops what the agent host has taken, and the oldest past the limit. */
private trim(agent: AgentState): void {
const floor = agent.confirmed ?? -1;
let drop = 0;
while (drop < agent.buffer.length && agent.buffer[drop]!.seq <= floor) drop++;
let overflow = false;
if (agent.buffer.length - drop > this.deps.bufferLimit) {
drop = agent.buffer.length - this.deps.bufferLimit;
overflow = true;
}
if (drop > 0) {
agent.droppedThrough = Math.max(agent.droppedThrough, agent.buffer[drop - 1]!.seq);
agent.buffer.splice(0, drop);
}
if (overflow && !agent.overflowing)
this.deps.log.warn(
'The controller is holding more events than it keeps for an agent whose host is not taking them; the oldest are dropped, and the agent host is told when it starts',
{ agentId: agent.agentId, limit: this.deps.bufferLimit }
);
agent.overflowing = overflow;
}
}