Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

21.1 KB
Raw Blame
import * as Match from "effect/Match";
import * as Predicate from "effect/Predicate";
import { createDiscordAdapter } from "@chat-adapter/discord";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createWhatsAppAdapter } from "@chat-adapter/whatsapp";
import { TelegramProvider } from "@mastra/telegram";
import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
import { BotId, type ChannelProvider } from "@akeru/contracts";
import { type Adapter, Chat, ConsoleLogger, type Message } from "chat";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Scope from "effect/Scope";
import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
import {
  ChannelRuntimeError,
  failWith,
  ChannelTransportError,
  transportError,
  fromPromise,
  isChannelPostRejected,
  channelFailureMessage,
  postChannelText,
} from "./ChannelErrors.ts";
import {
  type ChannelTransportRuntime,
  type ChannelRuntimeEntry,
  type StartedTransport,
  type InboundCallback,
  type ChannelTransportContext,
  type ChannelConnectInput,
} from "./ChannelRuntimeTypes.ts";
import { normalizedInboundMessage, mentionWithContext } from "./ChannelInbound.ts";

export const fromTransportRuntime = (runtime: ChannelTransportRuntime): ChannelRuntimeEntry => {
  const { webhook, react, removeReaction, isHealthy, settled } = runtime;

  return {
    // Injected transports signal a definite provider rejection by throwing ChannelPostRejectedError.
    post: (externalThreadId, text) =>
      Effect.tryPromise({
        try: () => runtime.post(externalThreadId, text),
        catch: (cause) => (isChannelPostRejected(cause) ? cause : transportError(cause)),
      }),
    shutdown: fromPromise(() => runtime.shutdown()),
    ...(webhook ? { webhook: (request: Request) => fromPromise(() => webhook(request)) } : {}),
    ...(react
      ? {
          react: (externalThreadId: string, externalMessageId: string, emoji: string) =>
            fromPromise(() => react(externalThreadId, externalMessageId, emoji)),
        }
      : {}),
    ...(removeReaction
      ? {
          removeReaction: (externalThreadId: string, externalMessageId: string, emoji: string) =>
            fromPromise(() => removeReaction(externalThreadId, externalMessageId, emoji)),
        }
      : {}),
    ...(isHealthy ? { isHealthy } : {}),
    ...(settled
      ? {
          settled: Effect.promise(() =>
            settled.then(
              () => undefined,
              () => undefined,
            ),
          ),
        }
      : {}),
  };
};

export const CHANNEL_GATEWAY_RENEWAL_INTERVAL = Duration.hours(1);

export const shutdownChat = (chat: Chat) => fromPromise(() => chat.shutdown());

export const initializeChannelChat = (chat: Chat) =>
  fromPromise(() => chat.initialize()).pipe(
    Effect.onError(() => shutdownChat(chat).pipe(Effect.ignoreCause)),
  );

/**
 * Blank messages and anything a bot wrote, including this bot, never start a turn.
 *
 * Discord, Slack, WhatsApp and iMessage always give a person's message a real boolean, so an
 * `"unknown"` author there is treated as a bot. Telegram reports `"unknown"` for messages sent on
 * behalf of a chat (`sender_chat`: anonymous group admins and linked channel posts), which people
 * write, so only an explicit `true` counts as a bot on Telegram.
 */
export const ignoredInbound = (provider: ChannelProvider, message: Message) =>
  !message.text.trim() ||
  message.author.isMe === true ||
  (provider === "telegram" ? message.author.isBot === true : message.author.isBot !== false);

