Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

12.3 KB
Raw Blame
import type { Environment, MattermostEnv } from '../core/env.ts';
import { assertAllowed } from '../core/guard.ts';

/**
 * Mattermost REST client for the harness — the *human* half of the loop.
 *
 * Everything here runs as an ordinary user's personal access token, because that
 * is what the scenarios are simulating: a person typing in a channel. The one
 * privileged action is adding an agent's bot account to a channel, which the
 * token can do for a channel it owns.
 *
 * The bot for a Switch agent is created by the Mattermost collaboration adapter
 * at agent-registration time, with `username === agentName` verbatim
 * (`create_agent_identity` -> `POST /api/v4/bots {username: agent_name}`). That
 * naming rule is why {@link MattermostClient.findBotUser} is a plain username
 * lookup, and why agent names must satisfy Mattermost's username rules:
 * lowercase, `[a-z0-9._-]`, 3-22 characters.
 */

export interface MattermostTeam {
  id: string;
  name: string;
  display_name: string;
}

export interface MattermostChannel {
  id: string;
  name: string;
  display_name: string;
  team_id: string;
  /** Epoch milliseconds. */
  create_at: number;
  /** Non-zero once the channel is archived. */
  delete_at?: number;
}

export interface MattermostUser {
  id: string;
  username: string;
  is_bot?: boolean;
}

export interface MattermostPost {
  id: string;
  channel_id: string;
  user_id: string;
  message: string;
  create_at: number;
  update_at: number;
  root_id: string;
  type: string;
  props?: Record<string, unknown>;
}

export class MattermostHttpError extends Error {
  readonly status: number;
  readonly body: string;
  constructor(method: string, path: string, status: number, body: string) {
    super(`${method} ${path} -> ${status}: ${body.slice(0, 400)}`);
    this.name = 'MattermostHttpError';
    this.status = status;
    this.body = body;
  }
}

export class MattermostClient {
  private readonly baseUrl: string;
  private readonly token: string;
  private readonly environment: Environment;

  constructor(env: MattermostEnv, environment: Environment) {
    this.baseUrl = env.url.endsWith('/') ? env.url.slice(0, -1) : env.url;
    this.token = env.token;
    this.environment = environment;
  }

  private async request<T>(
    method: string,
    path: string,
    body?: unknown,
    options: { allow404?: boolean } = {}
  ): Promise<T> {
    assertAllowed(this.environment, method, `/api/v4${path}`);
    const headers: Record<string, string> = {
      Authorization: `Bearer ${this.token}`,
      Accept: 'application/json',
    };
    if (body !== undefined) headers['Content-Type'] = 'application/json';

    const response = await fetch(`${this.baseUrl}/api/v4${path}`, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
      signal: AbortSignal.timeout(30_000),
    });

