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 { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import {
type CallerContext,
callOperation,
loadOperations,
SESSION_SELECTOR_HEADERS,
SwitchToolCatalog,
type SwitchIdentity,
type ToolResult,
} from '@sandboxaq/switch-agent-runtime/hosted';
import { z } from 'zod';
import type { PlacementMap, SessionPlacements } from './placements';
import type { Redactions } from './redaction';
import { issueServiceToken, readServiceGrants } from './service-access';
import { AgentServiceTokens } from './service-tokens';
import type { AskHandler, Caller, HostAsk } from './session-channel';
import { sharedConfigSchema } from './shared-config';
/**
* The watcher's answer to its sessions' tool calls.
*
* Each session host serves the Switch tools to its CLI and forwards every
* call here, the one process holding the agent's credentials and connection.
* A call is made as the calling session: the agent's token, the watcher's
* connection id, and the selector naming the session, its host and its
* generation. `connect_to_room` is also a local move: the room is placed with
* the calling session before Switch is asked, so the room's next message
* reaches it, and put back as it was if Switch refuses. Behind an agent
* controller, whose relay names each call's room from the placements, a move
* the controller does not take is put back and refused as well: Switch only
* checked membership, and the session would otherwise be told it connected
* and then find every call made from no room.
*
* It also answers the sessions' asks for service tokens (`AgentServiceTokens`),
* and scrubs every token handed out from the arguments of every call it makes,
* so a token an agent echoes into a room message never reaches Switch.
*/
export function sessionToolAnswerer(deps: {
identity: SwitchIdentity;
connectionId: string;
placements: SessionPlacements;
/** States every placement to Switch; raises when Switch does not take them. */
publish: () => Promise<void>;
/**
* Whether a call's room is named from the stated placements rather than
* recorded by Switch on `connect_to_room` (`AgentEventStream`).
*/
placementsNameCallRooms: () => boolean;
/** The service tokens handed out in this process, added to as more are. */
redactions: Redactions;
}): AskHandler {
const services = new AgentServiceTokens({
endpoint: deps.identity,
redactions: deps.redactions,
now: Date.now,
issue: issueServiceToken,
readGrants: readServiceGrants,
});
let catalog: Promise<SwitchToolCatalog> | null = null;
const tools = (): Promise<SwitchToolCatalog> => {
catalog ??= loadOperations(deps.identity).then(
(operations) => new SwitchToolCatalog(operations),
(error: unknown) => {
catalog = null;
throw error;
}
);
return catalog;
};
const context = async (caller: Caller): Promise<CallerContext> => {
const saved = sharedConfigSchema.parse(
JSON.parse(await readFile(join(caller.root, 'config.json'), 'utf8'))
);
return {
identity: deps.identity,
connectionId: deps.connectionId,
selector: {
[SESSION_SELECTOR_HEADERS.sessionId]: caller.sessionId,
[SESSION_SELECTOR_HEADERS.hostId]: caller.hostId,
[SESSION_SELECTOR_HEADERS.epoch]: caller.epoch,
},
room: deps.placements.roomOf(caller.sessionId),
mediaDir: join(caller.root, 'media'),
cwd: saved.start.input.cwd,
deadConnection: (operation) =>
`Switch refused ${operation}: this agent's connection (${deps.connectionId}) had lapsed. ` +
'The room watcher holding it reopens it within a few seconds — retry the call. If it ' +
'keeps failing, the watcher has stopped; check the agent in Switch Console.',
};
};
// One room move at a time, so the local map and Switch see moves in the
// same order and a refused move restores the state it actually replaced.
let moves: Promise<unknown> = Promise.resolve();
const connect = (
caller: Caller,
catalog: SwitchToolCatalog,
args: Record<string, unknown>
): Promise<ToolResult> => {
const move = moves.then(() => connectNow(caller, catalog, args));
moves = move.catch(() => {});
return move;
};
const connectNow = async (
caller: Caller,
catalog: SwitchToolCatalog,
args: Record<string, unknown>
): Promise<ToolResult> => {
const roomId = args.room_id;
const ctx = await context(caller);
if (typeof roomId !== 'string' || !roomId) return catalog.call(ctx, 'connect_to_room', args);
const before = deps.placements.snapshot();
const { displaced } = await deps.placements.place(caller.sessionId, roomId);
const result = await catalog.call(ctx, 'connect_to_room', args);
if (result.isError) {
await deps.placements.restore(before);
return result;
}
let notTaken: string | null = null;
try {
await deps.publish();
// A room the controller left out and named back (it does not count the
// agent as in it yet) is taken off the session by the publish itself.
if (deps.placementsNameCallRooms() && deps.placements.roomOf(caller.sessionId) !== roomId)
notTaken = `the agent controller does not count room ${roomId} among this agent's rooms yet`;
} catch (error) {
const reason = error instanceof Error ? error.message : String(error);
// Over the agent's own connection Switch placed the session on connect,
// and a later statement puts the copy right.
if (deps.placementsNameCallRooms()) notTaken = reason;
else
console.warn(
`Switch did not take this agent's session placements after session ${caller.sessionId} connected to room ${roomId}: ${reason}. They are stated again on the next change or reconnect.`
);
}
if (notTaken !== null) {
await deps.placements.restore(before);
// So what the stream states on its next change or reconnect is the map
// put back, not the move it did not take.
await deps.publish().catch(() => {});
console.warn(
`The agent controller did not take session ${caller.sessionId}'s move to room ${roomId}: ${notTaken}. The move was put back and connect_to_room refused.`
);
return {
isError: true,
content: [
{
type: 'text',
text:
'connect_to_room did not take effect: Switch accepted it, but the agent controller ' +
`running this agent did not record the move to room ${roomId} (${notTaken}), so your ` +
'calls would not be made from that room. Call connect_to_room again; if it keeps ' +
"failing, the agent controller's log says why.",
},
],
};
}
if (!displaced) return result;
const warning =
`Room ${roomId} was being attended by another session of this agent on the same machine ` +
`(${displaced}). That session no longer receives the room's messages; this one does. ` +
'Work in progress there may have been interrupted.';
console.warn(`Session ${caller.sessionId} took room ${roomId} from session ${displaced}.`);
const previous = result.structuredContent?.warning;
return {
...result,
content: [...result.content, { type: 'text', text: warning }],
...(result.structuredContent
? {
structuredContent: {
...result.structuredContent,
warning:
typeof previous === 'string' && previous ? `${previous}\n${warning}` : warning,
},
}
: {}),
};
};
/**
* Posts, as the session, a reply its turn left unposted. Only into the room
* the turn came from, and only while the session still attends it: a post
* goes to whichever room the session holds, and one it has moved to since
* did not ask.
*/
const roomReply = async (
caller: Caller,
catalog: SwitchToolCatalog,
ask: Extract<HostAsk, { type: 'room-reply' }>
): Promise<null> => {
const attended = deps.placements.roomOf(caller.sessionId);
if (attended !== ask.roomId)
throw new Error(
`Session ${caller.sessionId} no longer attends room ${ask.roomId}${attended ? ` (it attends ${attended})` : ''}, so its reply was not posted there.`
);
// Stated again first: a reply is posted as the session, in the room Switch
// holds it in, and the placement it was refused on may be the reason the
// turn could not post itself.
await deps
.publish()
.catch((error: unknown) =>
console.warn(
`Could not state the session placements before posting a reply for session ${caller.sessionId}: ${error instanceof Error ? error.message : String(error)}`
)
);
const posted = await catalog.call(await context(caller), 'post_message', {
body: deps.redactions.text(ask.body),
...(ask.threadId ? { thread_id: ask.threadId } : {}),
});
if (posted.isError) throw new Error(resultText(posted));
return null;
};
/**
* The instructions of the room the session attends, read through
* `connect_to_room`, which for an agent whose controller places its sessions
* checks membership and returns the room's context without claiming
* anything. Called directly rather than as the session's own connect: that
* one also places the session, and a session that has moved on since the
* message was handed over is not to be moved back.
*/
const roomInstructions = async (
caller: Caller,
catalog: SwitchToolCatalog,
ask: Extract<HostAsk, { type: 'room-instructions' }>
): Promise<{ instructions: string }> => {
const attended = deps.placements.roomOf(caller.sessionId);
if (attended !== ask.roomId)
throw new Error(
`Session ${caller.sessionId} no longer attends room ${ask.roomId}${attended ? ` (it attends ${attended})` : ''}, so its instructions were not read.`
);
const result = await catalog.call(await context(caller), 'connect_to_room', {
room_id: ask.roomId,
include_general_instructions: false,
});
if (result.isError) throw new Error(resultText(result));
const instructions = result.structuredContent?.instructions;
if (typeof instructions !== 'string')
throw new Error(`connect_to_room answered for room ${ask.roomId} without its instructions.`);
return { instructions: instructions.replace(ROOM_SECTION_HEADING, '').trim() };
};
return async (caller, ask) => {
if (ask.type === 'service-token') return services.answer(ask.service, ask.rejected);
const catalog = await tools();
if (ask.type === 'tools') return catalog.tools();
if (ask.type === 'room-reply') return roomReply(caller, catalog, ask);
if (ask.type === 'room-instructions') return roomInstructions(caller, catalog, ask);
const args = deps.redactions.value(ask.arguments);
if (ask.name === 'connect_to_room') return connect(caller, catalog, args);
return catalog.call(await context(caller), ask.name, args);
};
}
/** The heading `connect_to_room` puts over a room's own instructions (`build_room_instructions`). */
const ROOM_SECTION_HEADING = /^## Room-specific instructions\s*/;
function resultText(result: ToolResult): string {
return result.content.map((part) => part.text).join('\n');
}
/**
* Tells a room that the session started to answer it could not start, and
* why: as the agent, in the thread the message came from, and addressed to
* the agent's owner, who is the one able to fix what stopped it (a provider
* CLI that is not signed in, say). Raises when the room could not be told.
*
* The call is made as the session, so Switch must already know the room is
* placed with it.
*/
/** The notice a room gets while a session starts to answer it. */
export const SESSION_STARTING_MESSAGE = 'Starting a session to handle this — one moment.';
/**
* Tells the room a session is starting for its message, as the session that
* will answer: in the thread the message was in, so the answer follows it.
*/
export async function announceSessionStart(input: {
identity: SwitchIdentity;
connectionId: string;
session: { sessionId: string; hostId: string; epoch: string };
root: string;
cwd: string;
threadId: string | null;
}): Promise<void> {
const ctx: CallerContext = {
identity: input.identity,
connectionId: input.connectionId,
selector: {
[SESSION_SELECTOR_HEADERS.sessionId]: input.session.sessionId,
[SESSION_SELECTOR_HEADERS.hostId]: input.session.hostId,
[SESSION_SELECTOR_HEADERS.epoch]: input.session.epoch,
},
room: null,
mediaDir: join(input.root, 'media'),
cwd: input.cwd,
deadConnection: (operation) =>
`Switch refused ${operation}: this agent's connection (${input.connectionId}) had lapsed.`,
};
const posted = await callOperation(ctx, 'post_message', {
body: SESSION_STARTING_MESSAGE,
...(input.threadId ? { thread_id: input.threadId } : {}),
});
if (posted.isError) throw new Error(resultText(posted));
}
export async function announceStartFailure(input: {
identity: SwitchIdentity;
connectionId: string;
session: { sessionId: string; hostId: string; epoch: string };
root: string;
cwd: string;
threadId: string | null;
failure: string;
}): Promise<void> {
const ctx: CallerContext = {
identity: input.identity,
connectionId: input.connectionId,
selector: {
[SESSION_SELECTOR_HEADERS.sessionId]: input.session.sessionId,
[SESSION_SELECTOR_HEADERS.hostId]: input.session.hostId,
[SESSION_SELECTOR_HEADERS.epoch]: input.session.epoch,
},
room: null,
mediaDir: join(input.root, 'media'),
cwd: input.cwd,
deadConnection: (operation) =>
`Switch refused ${operation}: this agent's connection (${input.connectionId}) had lapsed.`,
};
const thread = input.threadId ? { thread_id: input.threadId } : {};
const detail = await callOperation(ctx, 'get_agent_detail', {
agent_id: input.identity.agentId,
});
const owner = detail.isError ? null : detail.structuredContent?.owner_name;
if (typeof owner === 'string' && owner) {
const targeted = await callOperation(ctx, 'send_targeted_message', {
body: `I couldn't start a session, and it needs you to fix it: ${input.failure} Then address me again.`,
target_names: [owner],
...thread,
});
if (!targeted.isError) return;
console.warn(
`Could not address this agent's owner (${owner}) about session ${input.session.sessionId} failing to start: ${resultText(targeted)}. Telling the room without addressing them.`
);
const posted = await callOperation(ctx, 'post_message', {
body: `I couldn't start a session, and my owner (${owner}) needs to fix it: ${input.failure} Then address me again.`,
...thread,
});
if (posted.isError) throw new Error(resultText(posted));
return;
}
console.warn(
`Could not find this agent's owner to tell about session ${input.session.sessionId} failing to start${
detail.isError ? ` (${resultText(detail)})` : ''
}. Telling the room without addressing them.`
);
const posted = await callOperation(ctx, 'post_message', {
body: `I couldn't start a session, and my owner needs to fix it: ${input.failure} Then address me again.`,
...thread,
});
if (posted.isError) throw new Error(resultText(posted));
}
/** What moving a room to a session did. */
export type PlaceOutcome = {
sessionId: string;
roomId: string;
/** The room the session attended before, if another. */
previous: string | null;
/** The session that attended the room until now, if another. */
displaced: string | null;
};
/**
* Where a room watcher is with the agent's connection to Switch.
*
* - `not-running`: no watcher runs on this control (not started yet, or it
* stopped; `detail` says why when it failed).
* - `disabled`: the watcher found the agent's room connection turned off and
* stopped.
* - `taken-over`: the watcher stood down because another client holds the
* agent's connection.
* - `connecting`: running, and the stream has not confirmed an open yet.
* - `connected`: Switch confirmed the stream's open and it has not ended since.
* - `disconnected`: an open failed or the open stream ended; it is retrying.
*/
export const watcherStateSchema = z.enum([
'not-running',
'disabled',
'taken-over',
'connecting',
'connected',
'disconnected',
]);
export type WatcherState = z.infer<typeof watcherStateSchema>;
export const watcherHealthSchema = z.object({
state: watcherStateSchema,
/** The stream's last error, why the watcher stopped, or why it stood down. */
detail: z.string().nullable(),
/** When `state` began, as an ISO timestamp. */
since: z.string(),
/** Session id → room id, as the watcher routes now. Empty while it is not running. */
placements: z.record(z.string(), z.string()),
/**
* The agent's sessions whose host runs here and is mid-turn, or has not yet
* said whether it is. Absent from a watcher too old to report it.
*/
busy: z.array(z.string()).optional(),
});
export type WatcherHealth = z.infer<typeof watcherHealthSchema>;
/** What a running watcher answers for, through its control. */
export type WatcherHandlers = {
place: (sessionId: string, roomId: string) => Promise<PlaceOutcome>;
forget: (sessionId: string) => Promise<void>;
warm: (roomId: string) => Promise<string | null>;
};
/**
* Reaches a running watcher from outside it: Console's "Reconnect to room",
* locally by a direct call and remotely through the sidecar's control port;
* and the watcher's own account of its connection and placements, which it
* keeps current here.
*/
export class WatcherControl {
private handlers: WatcherHandlers | null = null;
private current: WatcherHealth = {
state: 'not-running',
detail: null,
since: new Date().toISOString(),
placements: {},
};
private readonly healthListeners = new Set<(health: WatcherHealth) => void>();
/** Called by the watcher while it runs; the returned function unbinds it. */
bind(handlers: WatcherHandlers): () => void {
if (this.handlers) throw new Error('A room watcher is already bound to this control.');
this.handlers = handlers;
return () => {
if (this.handlers === handlers) this.handlers = null;
};
}
/** Whether a watcher is running behind this control. */
get running(): boolean {
return this.handlers !== null;
}
/**
* Forget a session Console deleted: stop its host, take its rooms off it,
* drop what was queued for it and remove its state, so the room's next
* message starts a new session rather than reaching the deleted one.
* Refused when no watcher is running.
*/
forget(sessionId: string): Promise<void> {
if (!this.handlers)
return Promise.reject(new Error("The agent's room watcher is not running."));
return this.handlers.forget(sessionId);
}
/** Move a room's messages to this session. Refused when no watcher is running. */
place(sessionId: string, roomId: string): Promise<PlaceOutcome> {
if (!this.handlers)
return Promise.reject(
new Error(
"The agent's room watcher is not running, so no session can be moved to a room. Turn the agent's room connection on first."
)
);
return this.handlers.place(sessionId, roomId);
}
/**
* Start the session a message to this room would start, or confirm the one
* placed there, without a message: a chat just created or reopened.
* Resolves to that session, or null when the agent may not start one.
* Refused when no watcher is running.
*/
warm(roomId: string): Promise<string | null> {
if (!this.handlers)
return Promise.reject(new Error("The agent's room watcher is not running."));
return this.handlers.warm(roomId);
}
health(): WatcherHealth {
return this.current;
}
/** Called with the new state after every change; the returned function stops it. */
onHealth(listener: (health: WatcherHealth) => void): () => void {
this.healthListeners.add(listener);
return () => this.healthListeners.delete(listener);
}
/**
* Called by the watcher as its state changes. A new state without a `detail`
* clears the old one; `since` moves only when the state does.
*/
report(change: {
state?: WatcherState;
detail?: string | null;
placements?: PlacementMap;
busy?: string[];
}): void {
const state = change.state ?? this.current.state;
const same = state === this.current.state;
const next: WatcherHealth = {
state,
detail: change.detail !== undefined ? change.detail : same ? this.current.detail : null,
since: same ? this.current.since : new Date().toISOString(),
placements: change.placements ? { ...change.placements } : this.current.placements,
...(change.busy
? { busy: [...change.busy].sort() }
: this.current.busy
? { busy: this.current.busy }
: {}),
};
if (
same &&
next.detail === this.current.detail &&
samePlacements(next.placements, this.current.placements) &&
sameList(next.busy, this.current.busy)
)
return;
this.current = next;
for (const listener of this.healthListeners) {
try {
listener(next);
} catch (error) {
console.error(`A room watcher health listener failed: ${String(error)}`);
}
}
}
}
function sameList(a: string[] | undefined, b: string[] | undefined): boolean {
if (!a || !b) return a === b;
return a.length === b.length && a.every((value, index) => value === b[index]);
}
function samePlacements(a: PlacementMap, b: PlacementMap): boolean {
const keys = Object.keys(a);
return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
}