export const startTelegram = (botId: BotId, token: string, onDirectMessage: InboundCallback) =>
  Effect.gen(function* () {
    const provider = new TelegramProvider({ mode: "polling", commands: [] });

    const connected = yield* fromPromise(() =>
      provider.connect(botId, { botToken: token, commands: [] }),
    );

    if (connected.type !== "immediate")
      return yield* failWith("Telegram did not connect immediately.");
    const installation = yield* fromPromise(() => provider.getInstallation(botId));
    const adapter = provider.getAdapter(connected.installationId);

    if (!installation || !adapter)
      return yield* failWith("Telegram did not create an active adapter.");

    // SAFETY: The SDK adapter implements the Chat transport protocol; the assertion bridges separately packaged adapter type declarations.
    const chat = new Chat({
      userName: installation.username ?? "Akeru Bot",
      adapters: { telegram: adapter as Adapter },
      state: createMemoryState(),
    });

    chat.onDirectMessage(async (thread, message) => {
      if (ignoredInbound("telegram", message)) return;
      await onDirectMessage(normalizedInboundMessage(thread, message));
    });
    const disconnect = fromPromise(() => provider.disconnect(botId)).pipe(Effect.ignoreCause);
    yield* Effect.gen(function* () {
      yield* initializeChannelChat(chat);

      if (!adapter.botUserId) {
        yield* shutdownChat(chat);

        return yield* failWith("Telegram did not identify the connected bot.");
      }
    }).pipe(Effect.onError(() => disconnect));

    return {
      externalIdentity: installation.username ? `@${installation.username}` : botId,
      runtime: {
        post: (externalThreadId, text) => postChannelText(chat, "telegram", externalThreadId, text),
        shutdown: shutdownChat(chat).pipe(Effect.andThen(disconnect)),
      },
    } satisfies StartedTransport;
  });

export interface RenewingGateway {
  readonly isHealthy: () => boolean;
  /** Completes when the supervisor stops, after a failure or shutdown. */
  readonly settled: Effect.Effect<void>;
  /** Aborts the listener, stops renewal, and waits for the listener task to finish. */
  readonly shutdown: Effect.Effect<void>;
}

/**
 * Keeps a time-limited gateway listener alive. Each cycle launches a listener that ends
 * itself at the renewal deadline and watches it until then; a schedule repeats the cycle.
 * Each cycle aborts and awaits the previous listener before launching the next one.
 * The first launch completes before this returns, and a failed first launch fails with its
 * cause so the connect can classify it. A later listener that stops early or fails to launch
 * leaves the gateway unhealthy. Renewal runs in its own child of the caller's scope, so
 * closing that scope stops it.
 */
export const startRenewingGateway = (
  start: (
    waitUntil: (task: Promise<unknown>) => void,
    durationMs: number,
    signal: AbortSignal,
  ) => Promise<Response>,
  label: string,
): Effect.Effect<RenewingGateway, ChannelTransportError | ChannelRuntimeError, Scope.Scope> =>
  Effect.gen(function* () {
    const scope = yield* Scope.fork(yield* Scope.Scope);
    let abort = new AbortController();
    const durationMs = Duration.toMillis(CHANNEL_GATEWAY_RENEWAL_INTERVAL);
    let healthy = true;
    let activeTask: Promise<unknown> | undefined;
    const currentTask = () => activeTask;
    const settle = (task: Promise<unknown>) => Effect.promise(() => task);

    const launch = Effect.gen(function* () {
      // A listener still running at its deadline must stop before the next one starts.
      const previous = currentTask();
      abort.abort();

      if (previous) yield* settle(previous);
      abort = new AbortController();
      activeTask = undefined;

      const response = yield* fromPromise(() =>
        start(
          (task) => {
            // Observe the task at once so an early rejection is never unhandled.
            activeTask = task.then(
              () => undefined,
              () => undefined,
            );
          },
          durationMs,
          abort.signal,
        ),
      );

      // Server-side and rate-limit statuses are worth retrying; anything else is a rejection.
      if (!response.ok) {
        const category =
          response.status >= 500 || response.status === 429 ? "network" : "credentials";

        return yield* failWith(channelFailureMessage(category), category);
      }

      const task = currentTask();

      if (!task) return yield* failWith(`${label} did not start a listener.`);

      return task;
    });

    const watch = (task: Promise<unknown>) =>
      settle(task).pipe(
        Effect.andThen(failWith(`${label} stopped before its renewal deadline.`)),
        Effect.timeoutOption(CHANNEL_GATEWAY_RENEWAL_INTERVAL),
      );

    // The first listener launches before this returns, so callers see it running.
    const first = yield* Effect.exit(launch);

    if (Exit.isFailure(first)) {
      abort.abort();
      yield* Scope.close(scope, Exit.void);
      const task = currentTask();

      if (task) yield* settle(task);

      return yield* Effect.failCause(first.cause);
    }

    const renew = launch.pipe(Effect.flatMap(watch), Effect.repeat(Schedule.forever));

    const supervisor = yield* watch(first.value).pipe(
      Effect.andThen(renew),
      Effect.onError(() =>
        Effect.sync(() => {
          healthy = false;
        }),
      ),
      Effect.ignoreCause,
      Effect.forkIn(scope),
    );

    return {
      isHealthy: () => healthy,
      settled: Fiber.await(supervisor).pipe(Effect.asVoid),
      shutdown: Effect.gen(function* () {
        healthy = false;
        yield* Scope.close(scope, Exit.void);
        abort.abort();
        const task = currentTask();

        if (task) yield* settle(task);
      }),
    } satisfies RenewingGateway;
  });

