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
Merge remote-tracking branch 'origin/main' into e2e-testing
Petr Bauch6c86a1915cd1
diff --cc CHANGELOG.mdindex 45cb66b85,9f901ea4d..735f41bc0--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -44,13 -44,80 +44,86 @@@ version of their own to them without al### [Unreleased]+ #### Added+ - **Templates carry packages.** A room in a template takes `packages:`, a list+ of packages that already exist, by `id` or by `name`, attached when the room+ is created. The person running the template must be able to attach each one+ by hand; a package that is missing, ambiguous or not theirs stops the run+ before the room exists. A template never creates or changes a package.+ Capturing a room (`GET /rooms/{id}/yaml`) now lists its packages by `id`,+ so a room built again from its capture gets them back (#910).++ #### Changed+ - **Following the conversation is described the same way everywhere, and the+ chart can turn it on.** The feature added in 0.31.0 is off unless+ `follow_the_conversation` is among the enabled feature flags+ (`FEATURE_FLAGS_ENABLED`, or `switchCore.featureFlags.enabled` in the Helm+ chart). The Switch skill and the agent runtime's instructions no longer tell+ agents that a message without their name can never reach them: a person's+ follow-up can, while other agents' chatter still does not. The chart lists+ the flag and, while it is on, sets `FOLLOW_THE_CONVERSATION_WINDOW_SECONDS`+ from `switchCore.followTheConversation.windowSeconds` (default 300).+ - **Agents name room groups by path.** `create_room` and `create_room_group`+ take a group as a path such as `Fraud/Incidents` (the top-level group, then+ each child), so two groups called `Incidents` under different parents no+ longer break every agent request that names one. A bare name still works+ when only one group has it; when several do, the error lists each match by+ its path so the agent can retry with the right one, and an unknown path+ names the first part that was not found. A group id is accepted too.+ - **Room group names are unique among siblings.** Creating, renaming or moving+ a group next to one with the same name (ignoring case) is refused with an+ error naming the existing group, from the dashboard, the API and agents+ alike. The same name under different parents is still fine. Deleting a+ group whose subgroup would move up next to a namesake is refused too, and+ the dashboard now shows why. Names can no longer contain `/` or be blank.+ Existing duplicates are left as they are and can be reached by id.+#### Fixed+- **Agents no longer read offline while their replica shuts down.** With several+ replicas, a stopping replica released its lease before its 5 s drain, so for+ up to about 6 s the other replicas counted its connected agents as gone: `@role`+ mentions did not reach the holder, rooms got false "offline" notices, and stop+ and reset commands were refused. It now drains first and closes its sockets+ as it releases.+ - **A request card posted in a thread now mentions the person who can answer+ it.** Approval and question cards go into the thread of the turn that raised+ them, and on Slack they used to mention nobody there, so an owner who was not+ in the thread was never told and the agent waited. A card in a thread now+ mentions the person who asked when the agent's addressing policy lets them+ answer, otherwise the agent's owner if they may answer, otherwise nobody.+ It never mentions more than one person, even when the policy lets anyone+ answer. Cards at the top of a channel mention whoever asked, as before.+ - **`!list-references` and `!list-documents` include what packages bring.**+ They listed only what was attached to the room directly, so a room whose+ references all came from a package answered "No references in this room."+ while its agents were sent them. Items from attached packages now follow+ the direct ones, each marked with the package it comes from (for example+ `(github, via Payments service context)`); an item attached both ways is+ listed once, as direct (#911).+ - **The template guide agents read now covers a room's `roles:`,+ `references:` and `docs:`.** All three already worked in a room resource+ and appear when a room is captured, but the guide stopped at `aliases:`, so+ an agent writing a template did not know they existed or what shape they+ take. It now gives each one's fields, a sentence on what it does, and a+ short example.+ - **The Teams command menu fits Teams' limit again.** Switch's own Teams app+ listed thirteen commands, one more than Teams allows, once `/remove-agent`+ joined it. Both Teams apps now offer the same twelve: `/remove-agent` is in,+ and `/room-url` leaves the menu but still works when typed. A self-hosted+ Teams app shows the change once its package is rebuilt with `--bump` and+ uploaded again.++ #### Removed+ - **`!run-cmd`, and the terminal command in offline replies.** A CLI started+ with that command got none of the Switch tools, so it never brought the agent+ online. The reply for an agent that is offline or not live now says what's+ wrong and who has to act, with no start command to paste. Where the owner+ starts it from Switch Console, the reply names the room to connect it to and+ the provider's sign-in command, for when Console says it is signed out. An+ always_on agent says its connector is down, whatever provider it registered+ through. Slack apps that list `/run-cmd` in their manifest keep showing it,+ answering "Unknown command", until an admin deletes it; Discord and Telegram+ drop it from their command lists by themselves (#730).### [0.31.0] - 2026-10-20diff --cc console/packages/plugins/src/switch-skill/SKILL.mdindex d75c7fe8c,a6de5b001..c447e79e7--- a/console/packages/plugins/src/switch-skill/SKILL.md+++ b/console/packages/plugins/src/switch-skill/SKILL.md@@@ -122,20 -121,16 +121,25 @@@ does, and there is no polling tool to c`BEGIN OPENING MESSAGE` / `END OPENING MESSAGE` markers. You did not writethem, but the person sees them as yours: do not repeat them.+ The first message you get from a room that has instructions of its own is+ preceded by them, between `BEGIN ROOM INSTRUCTIONS` / `END ROOM+ INSTRUCTIONS` markers (`[Switch] Room <room> has instructions of its+ own…`), and so is the next message after they change or are removed. They+ are the same instructions `connect_to_room` returns: follow them for+ everything you do in that room. If they could not be read, the line says so+ and asks you to call `connect_to_room` for that room before replying; do+ that rather than answering as if the room had none.+Where a server has "follow the conversation" switched on, a person's messagecan reach you without naming you: a reply in a thread where you spoke, or- were tagged, more recently than any other agent; their next message after- you have just answered them in the channel; or- any message in a room where you are the assigned agent. Treat it as meant+ were tagged, more recently than any other agent; their next channel message+ in an exchange with you that nobody else has interrupted, as long as every+ gap in it (their request to your answer, your answer to this message) is+ within the server's window, five minutes by default (after a break they+ need to mention you again); or any message in a room where you are the+ assigned agent. Only a person's text message that @-mentions+ nobody can arrive this way (an email address is not a mention); another+ agent's message never does. Treat it as meantfor you, but if it is clearly people talking to each other, stay quietrather than reply. People control this from the room: `!assign-agent @name`sends every message to one agent and `!unassign-agent` stops it;diff --cc console/tooling-e2e/src/clients/switch-client.tsindex e796d2b28,000000000..844eab85cmode 100644,000000..100644--- a/console/tooling-e2e/src/clients/switch-client.ts+++ b/console/tooling-e2e/src/clients/switch-client.ts@@@ -1,1049 -1,0 +1,1049 @@@+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_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;+ }+}++/**+ * 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;+ }+}++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 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> {+ 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,+ };+ }++ /**+ * 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 owner+ * 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/agents/register` — an agent owned by the signed-in user, in their current workspace. */+ async registerAgentAsUser(params: {+ name: string;+ description: string;+ }): Promise<AgentRef> {+ 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 };+ }++ /** `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);+ }++ async deleteRoom(roomId: string): Promise<void> {+ await this.gateway("DELETE", `/rooms/${roomId}`);+ }++ /**+ * `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.gateway("PUT", `/agents/${agentId}/addressing-policy`, {+ policy: null,+ });+ }++ /**+ * 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` — link 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).+ */+ async claimIdentity(+ bridgeType: string,+ externalUserId: string,+ username: string,+ ): Promise<void> {+ 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`,+ );+ await this.gateway(+ "POST",+ `/collaborations/${bridge.bridge_id}/identities`,+ {+ external_user_id: externalUserId,+ username,+ user_id: null,+ },+ );+ }++ 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/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 — `opencode`,- * `codex`, `claude-code` — and `options` is that type's option schema, which- * for OpenCode is `{ auto_session, repo_dir }`.++ * 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;+ }++ // ── 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));+}