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 { randomBytes } from "node:crypto";
import { request as httpRequest } from "node:http";
import { request as httpsRequest } from "node:https";
import type { Environment, SwitchEnv } from "../core/env.ts";
import { assertAllowed } from "../core/guard.ts";
import type { IssuedSecrets } from "../core/secrets.ts";
/**
* Thin client for the two Switch HTTP surfaces the harness talks to, both served
* by the same origin (`SWITCH_API_URL`):
*
* - the **agent bridge** at `/agents/...`, authenticated with either the
* registration token (to mint an agent) or an agent's own API key (to act as
* that agent);
* - the **gateway** at `/gateway/...`, authenticated with the session cookie
* from `POST /gateway/auth/login`.
*
* Every request passes the read-only guard first (`core/guard.ts`).
*
* Only endpoints this harness has actually exercised against a live server are
* modelled here; see README.md for the verified request/response shapes.
*/
export interface AgentRef {
id: string;
name: string;
}
export interface RegisteredAgent extends AgentRef {
apiKey: string;
}
export interface RoomSummary {
id: string;
name: string;
createdAt: string;
bridgeId: string | null;
bridgeType: string | null;
archived: boolean;
}
export interface RoomDetail extends RoomSummary {
externalChannelId: string | null;
matrixRoomId: string | null;
agentIds: string[];
}
/** The management API's agent definition (v1), as much of it as the harness sets. */
export interface ManagedAgentDefinition {
provider: string;
model: string | null;
instructions: string;
auto_mode: boolean;
auto_approve: boolean;
directory: string | null;
}
export interface AgentSummary {
id: string;
name: string;
createdAt: string;
}
/**
* One event off the agent-facing notification stream.
*
* The message text is **`payload.body`**, not a top-level `content` — an event
* looks like:
*
* ```json
* { "type": "message", "room_id": "…", "bridge_id": "…",
* "channel_type": "channel_public",
* "payload": { "addressed": true, "sender": "@switch-mattermost-…:localhost",
* "sender_name": "user", "message_id": "$…",
* "body": "@agent hello", "timestamp": 1788…, "thread_id": null,
* "attachments": [] } }
* ```
*/
/** One row of `GET /gateway/tenants/{tenant_id}/usage`: an amount per metric, client and model. */
export interface UsageTotal {
metric: string;
clientId: string;
clientName: string | null;
model: string;
amount: number;
}
export interface AgentEvent {
type: string;
room_id?: string;
bridge_id?: string;
channel_type?: string;
payload?: {
addressed?: boolean;
sender?: string;
sender_name?: string;
message_id?: string;
body?: string;
timestamp?: number;
thread_id?: string | null;
attachments?: unknown[];
[key: string]: unknown;
};
meta?: Record<string, unknown>;
[key: string]: unknown;
}
/** The human-readable text of an event, or `''` when it carries none. */
export function eventText(event: AgentEvent): string {
const body = event.payload?.body;
return typeof body === "string" ? body : "";
}
/** What a route answered to a probe: its status, and what it said its body was. */
export interface RouteProbe {
status: number;
contentType: string;
/** The `X-Request-Id` the request carried, which the server's log lines for it name; null untagged. */
requestId: string | null;
}
export class SwitchHttpError extends Error {
readonly status: number;
readonly body: string;
readonly method: string;
readonly path: string;
constructor(method: string, path: string, status: number, body: string) {
super(`${method} ${path} -> ${status}: ${truncate(body, 400)}`);
this.name = "SwitchHttpError";
this.status = status;
this.body = body;
this.method = method;
this.path = path;
}
}
/** An agent's addressing policy: anyone no rule matches is refused. */
export interface AddressingPolicy {
rules: {
rooms: "*" | string[];
room_groups: "*" | string[];
users: "*" | string[];
agents: "*" | string[];
owner: boolean;
owner_agents: boolean;
platform: boolean;
}[];
}
/** Only the agent's owner, and the platform identities its owner claimed. */
export const OWNER_ONLY: AddressingPolicy = {
rules: [
{
rooms: "*",
room_groups: "*",
users: [],
agents: [],
owner: true,
owner_agents: false,
platform: false,
},
],
};
/** What a template run made. */
export interface TemplateRun {
created_agents: {
slot: string;
agent_id: string;
name: string;
machine: { id: string; name: string };
listening: boolean;
}[];
room: { room_id: string; room_name: string; failed_attachments: unknown[] };
}
/** A template run the server refused, having created nothing. */
export class TemplateRefusal extends Error {
readonly problems: { slot: string; code: string; message: string }[];
constructor(
cause: SwitchHttpError,
problems: { slot: string; code: string; message: string }[],
) {
super(cause.message, { cause });
this.name = "TemplateRefusal";
this.problems = problems;
}
}
/**
* The reason code of a management API refusal (`{"error": {"code": …}}`), or
* null when the error is not one.
*/
export function managementErrorCode(error: unknown): string | null {
if (!(error instanceof SwitchHttpError)) return null;
try {
const parsed = JSON.parse(error.body) as { error?: { code?: unknown } };
return typeof parsed.error?.code === "string" ? parsed.error.code : null;
} catch {
return null;
}
}
/** A FastAPI error body's `detail` when it is a string, else the body as it came. */
export function errorDetail(body: string): string {
try {
const parsed = JSON.parse(body) as { detail?: unknown };
return typeof parsed.detail === "string" ? parsed.detail : body;
} catch {
return body;
}
}
function truncate(text: string, max: number): string {
return text.length > max ? `${text.slice(0, max)}…` : text;
}
interface SwitchRequest {
token?: string;
cookie?: string;
body?: unknown;
timeoutMs?: number;
}
export interface OrganizationSummary {
id: string;
slug: string;
name: string;
role: string;
}
export interface WorkspaceMembership {
id: string;
slug: string;
name: string;
role: string;
organization_role: string | null;
organization_id: string | null;
}
/** A workspace's message retention window; `message_retention_days: null` keeps messages forever. */
export interface RetentionPolicy {
message_retention_days: number | null;
updated_at: string | null;
updated_by_user_id: string | null;
}
/** One row of `GET /gateway/tenants/{tenant_id}/people`. `kind: 'member'` is someone taking part from Switch Console. */
export interface Person {
id: string;
kind: "identity" | "former" | "member";
username: string;
platform: string;
message_count: number;
}
export interface Erasure {
id: string;
state: "queued" | "running" | "done" | "failed";
messages_deleted: number;
error: string | null;
}
export class SwitchClient {
private readonly apiUrl: string;
/** The deployment-wide registration key; agents it registers belong to a bootstrap account. */
private readonly registrationToken: string;
private readonly adminEmail: string;
private readonly adminPassword: string;
private readonly environment: Environment;
private readonly issued: IssuedSecrets;
private gatewayCookie: string | null = null;
// Shared with every client `as()` makes, so one scenario's requests carry
// one tag, numbered without repeats, whichever user sent them.
private tagging: { tag: string | null; count: number } = {
tag: null,
count: 0,
};
constructor(env: SwitchEnv, environment: Environment, issued: IssuedSecrets) {
this.apiUrl = env.apiUrl;
this.registrationToken = env.agentRegistrationToken;
this.adminEmail = env.gatewayAdminEmail;
this.adminPassword = env.gatewayAdminPassword;
this.environment = environment;
this.issued = issued;
}
// ── plumbing ──────────────────────────────────────────────────────────────
/**
* Tag every request from now on with `X-Request-Id: <tag>-<n>`, which the
* server stamps on each log line it writes while serving it. `null` stops.
*/
tagRequests(tag: string | null): void {
this.tagging.tag = tag;
this.tagging.count = 0;
}
private requestId(): Record<string, string> {
if (this.tagging.tag === null) return {};
this.tagging.count += 1;
return { "X-Request-Id": `${this.tagging.tag}-${this.tagging.count}` };
}
private async request<T>(
method: string,
path: string,
init: SwitchRequest = {},
): Promise<T> {
return (await this.rawRequest(method, path, init)).parsed as T;
}
private async rawRequest(
method: string,
path: string,
init: SwitchRequest,
): Promise<{ parsed: unknown; response: Response }> {
assertAllowed(this.environment, method, path);
const headers: Record<string, string> = {
Accept: "application/json",
...this.requestId(),
};
if (init.token) headers.Authorization = `Bearer ${init.token}`;
if (init.cookie) headers.Cookie = init.cookie;
if (init.body !== undefined) headers["Content-Type"] = "application/json";
const response = await fetch(`${this.apiUrl}${path}`, {
method,
headers,
body: init.body === undefined ? undefined : JSON.stringify(init.body),
redirect: "manual",
signal: AbortSignal.timeout(init.timeoutMs ?? 30_000),
});
if (!response.ok) {
throw new SwitchHttpError(
method,
path,
response.status,
await response.text(),
);
}
if (response.status === 204) return { parsed: undefined, response };
const text = await response.text();
return { parsed: text === "" ? undefined : JSON.parse(text), response };
}
/**
* The status a request with no credential at all gets: no cookie, no bearer
* key, no body. For the check that every route which takes a session refuses
* a request without one.
*/
async statusWithoutCredentials(
method: string,
path: string,
): Promise<RouteProbe> {
return this.probe(method, path, null);
}
/**
* What a request with this client's signed-in session, and no body, gets:
* its status and content type. For the check that one workspace's member
* is refused another workspace's resources.
*/
async statusWithSession(method: string, path: string): Promise<RouteProbe> {
return this.probe(method, path, await this.gatewayLogin());
}
private async probe(
method: string,
path: string,
cookie: string | null,
): Promise<RouteProbe> {
if (method === "WS") return this.upgradeProbe(path, cookie);
assertAllowed(this.environment, method, path);
const tag = this.requestId();
const response = await fetch(`${this.apiUrl}${path}`, {
method,
headers: {
Accept: "application/json",
...(cookie === null ? {} : { Cookie: cookie }),
...tag,
},
redirect: "manual",
signal: AbortSignal.timeout(30_000),
});
await response.body?.cancel();
return {
status: response.status,
contentType: response.headers.get("content-type") ?? "",
requestId: tag["X-Request-Id"] ?? null,
};
}
/**
* A WebSocket route's answer to its opening handshake: `fetch` cannot send
* an upgrade, so this is the raw HTTP request a client's socket starts with.
* A refused handshake answers with an ordinary status (401 without a
* session); an accepted one answers 101, and the socket is dropped at once.
*/
private upgradeProbe(path: string, cookie: string | null): Promise<RouteProbe> {
// The handshake is a GET, and a refused one changes nothing.
assertAllowed(this.environment, "GET", path);
const tag = this.requestId();
const url = new URL(`${this.apiUrl}${path}`);
const send = url.protocol === "https:" ? httpsRequest : httpRequest;
return new Promise((resolve, reject) => {
const request = send(url, {
headers: {
Connection: "Upgrade",
Upgrade: "websocket",
"Sec-WebSocket-Version": "13",
"Sec-WebSocket-Key": randomBytes(16).toString("base64"),
...(cookie === null ? {} : { Cookie: cookie }),
...tag,
},
timeout: 30_000,
});
const requestId = tag["X-Request-Id"] ?? null;
request.on("response", (response) => {
response.resume();
resolve({
status: response.statusCode ?? 0,
contentType: response.headers["content-type"] ?? "",
requestId,
});
});
request.on("upgrade", (response, socket) => {
socket.destroy();
resolve({ status: response.statusCode ?? 101, contentType: "", requestId });
});
request.on("timeout", () => request.destroy(new Error(`No answer to the handshake on ${path}`)));
request.on("error", reject);
request.end();
});
}
/**
* The same server, signed in as someone else. Shares this client's record of
* issued credentials, so the other session is scanned for too, and its
* request tagging, so a scenario observing this client sees the other's
* requests as its own.
*/
as(email: string, password: string): SwitchClient {
const other = new SwitchClient(
{
apiUrl: this.apiUrl,
agentRegistrationToken: this.registrationToken,
gatewayAdminEmail: email,
gatewayAdminPassword: password,
},
this.environment,
this.issued,
);
other.tagging = this.tagging;
return other;
}
/** `POST /gateway/users` — a user in the signed-in admin's workspace. `role: 'admin'` makes a deployment operator. */
async createUser(params: {
name: string;
email: string;
password: string;
role: "user" | "admin";
}): Promise<{ id: string }> {
return this.gateway<{ id: string }>("POST", "/users", params);
}
/**
* `POST /gateway/tenants` — create a workspace. The caller becomes its admin
* and the server re-mints their session into it, so from here on this client
* acts in the new workspace.
*/
async createTenant(name: string): Promise<string> {
const { parsed, response } = await this.rawRequest(
"POST",
"/gateway/tenants",
{
cookie: await this.gatewayLogin(),
body: { name },
},
);
const cookie = sessionCookieFrom(response);
if (!cookie)
throw new Error(
"Creating a workspace returned no switch_auth cookie for it.",
);
this.issued.record(cookie.slice("switch_auth=".length));
this.gatewayCookie = cookie;
return (parsed as { id: string }).id;
}
/**
* `POST /gateway/organizations` — create an organization with its first
* workspace. The caller becomes its organization admin and the workspace's
* admin, and the server re-mints their session into the workspace, so from
* here on this client acts there.
*/
async createOrganization(name: string): Promise<{
organization: OrganizationSummary;
workspace: WorkspaceMembership;
}> {
const { parsed, response } = await this.rawRequest(
"POST",
"/gateway/organizations",
{
cookie: await this.gatewayLogin(),
body: { name },
},
);
const cookie = sessionCookieFrom(response);
if (!cookie)
throw new Error(
"Creating an organization returned no switch_auth cookie for its workspace.",
);
this.issued.record(cookie.slice("switch_auth=".length));
this.gatewayCookie = cookie;
return parsed as {
organization: OrganizationSummary;
workspace: WorkspaceMembership;
};
}
/** `GET /gateway/organizations/current/audit-events` — the organization's audit log, newest first; organization admin only. */
async organizationAuditEvents(): Promise<
{
action: string;
actor_user_id: string | null;
target_id: string | null;
details: Record<string, unknown> | null;
}[]
> {
return this.gateway("GET", "/organizations/current/audit-events");
}
/** `GET /gateway/organizations/current/issues` — what the organization's admins have left to fix; organization admin only. */
async organizationIssues(): Promise<
{ kind: string; workspace_id: string | null; workspace_name: string | null; agents: string[] }[]
> {
return this.gateway("GET", "/organizations/current/issues");
}
/** `GET /gateway/organizations/current` — the current workspace's organization and the caller's role there. */
async currentOrganization(): Promise<{
id: string;
name: string;
role: string | null;
}> {
return this.gateway("GET", "/organizations/current");
}
/** `GET /gateway/organizations` — the caller's organizations and their role in each. */
async organizations(): Promise<OrganizationSummary[]> {
return this.gateway<OrganizationSummary[]>("GET", "/organizations");
}
/** `GET /gateway/tenants/counts` — how many users and agents each workspace the caller may enter has. */
async workspaceCounts(): Promise<{ id: string; users: number; agents: number }[]> {
return this.gateway("GET", "/tenants/counts");
}
/** `GET /gateway/organizations/current/workspaces` — the current organization's workspaces the caller may enter. */
async organizationWorkspaces(): Promise<WorkspaceMembership[]> {
return this.gateway<WorkspaceMembership[]>(
"GET",
"/organizations/current/workspaces",
);
}
/** `POST /gateway/organizations/current/workspaces` — add a workspace to the current organization; the session stays put. */
async createOrganizationWorkspace(name: string): Promise<WorkspaceMembership> {
return this.gateway<WorkspaceMembership>(
"POST",
"/organizations/current/workspaces",
{ name },
);
}
/** `POST /gateway/agents/register` — an agent owned by the signed-in user, in their current workspace. */
async registerAgentAsUser(params: {
name: string;
description: string;
}): Promise<RegisteredAgent> {
const body = await this.gateway<{ id: string; api_key: string }>(
"POST",
"/agents/register",
{
agent_type: "opencode",
name: params.name,
description: params.description,
options: { auto_session: false },
},
);
this.issued.record(body.api_key);
return { id: body.id, name: params.name, apiKey: body.api_key };
}
/** `GET /gateway/feature-flags` — the flags this deployment has turned on. */
async enabledFeatureFlags(): Promise<Set<string>> {
const body = await this.gateway<{
flags: { key: string; enabled: boolean }[];
}>("GET", "/feature-flags");
return new Set(
body.flags.filter((flag) => flag.enabled).map((flag) => flag.key),
);
}
/**
* `GET /health/ready`: whether the server reports itself ready to serve. It
* answers 503 with the failing checks when it is not, which this throws as a
* {@link SwitchHttpError} carrying them.
*/
async ready(): Promise<void> {
await this.request("GET", "/health/ready", { timeoutMs: 10_000 });
}
/** `GET /health` — the reachability probe the suite skips on. */
async health(): Promise<void> {
const body = await this.request<{ status?: string }>("GET", "/health", {
timeoutMs: 5_000,
});
if (body?.status !== "ok") {
throw new Error(`Switch /health returned ${JSON.stringify(body)}`);
}
}
// ── gateway (admin) ───────────────────────────────────────────────────────
/**
* `POST /gateway/auth/login` with `{email, password}`.
*
* The gateway is **cookie-authenticated, not bearer-authenticated**: the
* response body is the session user, and the credential is a `switch_auth`
* cookie in `Set-Cookie`. Node's `fetch` has no cookie jar, so the cookie is
* extracted here and replayed as a `Cookie` header on every gateway call.
* Cached for the life of the client.
*/
async gatewayLogin(): Promise<string> {
if (this.gatewayCookie) return this.gatewayCookie;
const { response } = await this.rawRequest("POST", "/gateway/auth/login", {
body: { email: this.adminEmail, password: this.adminPassword },
});
const cookie = sessionCookieFrom(response);
if (!cookie) {
throw new Error(
"Gateway login succeeded but returned no switch_auth cookie — the gateway " +
"authenticates with a session cookie, not a bearer token.",
);
}
this.issued.record(cookie.slice("switch_auth=".length));
this.gatewayCookie = cookie;
return cookie;
}
private async gateway<T>(
method: string,
path: string,
body?: unknown,
): Promise<T> {
return this.request<T>(method, `/gateway${path}`, {
cookie: await this.gatewayLogin(),
body,
});
}
async listRooms(): Promise<RoomSummary[]> {
const rows = await this.gateway<RawRoom[]>("GET", "/rooms");
return rows.map(toRoomSummary);
}
async getRoom(roomId: string): Promise<RoomDetail> {
return toRoomDetail(await this.gateway<RawRoom>("GET", `/rooms/${roomId}`));
}
/**
* `POST /gateway/rooms` — create a Switch room and let the bridge provision
* the platform channel for it.
*
* This is the harness's room-creation path, and the choice is not arbitrary.
* The "add the agent's bot to a channel" route relies on some *other* agent's
* websocket witnessing the join (`_handle_user_added` in the Mattermost
* adapter), so adding the FIRST bot to a brand-new channel is witnessed by
* nobody and no room is ever created — verified against a live server, see
* README.md. Creating the room here makes Switch create the channel and add
* the bot itself, which is deterministic.
*
* `userNames` are platform usernames added to the channel — the harness adds
* itself, since it has to be a channel member to post as the human.
*
* `bridgeId: null` makes an internal-only room: no platform channel, so the
* only participants are agents and the fast lane needs no bridge at all.
*/
async createRoom(params: {
name: string;
description: string;
bridgeId: string | null;
agentNames: string[];
userNames: string[];
}): Promise<RoomDetail> {
const row = await this.gateway<RawRoom>("POST", "/rooms", {
name: params.name,
description: params.description,
...(params.bridgeId === null
? { internal_only: true }
: {
bridge_id: params.bridgeId,
internal_only: false,
channel_type: "channel_public",
}),
agent_names: params.agentNames,
user_names: params.userNames,
});
return toRoomDetail(row);
}
// ── decision routing (auto-route) ────────────────────────────────────────
/** `GET /gateway/decision-settings`: the signed-in workspace's decision settings. */
async decisionSettings(): Promise<Record<string, unknown>> {
return this.gateway("GET", "/decision-settings");
}
/** `PUT /gateway/decision-settings`: save the workspace's decision backend. */
async saveDecisionSettings(
body: Record<string, unknown>,
): Promise<Record<string, unknown>> {
return this.gateway("PUT", "/decision-settings", body);
}
/** `DELETE /gateway/decision-settings`: back to the server default. */
async resetDecisionSettings(): Promise<void> {
await this.gateway("DELETE", "/decision-settings");
}
/** `POST /gateway/decision-settings/test`: one sample decision, nothing saved. */
async testDecisionSettings(
body: Record<string, unknown>,
): Promise<Record<string, unknown>> {
return this.gateway("POST", "/decision-settings/test", body);
}
/** `PUT /gateway/rooms/{room_id}/auto-route`: the room's auto-route switch. */
async setRoomAutoRoute(
roomId: string,
body: { on?: boolean; fallback_agent?: string | null },
): Promise<Record<string, unknown>> {
return this.gateway("PUT", `/rooms/${roomId}/auto-route`, body);
}
async deleteRoom(roomId: string): Promise<void> {
await this.gateway("DELETE", `/rooms/${roomId}`);
}
/** `DELETE /gateway/room-groups/{id}` — a group's rooms and subgroups move up a level, so delete those first. */
async deleteRoomGroup(groupId: string): Promise<void> {
await this.gateway("DELETE", `/room-groups/${groupId}`);
}
/** `POST /gateway/packages` — a private package owned by the signed-in admin, with nothing in it. */
async createPackage(params: {
name: string;
description: string;
instructions: string;
}): Promise<{ id: string; name: string }> {
return this.gateway<{ id: string; name: string }>("POST", "/packages", params);
}
async deletePackage(packageId: string): Promise<void> {
await this.gateway("DELETE", `/packages/${packageId}`);
}
/** `GET /gateway/rooms/{id}/packages` — the packages attached to a room. */
async roomPackages(roomId: string): Promise<{ id: string; name: string }[]> {
return this.gateway<{ id: string; name: string }[]>(
"GET",
`/rooms/${roomId}/packages`,
);
}
/**
* `GET /gateway/rooms/{id}/yaml` — the room captured as the document
* `/rooms/from-yaml` takes, so the room can be built again from it.
*/
async exportRoomYaml(roomId: string): Promise<string> {
assertAllowed(this.environment, "GET", `/gateway/rooms/${roomId}/yaml`);
const response = await fetch(`${this.apiUrl}/gateway/rooms/${roomId}/yaml`, {
headers: {
Accept: "application/x-yaml",
Cookie: await this.gatewayLogin(),
...this.requestId(),
},
redirect: "manual",
signal: AbortSignal.timeout(30_000),
});
const text = await response.text();
if (!response.ok) {
throw new SwitchHttpError("GET", `/gateway/rooms/${roomId}/yaml`, response.status, text);
}
return text;
}
/**
* `DELETE /gateway/agents/by-name/{name}` — admin-authenticated teardown that,
* unlike `DELETE /agents/{id}`, does not need the agent's own API key. Used by
* the cleanup script for agents left behind by an interrupted run.
*/
async deleteAgentByName(name: string): Promise<void> {
await this.gateway("DELETE", `/agents/by-name/${encodeURIComponent(name)}`);
}
/**
* `POST /gateway/management/agents` — register an agent owned by the signed-in
* admin and place it on a controller, which then runs its sessions. The
* server checks the placement before registering anything, so a refusal
* leaves nothing behind and the call can simply be repeated.
*
* Refused with 409 until the controller has connected and reported the
* provider installed and signed in; see {@link managementErrorCode}.
*/
async createManagedAgent(params: {
name: string;
description: string;
controllerId: string;
definition: ManagedAgentDefinition;
}): Promise<AgentRef> {
const view = await this.gateway<{ agent_id: string; name: string }>(
"POST",
"/management/agents",
{
name: params.name,
description: params.description,
controller_id: params.controllerId,
desired_state: "running",
definition: params.definition,
},
);
return { id: view.agent_id, name: view.name };
}
/**
* `PUT /gateway/agents/{id}/addressing-policy` with `{policy: null}` — clear
* the agent's scoped addressing policy, so anyone may address it.
*
* Agents are created owner-only: only their owner, or agents and identities
* the owner has claimed, may address them, and anything else is answered with
* a refusal instead of delivered. The harness's senders are other throwaway
* agents and an unclaimed platform user, so its agents are opened explicitly.
*/
async openAddressing(agentId: string): Promise<void> {
await this.setAddressingPolicy(agentId, null);
}
/** `PUT /gateway/agents/{id}/addressing-policy` — who may address the agent; null lets anyone. */
async setAddressingPolicy(
agentId: string,
policy: AddressingPolicy | null,
): Promise<void> {
await this.gateway("PUT", `/agents/${agentId}/addressing-policy`, {
policy,
});
}
/**
* `POST /gateway/rooms/from-template-document` — run a template as the
* signed-in admin: create its agents, wait for each to listen, then build
* its room. A refusal creates nothing and throws a {@link TemplateRefusal}
* naming every problem.
*/
async runTemplateDocument(params: {
template: string;
templateName: string;
}): Promise<TemplateRun> {
try {
return await this.gateway<TemplateRun>(
"POST",
"/rooms/from-template-document",
{ template: params.template, template_name: params.templateName },
);
} catch (error) {
if (error instanceof SwitchHttpError && error.status === 409) {
const body = JSON.parse(error.body) as {
code?: string;
problems?: { slot: string; code: string; message: string }[];
};
if (body.code === "agents_not_created") {
throw new TemplateRefusal(error, body.problems ?? []);
}
}
throw error;
}
}
/**
* The status Switch reports for one agent in one room. `live` means a session
* is attending the room; `dormant` means an auto-session connector is watching
* and would spawn one; `no_session` / `disconnected` mean nothing is there.
*/
async agentStatusInRoom(
roomId: string,
agentId: string,
): Promise<string | null> {
const row = await this.gateway<RawRoom>("GET", `/rooms/${roomId}`);
const statuses = row.agent_statuses;
if (!statuses || typeof statuses !== "object") return null;
const status = (statuses as Record<string, unknown>)[agentId];
return typeof status === "string" ? status : null;
}
/**
* `PUT /gateway/agents/{id}/name` — rename an agent and set its display name
* in the same step. Returns the name the server now holds.
*/
async renameAgent(
agentId: string,
name: string,
displayName: string | null,
): Promise<{
name: string;
displayName: string | null;
bridgeFailures: string[];
}> {
const body = await this.gateway<{
agent: { name: string; display_name: string | null };
bridge_failures: string[];
}>("PUT", `/agents/${agentId}/name`, { name, display_name: displayName });
return {
name: body.agent.name,
displayName: body.agent.display_name,
bridgeFailures: body.bridge_failures,
};
}
/**
* `POST /gateway/collaborations/{bridge}/identities` on the default bridge
* of `bridgeType` — start linking a chat account to the signed-in Switch
* user, so Switch can recognise that person in a room (what the rename and
* delete chat commands check).
*
* The link counts only once the account posts the returned code
* (`!link-account CODE`); `code` is null when the account had already
* confirmed it.
*/
async claimIdentity(
bridgeType: string,
externalUserId: string,
username: string,
): Promise<{ bridgeId: string; identityId: string; code: string | null }> {
const bridges = await this.gateway<
{ bridge_id: string; bridge_type: string; is_default?: boolean }[]
>("GET", "/collaborations");
const ofType = bridges.filter((row) => row.bridge_type === bridgeType);
const bridge = ofType.find((row) => row.is_default) ?? ofType[0];
if (!bridge)
throw new Error(
`No ${bridgeType} collaboration bridge on this Switch server`,
);
const body = await this.gateway<{
id: string;
link_request: { code: { code: string } | null } | null;
}>("POST", `/collaborations/${bridge.bridge_id}/identities`, {
external_user_id: externalUserId,
username,
user_id: null,
expects_confirmation: true,
});
if (body.link_request && !body.link_request.code)
throw new Error("A link for yourself came back without a code");
return {
bridgeId: bridge.bridge_id,
identityId: body.id,
code: body.link_request?.code?.code ?? null,
};
}
/**
* `DELETE /gateway/collaborations/{bridge}/identities/{identity}` — unlink
* the signed-in user from a chat account, or cancel a link still waiting
* for its code.
*/
async releaseIdentity(bridgeId: string, identityId: string): Promise<void> {
await this.gateway(
"DELETE",
`/collaborations/${bridgeId}/identities/${identityId}`,
);
}
/**
* `DELETE /gateway/collaborations/{bridge}/identities/{identity}/request` —
* stop waiting for a chat account to confirm the signed-in user's link,
* leaving any link it already has.
*/
async cancelLinkRequest(bridgeId: string, identityId: string): Promise<void> {
await this.gateway(
"DELETE",
`/collaborations/${bridgeId}/identities/${identityId}/request`,
);
}
/**
* `GET /gateway/collaborations/{bridge}/identities/unconfirmed` — the
* links on a bridge made before links needed confirming, by identity id.
* Admin only.
*/
async unconfirmedLinkIds(bridgeId: string): Promise<string[]> {
const rows = await this.gateway<{ id: string }[]>(
"GET",
`/collaborations/${bridgeId}/identities/unconfirmed`,
);
return rows.map((row) => row.id);
}
/**
* `GET /gateway/auth/me/identities/pending` — the chat accounts waiting to
* confirm a link to the signed-in user, by identity id.
*/
async pendingIdentityIds(): Promise<string[]> {
const rows = await this.gateway<{ id: string }[]>(
"GET",
"/auth/me/identities/pending",
);
return rows.map((row) => row.id);
}
/**
* `POST /gateway/collaborations/{bridge}/identities/{identity}/code` — a
* fresh code for the signed-in user's waiting link, replacing the last.
*/
async issueLinkCode(bridgeId: string, identityId: string): Promise<string> {
const body = await this.gateway<{ code: string }>(
"POST",
`/collaborations/${bridgeId}/identities/${identityId}/code`,
);
return body.code;
}
async listAgents(): Promise<AgentSummary[]> {
const rows = await this.gateway<
{ id: string; name: string; created_at: string }[]
>("GET", "/agents");
return rows.map((row) => ({
id: row.id,
name: row.name,
createdAt: row.created_at,
}));
}
/** `GET /gateway/organizations/current/members` — the organization of the bound workspace, `org_admin` only. */
async organizationMembers(): Promise<{ user_id: string; role: string }[]> {
return this.gateway<{ user_id: string; role: string }[]>(
"GET",
"/organizations/current/members",
);
}
/** `PATCH /gateway/organizations/current/members/{user_id}` — grant or take back `org_admin`. */
async setOrganizationRole(
userId: string,
role: "org_admin" | "member",
): Promise<{ user_id: string; role: string }> {
return this.gateway<{ user_id: string; role: string }>(
"PATCH",
`/organizations/current/members/${encodeURIComponent(userId)}`,
{ role },
);
}
/** `DELETE /gateway/organizations/current/members/{user_id}` — remove someone from the organization. */
async removeOrganizationMember(userId: string): Promise<void> {
await this.gateway<unknown>(
"DELETE",
`/organizations/current/members/${encodeURIComponent(userId)}`,
);
}
/** `GET /gateway/tenants/{tenant_id}/members` — the workspace roster, with each person's organization role. */
async workspaceMembers(tenantId: string): Promise<
{
user_id: string;
role: string;
organization_role: string | null;
via_organization: boolean;
}[]
> {
return this.gateway("GET", `/tenants/${encodeURIComponent(tenantId)}/members`);
}
/** `DELETE /gateway/tenants/{tenant_id}/members/{user_id}` — remove someone from a workspace. */
async removeWorkspaceMember(tenantId: string, userId: string): Promise<void> {
await this.gateway<unknown>(
"DELETE",
`/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}`,
);
}
/**
* `DELETE /gateway/tenants/{tenant_id}` — delete the bound workspace, once it
* is empty, by typing its name. Its own admins only. The server re-mints the
* session onto the caller's only other workspace, if there is exactly one,
* so from here on this client acts there.
*/
async deleteTenant(tenantId: string, name: string): Promise<void> {
const { response } = await this.rawRequest(
"DELETE",
`/gateway/tenants/${encodeURIComponent(tenantId)}`,
{ cookie: await this.gatewayLogin(), body: { name } },
);
const cookie = sessionCookieFrom(response);
if (cookie) {
this.issued.record(cookie.slice("switch_auth=".length));
this.gatewayCookie = cookie;
}
}
/** `POST /gateway/ownership/transfer` — make another member of this workspace the owner of something. */
async transferOwnership(params: {
kind: "agent" | "room" | "package" | "reference" | "reference_type" | "document" | "template";
id: string;
newOwnerId: string;
}): Promise<{ kind: string; id: string; owner_id: string; agent_key_reissued: boolean }> {
return this.gateway("POST", "/ownership/transfer", {
kind: params.kind,
id: params.id,
new_owner_id: params.newOwnerId,
});
}
/** `DELETE /gateway/users/{user_id}` — the deployment operator deletes someone's whole account. */
async deleteUser(userId: string): Promise<void> {
await this.gateway<unknown>("DELETE", `/users/${encodeURIComponent(userId)}`);
}
/**
* `POST /gateway/auth/sessions/revoke` — sign this account out of every
* device, this client included: its cookie stops working too.
*/
async endMySessions(): Promise<void> {
await this.gateway<unknown>("POST", "/auth/sessions/revoke");
}
/** `POST /gateway/users/{user_id}/sessions/revoke` — the deployment operator signs someone out of every device. */
async endUserSessions(userId: string): Promise<void> {
await this.gateway<unknown>(
"POST",
`/users/${encodeURIComponent(userId)}/sessions/revoke`,
);
}
/** `GET /gateway/tenants/{tenant_id}/retention` — how long the workspace keeps messages; null days is forever. */
async retentionPolicy(tenantId: string): Promise<RetentionPolicy> {
return this.gateway("GET", `/tenants/${encodeURIComponent(tenantId)}/retention`);
}
/** `GET /gateway/tenants/{tenant_id}/retention/preview` — how many messages a window of `days` would delete now. */
async previewRetention(
tenantId: string,
days: number,
): Promise<{ message_retention_days: number; messages_to_delete: number }> {
return this.gateway(
"GET",
`/tenants/${encodeURIComponent(tenantId)}/retention/preview?days=${days}`,
);
}
/** `PUT /gateway/tenants/{tenant_id}/retention` — delete messages once they are older than `days`. */
async setRetention(tenantId: string, days: number): Promise<RetentionPolicy> {
return this.gateway("PUT", `/tenants/${encodeURIComponent(tenantId)}/retention`, {
message_retention_days: days,
});
}
/** `DELETE /gateway/tenants/{tenant_id}/retention` — keep messages forever again. */
async clearRetention(tenantId: string): Promise<RetentionPolicy> {
return this.gateway("DELETE", `/tenants/${encodeURIComponent(tenantId)}/retention`);
}
/** `GET /gateway/tenants/{tenant_id}/people` — everyone seen in the workspace's rooms, the list a person is erased from. */
async people(tenantId: string): Promise<Person[]> {
return this.gateway("GET", `/tenants/${encodeURIComponent(tenantId)}/people`);
}
/** `POST /gateway/tenants/{tenant_id}/erasures` — queue erasing what the named people sent. */
async requestErasure(
tenantId: string,
params: { memberClientIds: string[] },
): Promise<Erasure> {
return this.gateway("POST", `/tenants/${encodeURIComponent(tenantId)}/erasures`, {
member_client_ids: params.memberClientIds,
});
}
/** `GET /gateway/tenants/{tenant_id}/erasures` — the workspace's erasure requests, newest first. */
async erasures(tenantId: string): Promise<Erasure[]> {
return this.gateway("GET", `/tenants/${encodeURIComponent(tenantId)}/erasures`);
}
/** `POST /gateway/chats` — a direct chat between the signed-in person and one agent. Returns its room id. */
async createDirectChat(agentId: string): Promise<string> {
const envelope = await this.gateway<{ chat: { roomId: string } }>("POST", "/chats", {
agentId,
requestId: crypto.randomUUID(),
});
return envelope.chat.roomId;
}
/** `POST /gateway/chats/{room_id}/messages` — post into a chat as the signed-in person. */
async sendChatMessage(roomId: string, body: string): Promise<void> {
await this.gateway<unknown>("POST", `/chats/${encodeURIComponent(roomId)}/messages`, {
requestId: crypto.randomUUID(),
body,
});
}
/** `GET /gateway/operator/workspaces` — every workspace on the server, platform operator only. */
async operatorWorkspaces(): Promise<{ id: string; name: string }[]> {
return this.gateway<{ id: string; name: string }[]>("GET", "/operator/workspaces");
}
/** `GET /gateway/auth/session` — the workspace this admin session is bound to. */
async tenantId(): Promise<string> {
const state = await this.gateway<{
state: string;
tenant: { id: string } | null;
}>("GET", "/auth/session");
if (state.tenant === null) {
throw new Error(
`The gateway admin's session is bound to no workspace (state '${state.state}').`,
);
}
return state.tenant.id;
}
/**
* `GET /gateway/tenants/{tenant_id}/usage` — what each client spent, per
* metric and model, over `[since, until)`. Counted in whole UTC hours.
*/
async usage(
tenantId: string,
since: Date,
until: Date,
): Promise<UsageTotal[]> {
const query = `since=${encodeURIComponent(since.toISOString())}&until=${encodeURIComponent(until.toISOString())}`;
const rows = await this.gateway<
{
metric: string;
client_id: string;
client_name: string | null;
model: string;
amount: number;
}[]
>("GET", `/tenants/${tenantId}/usage?${query}`);
return rows.map((row) => ({
metric: row.metric,
clientId: row.client_id,
clientName: row.client_name,
model: row.model,
amount: row.amount,
}));
}
/** The bridge id of the default collaboration bridge of `type`. */
async defaultBridgeId(type: string): Promise<string> {
return (await this.defaultBridge(type)).id;
}
/** The default collaboration bridge of `type`: its id, and the display name a room document names it by. */
async defaultBridge(
type: string,
): Promise<{ id: string; displayName: string }> {
const rows = await this.gateway<
{
id: string;
bridge_type: string;
display_name: string;
is_default?: boolean;
}[]
>("GET", "/collaborations");
const ofType = rows.filter((row) => row.bridge_type === type);
if (ofType.length === 0) {
throw new Error(
`No ${type} collaboration bridge registered on this Switch server`,
);
}
const row = ofType.find((candidate) => candidate.is_default) ?? ofType[0]!;
return { id: row.id, displayName: row.display_name };
}
/**
* `POST /gateway/rooms/from-yaml` — provision one room from a room document,
* as the signed-in admin; the gateway's side of `create_room_from_yaml`.
* Anything the room was given that could not be attached is a failure, not a
* room that is quietly missing part of its setup.
*/
async createRoomFromYaml(yaml: string): Promise<RoomDetail> {
const result = await this.gateway<{
room_id?: string;
failed_attachments?: unknown[];
}>("POST", "/rooms/from-yaml", { yaml });
if (result.room_id === undefined) {
throw new Error(
`from-yaml did not make one room: ${JSON.stringify(result)}`,
);
}
const roomId = result.room_id;
if (
result.failed_attachments !== undefined &&
result.failed_attachments.length > 0
) {
throw await this.withRoomDeleted(
roomId,
new Error(
`from-yaml made room ${roomId} without part of what it was given: ` +
JSON.stringify(result.failed_attachments),
),
);
}
try {
return await this.getRoom(roomId);
} catch (error) {
throw await this.withRoomDeleted(roomId, error);
}
}
/** Delete a room a call made before failing, and return the failure, saying whether the room went too. */
private async withRoomDeleted(
roomId: string,
failure: unknown,
): Promise<Error> {
const reason = failure instanceof Error ? failure.message : String(failure);
try {
await this.deleteRoom(roomId);
return new Error(`${reason} (room ${roomId} was deleted)`, {
cause: failure,
});
} catch (cleanup) {
const why = cleanup instanceof Error ? cleanup.message : String(cleanup);
return new Error(
`${reason} (and room ${roomId} could not be deleted, delete it by hand: ${why})`,
{
cause: failure,
},
);
}
}
/**
* Find the Switch room bound to a given external (Mattermost) channel id.
* The room list does not carry `external_channel_id`, so each candidate room
* on the bridge is read in full — the set is small on a dev server, and the
* alternative (matching on display name) is ambiguous.
*/
async findRoomByExternalChannel(
bridgeId: string,
externalChannelId: string,
): Promise<RoomDetail | null> {
const rooms = await this.listRooms();
for (const room of rooms) {
if (room.bridgeId !== bridgeId || room.archived) continue;
const detail = await this.getRoom(room.id);
if (detail.externalChannelId === externalChannelId) return detail;
}
return null;
}
/** Poll {@link findRoomByExternalChannel} until the bridge has created the room. */
async waitForRoomByExternalChannel(
bridgeId: string,
externalChannelId: string,
deadlineMs: number,
): Promise<RoomDetail> {
const until = Date.now() + deadlineMs;
let last: RoomDetail | null = null;
while (Date.now() < until) {
last = await this.findRoomByExternalChannel(bridgeId, externalChannelId);
if (last) return last;
await sleep(2_000);
}
throw new Error(
`No Switch room appeared for Mattermost channel ${externalChannelId} within ${deadlineMs}ms. ` +
`Is the Mattermost bridge running and is the agent's bot a member of the channel?`,
);
}
// ── agent bridge: registration ────────────────────────────────────────────
/**
* Register a "known agent" (`POST /agents/register-known`, registration-token
* auth). `agentType` is one of the gateway's known types — `claude-code`,
* `codex`, `opencode`, `cursor` or `antigravity` — and `options` is that
* type's option schema, which for OpenCode is `{ auto_session, repo_dir }`.
*
* Registration is also what mints the agent's Mattermost bot account: the
* protocol service calls `create_agent_identity` on every collaboration
* bridge, and the Mattermost adapter creates a bot whose **username is the
* agent name verbatim**. So the agent must be registered before its bot can
* be added to a channel.
*/
async registerKnownAgent(params: {
agentType: "opencode" | "codex" | "claude-code" | "antigravity" | "cursor";
name: string;
description: string;
options?: Record<string, unknown>;
}): Promise<RegisteredAgent> {
const body = await this.request<{ id: string; api_key: string }>(
"POST",
"/agents/register-known",
{
token: this.registrationToken,
body: {
agent_type: params.agentType,
name: params.name,
description: params.description,
options: params.options ?? {},
},
},
);
this.issued.record(body.api_key);
return { id: body.id, name: params.name, apiKey: body.api_key };
}
/**
* `DELETE /agents/{id}` authenticated as the agent itself — the registration
* token is not accepted here, the handler compares the token's agent against
* the path id.
*/
async deleteAgent(agent: RegisteredAgent): Promise<void> {
await this.request("DELETE", `/agents/${agent.id}`, {
token: agent.apiKey,
});
}
// ── agent bridge: acting as an agent ──────────────────────────────────────
/**
* Long-poll `GET /agents/{id}/notifications?timeout=` as the agent. Returns
* only *notifiable* events (addressed messages and listened-for
* joins) and never drains the per-room queues a live session polls, so the
* harness can watch the same stream Switch Console's auto-session watcher
* watches without stealing a running session's events.
*
* Returns `[]` on the server's 204 (nothing within the timeout).
*/
async pollNotifications(
agent: RegisteredAgent,
timeoutSeconds = 10,
): Promise<AgentEvent[]> {
const body = await this.request<{ events?: AgentEvent[] } | undefined>(
"GET",
`/agents/${agent.id}/notifications?timeout=${timeoutSeconds}`,
{ token: agent.apiKey, timeoutMs: (timeoutSeconds + 15) * 1000 },
);
return body?.events ?? [];
}
/** As {@link pollNotifications}, but for one room's live event queue. */
async pollRoomEvents(
agent: RegisteredAgent,
roomId: string,
timeoutSeconds = 10,
): Promise<AgentEvent[]> {
const body = await this.request<{ events?: AgentEvent[] } | undefined>(
"GET",
`/agents/${agent.id}/rooms/${roomId}/events?timeout=${timeoutSeconds}`,
{ token: agent.apiKey, timeoutMs: (timeoutSeconds + 15) * 1000 },
);
return body?.events ?? [];
}
/**
* Wait for a notification satisfying `predicate`, collecting everything seen
* along the way. Returns `{ match: null, seen }` on timeout rather than
* throwing, so a caller can report the stream it did see.
*/
async waitForNotification(
agent: RegisteredAgent,
predicate: (event: AgentEvent) => boolean,
deadlineMs: number,
): Promise<{ match: AgentEvent | null; seen: AgentEvent[] }> {
const until = Date.now() + deadlineMs;
const seen: AgentEvent[] = [];
while (Date.now() < until) {
const remaining = Math.max(
1,
Math.min(10, Math.ceil((until - Date.now()) / 1000)),
);
const events = await this.pollNotifications(agent, remaining);
for (const event of events) {
seen.push(event);
if (predicate(event)) return { match: event, seen };
}
}
return { match: null, seen };
}
/**
* `GET /agents/{id}/rooms/{room_id}/history?limit=` as the agent — the room's
* recent messages, addressed or not. Unlike the notification stream this shows
* ordinary channel chatter, which is what makes it usable as a bridge-liveness
* probe that does not wake the agent.
*/
async roomHistory(
agent: RegisteredAgent,
roomId: string,
limit = 20,
): Promise<
{
sender: string;
sender_name: string;
body: string;
timestamp: number | null;
}[]
> {
const body = await this.request<{
events: {
sender: string;
sender_name: string;
body: string;
timestamp: number | null;
}[];
}>("GET", `/agents/${agent.id}/rooms/${roomId}/history?limit=${limit}`, {
token: agent.apiKey,
});
return body.events;
}
/**
* `POST /agents/{id}/message` with `{room_id, content}` — post into a room as
* the agent. The bridge relays it to Mattermost as the agent's bot. Returns
* the Matrix event id.
*/
async sendMessage(
agent: RegisteredAgent,
roomId: string,
content: string,
): Promise<string> {
const body = await this.request<{ ok: boolean; event_id: string }>(
"POST",
`/agents/${agent.id}/message`,
{ token: agent.apiKey, body: { room_id: roomId, content } },
);
return body.event_id;
}
/**
* `POST /agents/{id}/rooms/{room_id}/media` — post one file to a room as the
* agent (multipart, part `file`). Returns the media URI it was stored under.
*/
async uploadMedia(
agent: RegisteredAgent,
roomId: string,
file: { name: string; bytes: Uint8Array<ArrayBuffer>; contentType: string },
): Promise<{ eventId: string; mxc: string }> {
const path = `/agents/${agent.id}/rooms/${roomId}/media`;
assertAllowed(this.environment, "POST", path);
const form = new FormData();
form.append(
"file",
new Blob([file.bytes], { type: file.contentType }),
file.name,
);
const response = await fetch(`${this.apiUrl}${path}`, {
method: "POST",
headers: {
Accept: "application/json",
Authorization: `Bearer ${agent.apiKey}`,
...this.requestId(),
},
body: form,
redirect: "manual",
signal: AbortSignal.timeout(30_000),
});
const text = await response.text();
if (!response.ok) throw new SwitchHttpError("POST", path, response.status, text);
const body = JSON.parse(text) as { event_id: string; mxc: string };
return { eventId: body.event_id, mxc: body.mxc };
}
/**
* `GET /agents/{id}/rooms/{room_id}/media?mxc=` — an attachment's bytes, and
* the headers that name it, as the agent's session host downloads it.
*/
async downloadMedia(
agent: RegisteredAgent,
roomId: string,
mxc: string,
): Promise<{ bytes: Uint8Array; contentType: string; contentDisposition: string }> {
const path = `/agents/${agent.id}/rooms/${roomId}/media?mxc=${encodeURIComponent(mxc)}`;
assertAllowed(this.environment, "GET", path);
const response = await fetch(`${this.apiUrl}${path}`, {
headers: { Authorization: `Bearer ${agent.apiKey}`, ...this.requestId() },
redirect: "manual",
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
throw new SwitchHttpError("GET", path, response.status, await response.text());
}
return {
bytes: new Uint8Array(await response.arrayBuffer()),
contentType: response.headers.get("content-type") ?? "",
contentDisposition: response.headers.get("content-disposition") ?? "",
};
}
/**
* Any agent-bridge request as the agent, answered with its status and body
* whatever the status: for the checks that a client's mistake is answered
* with a 4xx that says what was wrong.
*/
async agentAttempt(
agent: RegisteredAgent,
method: "GET" | "POST",
path: string,
body: unknown,
): Promise<{ status: number; detail: string }> {
try {
await this.request(method, path, { token: agent.apiKey, body: body ?? undefined });
return { status: 200, detail: "" };
} catch (error) {
if (!(error instanceof SwitchHttpError)) throw error;
return { status: error.status, detail: errorDetail(error.body) };
}
}
// ── agent bridge: the operations front door ───────────────────────────────
/**
* `GET /agents/{id}/ops` — every operation the registry defines, with its
* parameters, keyed by name. The same registry serves the MCP server, so what this lists is
* what an agent's session sees as tools.
*/
async listOperations(agent: RegisteredAgent): Promise<string[]> {
const body = await this.request<{ operations: Record<string, unknown> }>(
"GET",
`/agents/${agent.id}/ops`,
{ token: agent.apiKey },
);
return Object.keys(body.operations);
}
/**
* `POST /agents/{id}/ops/{operation}` — run one registry operation as the
* agent, with `args` as its arguments, and return its `result`. Operations that act on "the room you
* are connected to" need a live connection and fail without one; the fast
* lane calls those that take the room as an argument.
*/
async callOperation<T>(
agent: RegisteredAgent,
operation: string,
args: Record<string, unknown>,
): Promise<T> {
const body = await this.request<{ result: T }>(
"POST",
`/agents/${agent.id}/ops/${operation}`,
{
token: agent.apiKey,
body: args,
},
);
return body.result;
}
/**
* `POST /agents/{id}/watch/heartbeat` — the room-agnostic "an operator
* connector is watching this agent" beat. Switch Console pings it while its
* auto-session watcher is running; it is what makes the agent report DORMANT
* rather than DISCONNECTED in rooms with no live session.
*/
async watchHeartbeat(agent: RegisteredAgent): Promise<void> {
await this.request("POST", `/agents/${agent.id}/watch/heartbeat`, {
token: agent.apiKey,
body: {},
});
}
}
interface RawRoom {
id: string;
name: string;
created_at: string;
bridge_id?: string | null;
bridge_type?: string | null;
archived?: boolean;
external_channel_id?: string | null;
matrix_room_id?: string | null;
agent_ids?: string[];
agent_statuses?: Record<string, unknown>;
}
function toRoomDetail(row: RawRoom): RoomDetail {
return {
...toRoomSummary(row),
externalChannelId: row.external_channel_id ?? null,
matrixRoomId: row.matrix_room_id ?? null,
agentIds: row.agent_ids ?? [],
};
}
function toRoomSummary(row: RawRoom): RoomSummary {
return {
id: row.id,
name: row.name,
createdAt: row.created_at,
bridgeId: row.bridge_id ?? null,
bridgeType: row.bridge_type ?? null,
archived: row.archived ?? false,
};
}
/**
* The `switch_auth=…` pair out of a response's `Set-Cookie` headers, ready to be
* sent back as a `Cookie` header. Node exposes multiple `Set-Cookie` headers via
* `getSetCookie()`; the single-header fallback covers older runtimes.
*/
export function sessionCookieFrom(response: Response): string | null {
const raw =
typeof response.headers.getSetCookie === "function"
? response.headers.getSetCookie()
: [response.headers.get("set-cookie") ?? ""];
for (const header of raw) {
const pair = header.split(";", 1)[0]?.trim();
if (pair?.startsWith("switch_auth=")) return pair;
}
return null;
}
export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}