export function registerThreadedHandlers(
  chat: Chat,
  provider: ChannelProvider,
  context: ChannelTransportContext,
) {
  chat.onNewMention(async (thread, message) => {
    if (ignoredInbound(provider, message)) return;
    await thread.subscribe();
    await context.onMention(await mentionWithContext(thread, message));
  });
  chat.onSubscribedMessage(async (thread, message) => {
    if (ignoredInbound(provider, message)) return;
    await context.onSubscribedMessage(normalizedInboundMessage(thread, message));
  });
}

export const onDirectText = (
  chat: Chat,
  provider: ChannelProvider,
  onDirectMessage: InboundCallback,
) =>
  chat.onDirectMessage(async (thread, message) => {
    if (ignoredInbound(provider, message)) return;
    await onDirectMessage(normalizedInboundMessage(thread, message));
  });

export const subscribeThreads = (chat: Chat, context: ChannelTransportContext) =>
  Effect.promise(() =>
    Promise.allSettled(
      context.subscribedThreadIds.map((externalThreadId) =>
        chat.thread(externalThreadId).subscribe(),
      ),
    ),
  );

export const startIMessage = (
  input: Extract<ChannelConnectInput, { readonly provider: "imessage" }>,
  context: ChannelTransportContext,
  onDirectMessage: InboundCallback,
) =>
  Effect.gen(function* () {
    const adapter = createiMessageAdapter(
      input.mode === "hosted"
        ? { projectId: input.projectId, projectSecret: input.projectSecret }
        : {
            serverUrl: input.serverUrl,
            apiKey: input.apiKey,
            ...(input.phone ? { phone: input.phone } : {}),
          },
    );

    const chat = new Chat({
      userName: context.botName,
      adapters: { imessage: adapter },
      state: createMemoryState(),
    });

    onDirectText(chat, "imessage", onDirectMessage);
    yield* initializeChannelChat(chat);

    const gateway = yield* startRenewingGateway(
      (waitUntil, durationMs, signal) =>
        adapter.startGatewayListener({ waitUntil }, durationMs, signal),
      "Photon gateway",
    ).pipe(Effect.onError(() => shutdownChat(chat).pipe(Effect.ignoreCause)));

    return {
      externalIdentity:
        input.mode === "self-hosted" && input.phone
          ? input.phone
          : input.mode === "hosted"
            ? "Photon hosted"
            : "Photon self-hosted",
      runtime: {
        post: (externalThreadId, text) => postChannelText(chat, "imessage", externalThreadId, text),
        isHealthy: gateway.isHealthy,
        settled: gateway.settled,
        shutdown: gateway.shutdown.pipe(Effect.andThen(shutdownChat(chat))),
      },
    } satisfies StartedTransport;
  });

