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 {
MattermostChannel,
MattermostClient,
MattermostUser,
} from "../clients/mattermost-client.ts";
import {
sleep,
type RegisteredAgent,
type RoomDetail,
type SwitchClient,
} from "../clients/switch-client.ts";
import type { HarnessAgentType, HarnessEnv } from "../core/env.ts";
import type { NameScope } from "../core/run.ts";
/**
* What a scenario stands up, and the teardown that removes it.
*
* Every artefact is named through the run context and registered for teardown
* the moment it exists, so a scenario that fails halfway still cleans up what it
* made. Teardown runs newest first — rooms before the agents in them — and
* reports every failure rather than stopping at the first, because one leaked
* room should not hide another.
*/
export class Fixtures {
readonly env: HarnessEnv;
readonly names: NameScope;
readonly switchClient: SwitchClient;
readonly mattermost: MattermostClient | null;
private readonly cleanups: { label: string; run: () => Promise<void> }[] = [];
private readonly agentCleanups = new Map<
string,
{ label: string; run: () => Promise<void> }
>();
constructor(
env: HarnessEnv,
names: NameScope,
switchClient: SwitchClient,
mattermost: MattermostClient | null,
) {
this.env = env;
this.names = names;
this.switchClient = switchClient;
this.mattermost = mattermost;
}
/**
* Register an agent named for `role` in this scope.
*
* `autoSession` is off unless asked for: with it on, Switch expects a
* connector to spawn a session when the agent is addressed, and an operator's
* Console watching the same server could fight the harness for the room.
*
* The registration token's agents belong to a non-admin account. With
* `ownedByAdmin` the agent is registered by the signed-in gateway admin
* instead, for operations only a workspace admin's agent may call.
*/
async agent(
role: string,
options: {
autoSession?: boolean;
agentType?: HarnessAgentType;
repoDir?: string;
ownedByAdmin?: boolean;
} = {},
): Promise<RegisteredAgent> {
const name = this.names.name(role);
const description = `Switch end-to-end harness agent (run ${this.names.runId}). Safe to delete.`;
if (options.ownedByAdmin) {
if (options.autoSession || options.agentType || options.repoDir) {
throw new Error(
"ownedByAdmin registers a plain opencode agent; drop the other options",
);
}
return this.track(
await this.switchClient.registerAgentAsUser({ name, description }),
);
}
const agent = await this.switchClient.registerKnownAgent({
agentType: options.agentType ?? "opencode",
name,
description,
options: {
auto_session: options.autoSession ?? false,
...(options.repoDir ? { repo_dir: options.repoDir } : {}),
},
});
return this.track(agent);
}
private async track(agent: RegisteredAgent): Promise<RegisteredAgent> {
const name = agent.name;
const cleanup = {
label: `agent ${name} (${agent.id})`,
run: () => this.switchClient.deleteAgent(agent),
};
this.cleanups.push(cleanup);
this.agentCleanups.set(agent.id, cleanup);
await this.switchClient.openAddressing(agent.id);
return agent;
}
/** A room with no platform channel: agents only, no bridge involved. */
async internalRoom(
role: string,
agents: RegisteredAgent[],
): Promise<RoomDetail> {
const name = this.names.name(role);
const room = await this.switchClient.createRoom({
name,
description: `Switch end-to-end harness (run ${this.names.runId}). Safe to delete.`,
bridgeId: null,
agentNames: agents.map((agent) => agent.name),
userNames: [],
});
this.defer(`room ${name} (${room.id})`, () =>
this.switchClient.deleteRoom(room.id),
);
if (room.externalChannelId !== null) {
throw new Error(
`Internal-only room ${room.id} came back with a platform channel.`,
);
}
return room;
}
/**
* A room on the Mattermost bridge, with the human the harness posts as in its
* channel, and the bridge proven live in both directions' first hop.
*
* Created from the gateway so Switch provisions the channel and adds the bots
* itself. The other route — make a channel, add a bot — creates no room when
* the bot is the first in a new channel, because nobody's websocket witnesses
* the join.
*/
async mattermostRoom(
role: string,
agents: RegisteredAgent[],
): Promise<BridgedRoom> {
const mattermost = this.requireMattermost();
const human = await mattermost.me();
const bridgeId = await this.switchClient.defaultBridgeId("mattermost");
// Resolved even though room creation does not need it: it fails fast and
// clearly when MATTERMOST_TEAM names a team that does not exist.
await mattermost.findTeam(this.mattermostTeam());
// Registration mints each agent's bot; wait for them so the room's members
// and any later `@name` mention have accounts to resolve to.
const bots = new Map<string, MattermostUser>();
for (const agent of agents) {
bots.set(agent.id, await mattermost.waitForBotUser(agent.name, 60_000));
}
const name = this.names.name(role);
const room = await this.switchClient.createRoom({
name,
description: `Switch end-to-end harness (run ${this.names.runId}). Safe to delete.`,
bridgeId,
agentNames: agents.map((agent) => agent.name),
userNames: [human.username],
});
const channelId = room.externalChannelId;
// One step, in order: the room first, then its channel only if deleting the
// room did not already archive it.
this.defer(
`room ${name} (${room.id}) and channel ${channelId ?? "none"}`,
async () => {
await this.switchClient.deleteRoom(room.id);
if (channelId === null) return;
const left = await mattermost.getChannel(channelId);
if (!left.delete_at) await mattermost.archiveChannel(channelId);
},
);
if (channelId === null) {
throw new Error(
`Switch room ${room.id} was created without a Mattermost channel — ` +
`the collaboration bridge did not provision one.`,
);
}
const channel = await mattermost.getChannel(channelId);
const bridged: BridgedRoom = { room, channel, human, bots };
const witness = agents[0];
if (!witness) throw new Error("A bridged room needs at least one agent.");
await waitForBridgeReady({
switchClient: this.switchClient,
mattermost,
agent: witness,
room,
channel,
runId: this.names.runId,
});
return bridged;
}
/**
* The scenario deleted `agent` itself, and checked that it is gone, so
* teardown has nothing left to remove for it.
*/
removed(agent: RegisteredAgent): void {
const cleanup = this.agentCleanups.get(agent.id);
if (cleanup === undefined)
throw new Error(`Agent ${agent.id} was not registered here.`);
this.agentCleanups.delete(agent.id);
this.cleanups.splice(this.cleanups.indexOf(cleanup), 1);
}
/** Register a cleanup step for something created outside these helpers. */
defer(label: string, run: () => Promise<void>): void {
this.cleanups.push({ label, run });
}
/**
* Undo everything, newest first. Never throws: a teardown failure must not
* mask the scenario's result. Returns what could not be removed, so the
* caller can print it and an operator can clean up by hand.
*/
async teardown(): Promise<string[]> {
if (this.env.keepArtifacts) {
const kept = this.cleanups.map((cleanup) => cleanup.label);
this.cleanups.length = 0;
return kept.map((label) => `kept (SWITCH_E2E_KEEP=1): ${label}`);
}
const failures: string[] = [];
while (this.cleanups.length > 0) {
const cleanup = this.cleanups.pop()!;
try {
await cleanup.run();
} catch (error) {
failures.push(
`could not remove ${cleanup.label}: ${error instanceof Error ? error.message : String(error)}`,
);
}
}
return failures;
}
private requireMattermost(): MattermostClient {
if (!this.mattermost) {
throw new Error(
"This scenario needs Mattermost but none is configured — declare " +
"`requires: ['mattermost']` in its header so it is skipped or failed up front.",
);
}
return this.mattermost;
}
private mattermostTeam(): string {
if (!this.env.mattermost) throw new Error("No Mattermost configured.");
return this.env.mattermost.team;
}
}
export interface BridgedRoom {
room: RoomDetail;
channel: MattermostChannel;
/** The human the harness posts as. */
human: MattermostUser;
/** Each agent's Mattermost bot, by agent id. A bot's username is the agent's name. */
bots: Map<string, MattermostUser>;
}
/**
* Block until a plain channel message actually reaches Switch.
*
* This is not belt-and-braces. The Mattermost adapter reads inbound posts off
* its bots' websockets, and each bot's socket is opened on a background thread
* after the bot account is created — the server log shows
* `Websocket authentification OK` arriving after the room already exists. A
* message posted before any bot in the channel is listening is silently
* dropped, which shows up later as a scenario that times out for no visible
* reason. A post is handled whichever bot's socket it arrives on (the adapter
* dedupes by post id), so one bot's socket being up is enough for the room to
* hear a message: the probe may read through any agent in the room.
*
* The probe is deliberately **unaddressed**: it proves Mattermost → Switch
* delivery without putting an `@agent` mention on the wire, so it cannot spawn a
* console session or consume a turn. It is read back through the agent's room
* history, which carries ordinary chatter, rather than the notification stream,
* which by design carries only addressed messages.
*/
export async function waitForBridgeReady(params: {
switchClient: SwitchClient;
mattermost: MattermostClient;
agent: RegisteredAgent;
room: RoomDetail;
channel: MattermostChannel;
runId: string;
deadlineMs?: number;
}): Promise<void> {
const deadlineMs = params.deadlineMs ?? 120_000;
const probe = `switch-e2e-bridge-probe ${params.runId}`;
const until = Date.now() + deadlineMs;
while (Date.now() < until) {
// Re-post rather than only re-read: if the socket was down when the last
// one went out, that message is gone for good and no amount of polling
// will produce it.
await params.mattermost.post({
channelId: params.channel.id,
message: probe,
});
const history = await params.switchClient.roomHistory(
params.agent,
params.room.id,
50,
);
if (history.some((event) => event.body.includes(probe))) return;
await sleep(5_000);
}
throw new Error(
`Mattermost -> Switch delivery never came up for room ${params.room.id} ` +
`(channel ${params.channel.id}) within ${deadlineMs}ms: a plain channel message ` +
`never reached the agent's room history. The agent bot's websocket is probably not connected.`,
);
}