    if (response.status === 404 && options.allow404) return null as T;
    if (!response.ok) {
      throw new MattermostHttpError(method, path, response.status, await response.text());
    }
    const text = await response.text();
    return (text === '' ? undefined : JSON.parse(text)) as T;
  }

  /**
   * Sign a new person up, as anyone may on a server with open sign-up, and
   * log them in. `POST /api/v4/users`, then `POST /api/v4/users/login`, whose
   * `Token` header is the session token the returned client posts with.
   */
  static async signUp(
    env: MattermostEnv,
    environment: Environment,
    person: { username: string; email: string; password: string }
  ): Promise<{ client: MattermostClient; user: MattermostUser; token: string }> {
    const base = env.url.endsWith('/') ? env.url.slice(0, -1) : env.url;
    const send = async (path: string, body: unknown): Promise<Response> => {
      assertAllowed(environment, 'POST', `/api/v4${path}`);
      const response = await fetch(`${base}/api/v4${path}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(30_000),
      });
      if (!response.ok) {
        throw new MattermostHttpError('POST', path, response.status, await response.text());
      }
      return response;
    };
    const user = (await (await send('/users', person)).json()) as MattermostUser;
    const login = await send('/users/login', {
      login_id: person.username,
      password: person.password,
    });
    const token = login.headers.get('Token');
    if (token === null) throw new Error(`Mattermost logged ${person.username} in without a token.`);
    return { client: new MattermostClient({ ...env, token }, environment), user, token };
  }

  /**
   * Take a person the harness signed up off the server again: deactivate them
   * (`DELETE /api/v4/users/{id}`, as themselves), or, where Mattermost does not
   * let a person deactivate themselves, take them out of every team and sign
   * them out, and say that the account itself is left behind.
   */
  async leave(userId: string): Promise<void> {
    try {
      await this.request('DELETE', `/users/${userId}`);
      return;
    } catch (error) {
      if (!(error instanceof MattermostHttpError) || ![401, 403, 501].includes(error.status)) {
        throw error;
      }
      const teams = await this.request<MattermostTeam[]>('GET', `/users/${userId}/teams`);
      for (const team of teams) {
        await this.request('DELETE', `/teams/${team.id}/members/${userId}`);
      }
      await this.request('POST', '/users/logout');
      console.warn(
        `Mattermost does not let ${userId} deactivate itself here (${error.status}); ` +
          'it was taken out of its teams and signed out, but the account remains.'
      );
    }
  }

  /** `POST /api/v4/teams/{id}/members` — join a team that is open to anyone, as the token's user. */
  async joinTeam(teamId: string, userId: string): Promise<void> {
    await this.request('POST', `/teams/${teamId}/members`, { team_id: teamId, user_id: userId });
  }

  /** `GET /api/v4/users/me` — also the reachability + token-validity probe. */
  async me(): Promise<MattermostUser> {
    return this.request<MattermostUser>('GET', '/users/me');
  }

  /** `GET /api/v4/teams/name/{team}` — `team` is the URL slug, e.g. `switch`. */
  async findTeam(teamName: string): Promise<MattermostTeam> {
    const team = await this.request<MattermostTeam | null>(
      'GET',
      `/teams/name/${encodeURIComponent(teamName)}`,
      undefined,
      { allow404: true }
    );
    if (!team) throw new Error(`Mattermost team '${teamName}' not found`);
    return team;
  }

  /**
   * `POST /api/v4/channels` with `team_id` in the **body** — create an open
   * channel. (There is no `POST /teams/{id}/channels`; that path 404s.) The
   * creating user is a member automatically, which is what lets the harness post
   * into it afterwards.
   */
  async createChannel(params: {
    teamId: string;
    name: string;
    displayName: string;
    purpose?: string;
  }): Promise<MattermostChannel> {
    return this.request<MattermostChannel>('POST', '/channels', {
      team_id: params.teamId,
      name: params.name,
      display_name: params.displayName,
      purpose: params.purpose ?? '',
      type: 'O',
    });
  }

  /** `GET /api/v4/teams/{team_id}/channels` — the team's public channels. */
  async listTeamChannels(teamId: string): Promise<MattermostChannel[]> {
    return this.request<MattermostChannel[]>('GET', `/teams/${teamId}/channels?per_page=200`);
  }

  /** `GET /api/v4/channels/{id}`. */
  async getChannel(channelId: string): Promise<MattermostChannel> {
    return this.request<MattermostChannel>('GET', `/channels/${channelId}`);
  }

  /** `DELETE /api/v4/channels/{id}` — archives the channel (Mattermost soft-delete). */
  async archiveChannel(channelId: string): Promise<void> {
    await this.request('DELETE', `/channels/${channelId}`);
  }

  /**
   * `GET /api/v4/users/username/{username}`. For a Switch agent's bot this is
   * the agent name verbatim. Returns null when no such user exists yet — the
   * bot is created asynchronously at agent registration, so callers poll.
   */
  async findBotUser(username: string): Promise<MattermostUser | null> {
    return this.request<MattermostUser | null>(
      'GET',
      `/users/username/${encodeURIComponent(username)}`,
      undefined,
      { allow404: true }
    );
  }

  /** Poll {@link findBotUser} until the bridge has minted the agent's bot. */
  async waitForBotUser(username: string, deadlineMs: number): Promise<MattermostUser> {
    const until = Date.now() + deadlineMs;
    for (;;) {
      const user = await this.findBotUser(username);
      if (user) return user;
      if (Date.now() >= until) {
        throw new Error(
          `Mattermost bot account '${username}' did not appear within ${deadlineMs}ms. ` +
            `The Mattermost collaboration bridge mints it at agent registration — check the bridge is running.`
        );
      }
      await sleep(2_000);
    }
  }

  /**
   * `POST /api/v4/channels/{channel_id}/members {user_id}` — adding the agent's
   * bot to a channel is what makes Switch provision a room for it. This is the
   * REST equivalent of typing `!invite-agent @agent-name` in the channel.
   */
  async addUserToChannel(channelId: string, userId: string): Promise<void> {
    await this.request('POST', `/channels/${channelId}/members`, {
      user_id: userId,
      channel_id: channelId,
    });
  }

  /** `POST /api/v4/posts` — post as the token's user. */
  async post(params: {
    channelId: string;
    message: string;
    rootId?: string;
  }): Promise<MattermostPost> {
    return this.request<MattermostPost>('POST', '/posts', {
      channel_id: params.channelId,
      message: params.message,
      root_id: params.rootId ?? '',
    });
  }

  /**
   * `GET /api/v4/channels/{id}/posts?since=<ms>` — posts created or updated at
   * or after `sinceMs`, returned oldest-first here (Mattermost hands back an
   * `order` array that is newest-first).
   */
  async postsSince(channelId: string, sinceMs: number): Promise<MattermostPost[]> {
    const body = await this.request<{
      order: string[];
      posts: Record<string, MattermostPost>;
    }>('GET', `/channels/${channelId}/posts?since=${Math.floor(sinceMs)}`);
    return (body.order ?? [])
      .map((id) => body.posts[id])
      .filter((post): post is MattermostPost => post !== undefined)
      .sort((a, b) => a.create_at - b.create_at);
  }

  /**
   * Wait for a post from `userId` matching `predicate`.
   *
   * Returns the whole transcript seen in the window either way, so a failing
   * scenario can report what the agent *did* say instead of only that it timed
   * out. `sinceMs` advances as posts arrive, and system posts (`type` starting
   * `system_`) are dropped — a bot join emits one and it is not a reply.
   */
  async waitForPost(params: {
    channelId: string;
    fromUserId: string;
    predicate: (post: MattermostPost) => boolean;
    sinceMs: number;
    deadlineMs: number;
    pollIntervalMs?: number;
  }): Promise<{ match: MattermostPost | null; transcript: MattermostPost[] }> {
    const until = Date.now() + params.deadlineMs;
    const transcript: MattermostPost[] = [];
    const seen = new Set<string>();
    let since = params.sinceMs;

    for (;;) {
      const posts = await this.postsSince(params.channelId, since);
      for (const post of posts) {
        if (seen.has(post.id)) continue;
        seen.add(post.id);
        if (post.create_at >= since) since = post.create_at;
        if (post.type?.startsWith('system_')) continue;
        transcript.push(post);
        if (post.user_id === params.fromUserId && params.predicate(post)) {
          return { match: post, transcript };
        }
      }
      if (Date.now() >= until) return { match: null, transcript };
      await sleep(params.pollIntervalMs ?? 2_000);
    }
  }

  /**
   * Whether any post from `userId` arrived in the window — used by the interrupt
   * scenario, which asserts the *absence* of further output rather than the
   * presence of a reply.
   */
  async postsFrom(channelId: string, userId: string, sinceMs: number): Promise<MattermostPost[]> {
    const posts = await this.postsSince(channelId, sinceMs);
    return posts.filter((post) => post.user_id === userId && !post.type?.startsWith('system_'));
  }
}

export function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}