export const startWhatsApp = (
  input: Extract<ChannelConnectInput, { readonly provider: "whatsapp" }>,
  context: ChannelTransportContext,
  onDirectMessage: InboundCallback,
) =>
  Effect.gen(function* () {
    const adapter = createWhatsAppAdapter({
      accessToken: input.accessToken,
      appSecret: input.appSecret,
      phoneNumberId: input.phoneNumberId,
      verifyToken: input.verifyToken,
      userName: context.botName,
    });

    // SAFETY: The SDK adapter implements the Chat transport protocol; the assertion bridges separately packaged adapter type declarations.
    const chat = new Chat({
      userName: context.botName,
      adapters: { whatsapp: adapter as Adapter },
      state: createMemoryState(),
    });

    onDirectText(chat, "whatsapp", onDirectMessage);
    yield* initializeChannelChat(chat);

    return {
      externalIdentity: input.phoneNumberId,
      runtime: {
        post: (externalThreadId, text) => postChannelText(chat, "whatsapp", externalThreadId, text),
        shutdown: shutdownChat(chat),
        webhook: (request) =>
          Effect.gen(function* () {
            const tasks: Promise<unknown>[] = [];

            const response = yield* fromPromise(() =>
              adapter.handleWebhook(request, { waitUntil: (task) => void tasks.push(task) }),
            ).pipe(Effect.option);

            if (Option.isNone(response))
              return new Response("Invalid webhook payload", { status: 400 });
            const results = yield* Effect.promise(() => Promise.allSettled(tasks));

            return results.some((result) => result.status === "rejected")
              ? new Response("Webhook processing failed", { status: 500 })
              : response.value;
          }),
      },
    } satisfies StartedTransport;
  });

export const SLACK_APP_TOKEN_INVALID = "Slack app-level token is invalid.";

export const SLACK_UNREACHABLE = "Slack could not be reached. Check the network and try again.";

// Slack `error` codes that mean the app-level token itself is unusable.
export const SLACK_TOKEN_ERRORS: ReadonlySet<unknown> = new Set([
  "invalid_auth",
  "not_authed",
  "token_revoked",
  "token_expired",
  "account_inactive",
  "not_allowed_token_type",
  "missing_scope",
]);

// Socket Mode retries a rejected app token in the background instead of failing `initialize`,
// so the token is checked up front. Only a Slack auth error blames the token; network, HTTP,
// and other Slack failures report that Slack could not be reached. Slack's own error text is
// dropped to keep it out of logs.
export const validateSlackAppToken = (
  appToken: string,
  httpClient: HttpClient.HttpClient | undefined,
) =>
  Effect.gen(function* () {
    if (!appToken.startsWith("xapp-"))
      return yield* failWith(SLACK_APP_TOKEN_INVALID, "credentials");

    const probe = HttpClient.execute(
      HttpClientRequest.post("https://slack.com/api/apps.connections.open").pipe(
        HttpClientRequest.bearerToken(appToken),
      ),
    ).pipe(Effect.flatMap((response) => response.json));

    const body = yield* (
      httpClient
        ? probe.pipe(Effect.provideService(HttpClient.HttpClient, httpClient))
        : probe.pipe(Effect.provide(FetchHttpClient.layer))
    ).pipe(
      Effect.mapError(
        () => new ChannelRuntimeError({ message: SLACK_UNREACHABLE, category: "network" }),
      ),
    );

    if (Predicate.isObjectOrArray(body) && "ok" in body && body.ok === true) return;

    if (Predicate.isObjectOrArray(body) && "error" in body && SLACK_TOKEN_ERRORS.has(body.error))
      return yield* failWith(SLACK_APP_TOKEN_INVALID, "credentials");

    return yield* failWith(SLACK_UNREACHABLE, "network");
  });

export const startSlack = (
  input: Extract<ChannelConnectInput, { readonly provider: "slack" }>,
  context: ChannelTransportContext,
  onDirectMessage: InboundCallback,
) =>
  Effect.gen(function* () {
    yield* validateSlackAppToken(input.appToken, context.httpClient);

    const adapter = createSlackAdapter({
      mode: "socket",
      botToken: input.botToken,
      appToken: input.appToken,
      // An internal retry could hide an accepted request behind a later rejection.
      webClientOptions: { retryConfig: { retries: 0 }, rejectRateLimitedCalls: true },
    });

    const state = createMemoryState();
    yield* fromPromise(() => state.connect());
    yield* fromPromise(() =>
      Promise.all(context.subscribedThreadIds.map((threadId) => state.subscribe(threadId))),
    );

    // SAFETY: The SDK adapter implements the Chat transport protocol; the assertion bridges separately packaged adapter type declarations.
    const chat = new Chat({
      userName: context.botName,
      adapters: { slack: adapter as Adapter },
      state,
    });

    onDirectText(chat, "slack", onDirectMessage);
    registerThreadedHandlers(chat, "slack", context);
    yield* initializeChannelChat(chat);

    if (!adapter.botUserId) {
      yield* shutdownChat(chat);

      return yield* failWith("Slack bot credentials are invalid.");
    }

    yield* subscribeThreads(chat, context);

    return {
      externalIdentity: adapter.botUserId,
      runtime: {
        react: (externalThreadId, externalMessageId, emoji) =>
          fromPromise(() => adapter.addReaction(externalThreadId, externalMessageId, emoji)),
        removeReaction: (externalThreadId, externalMessageId, emoji) =>
          fromPromise(() => adapter.removeReaction(externalThreadId, externalMessageId, emoji)),
        post: (externalThreadId, text) => postChannelText(chat, "slack", externalThreadId, text),
        shutdown: shutdownChat(chat),
      },
    } satisfies StartedTransport;
  });

export const startDiscord = (
  input: Extract<ChannelConnectInput, { readonly provider: "discord" }>,
  context: ChannelTransportContext,
  onDirectMessage: InboundCallback,
) =>
  Effect.gen(function* () {
    const adapter = createDiscordAdapter({
      applicationId: input.applicationId,
      botToken: input.botToken,
      // The SDK requires a key to verify interaction webhooks. Akeru only uses the gateway,
      // but a placeholder verifier would silently reject interactions if they are ever routed.
      publicKey: input.publicKey,
      // The SDK falls back to DISCORD_* environment variables for these. Only a direct mention
      // of the bot starts a chat, whatever the server's environment says.
      mentionRoleIds: [],
      respondToChannelIds: [],
      respondToGlobalMentions: false,
      // Info-level gateway logs include message content.
      logger: new ConsoleLogger("warn", "discord"),
    });

    // SAFETY: The SDK adapter implements the Chat transport protocol; the assertion bridges separately packaged adapter type declarations.
    const chat = new Chat({
      userName: context.botName,
      adapters: { discord: adapter as Adapter },
      state: createMemoryState(),
    });

    onDirectText(chat, "discord", onDirectMessage);
    registerThreadedHandlers(chat, "discord", context);
    yield* initializeChannelChat(chat);

    const identity = yield* fromPromise(() => adapter.getUser(input.applicationId)).pipe(
      Effect.onError(() => shutdownChat(chat).pipe(Effect.ignoreCause)),
    );

    if (!identity) {
      yield* shutdownChat(chat);

      return yield* failWith("Discord credentials are invalid.");
    }

    yield* subscribeThreads(chat, context);

    const gateway = yield* startRenewingGateway(
      (waitUntil, durationMs, signal) =>
        adapter.startGatewayListener({ waitUntil }, durationMs, signal),
      "Discord gateway",
    ).pipe(Effect.onError(() => shutdownChat(chat).pipe(Effect.ignoreCause)));

    return {
      externalIdentity: `${identity.userName} (${identity.userId})`,
      runtime: {
        post: (externalThreadId, text) => postChannelText(chat, "discord", externalThreadId, text),
        react: (externalThreadId, externalMessageId, emoji) =>
          fromPromise(() => adapter.addReaction(externalThreadId, externalMessageId, emoji)),
        removeReaction: (externalThreadId, externalMessageId, emoji) =>
          fromPromise(() => adapter.removeReaction(externalThreadId, externalMessageId, emoji)),
        isHealthy: gateway.isHealthy,
        settled: gateway.settled,
        shutdown: gateway.shutdown.pipe(Effect.andThen(shutdownChat(chat))),
      },
    } satisfies StartedTransport;
  });

export const startBuiltInTransport = (
  botId: BotId,
  input: ChannelConnectInput,
  context: ChannelTransportContext,
  onDirectMessage: InboundCallback,
): Effect.Effect<StartedTransport, ChannelRuntimeError | ChannelTransportError, Scope.Scope> =>
  Match.value(input).pipe(
    Match.when({ provider: "telegram" }, (input) =>
      startTelegram(botId, input.token, onDirectMessage),
    ),
    Match.when({ provider: "imessage" }, (input) => startIMessage(input, context, onDirectMessage)),
    Match.when({ provider: "whatsapp" }, (input) => startWhatsApp(input, context, onDirectMessage)),
    Match.when({ provider: "slack" }, (input) => startSlack(input, context, onDirectMessage)),
    Match.orElse((input) => startDiscord(input, context, onDirectMessage)),
  );