Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

15.0 KB
Raw Blame
/**
 * The messaging-channel connector seam: what the MessagingBridge needs from one chat
 * platform (Feishu, Telegram, QQ and WeChat today; further channels implement the same interface
 * and register in app assembly). A connector owns everything channel-specific — credential
 * shape, wire protocol, event normalization — and hands the bridge a channel-neutral
 * view: a client for outbound sends and credential checks, and a long-lived event
 * connection delivering normalized inbound messages (text, images and files, each as far as
 * the channel actually carries them).
 *
 * Config documents are the repo's stored per-channel JSON (`MessagingBindingRow.config`);
 * every connector method validates its own shape and throws a readable error on a
 * malformed one — the bridge treats that like any other channel failure.
 */
import type { MessagingChannel } from "../../api/types.js";

/**
 * Known messaging channels, declared once with the wire types. The DB stores the discriminator
 * as text; `isMessagingChannel` (enabled-channel.ts) narrows a stored one, and an unknown value
 * is skipped defensively.
 */
export type { MessagingChannel };

/** One inbound image's bytes, once fetched, with the MIME type the bridge needs for its data URL. */
export interface MessagingInboundImageData {
  data: Buffer;
  /** e.g. `image/png` — the connector's best answer, from the channel's own type or the bytes. */
  mimeType: string;
}

/**
 * An image attached to an inbound message: a handle, not the bytes.
 *
 * The bytes are deliberately NOT eagerly downloaded by the connector. Most of what makes
 * an inbound message uninteresting is decided after the event is normalized — a
 * redelivery is dropped before anything else happens — and a channel that downloaded
 * first would pay a full image transfer for every replay. Fetching lazily also puts the
 * cap where the transfer is: `fetch` refuses anything over `maxBytes` rather than handing
 * the bridge something it would only discard, which is what keeps a 100MB attachment from
 * ever being resident in this process.
 */
export interface MessagingInboundImage {
  /**
   * Downloads the image. Two distinct failures, and the bridge answers them differently:
   * `MessagingMediaTooLargeError` (see media.ts) for anything past `maxBytes`, which the
   * user fixes by sending something smaller, and any other Error — carrying the channel's
   * OWN reason, since a permission the bot lacks and a network blip are not the same
   * problem — for a transfer that could not be made at all. That reason reaches the chat,
   * so a connector must keep credentials out of it (see telegram-api's fetchErrorText).
   */
  fetch(maxBytes: number): Promise<MessagingInboundImageData>;
}

/**
 * A non-image file attached to an inbound message: a handle, not the bytes, for exactly the
 * reasons MessagingInboundImage is one — a redelivery is dropped before anything is
 * transferred, and the cap rides into `fetch` so an oversized attachment is refused at the
 * byte that crosses it rather than buffered whole and measured afterwards. A file's ceiling
 * is the server's per-file attachment limit, which is far larger than an image's, so the
 * difference between refusing during and after the transfer is correspondingly larger.
 *
 * There is no MIME type on this seam. An image needs one because its bytes become a `data:`
 * URL inside the conversation; a file's bytes go to the Session scratchpad and reach the
 * model as a PATH, so the name's extension is the whole of what says what it is — and a
 * channel's declared media type is the sender's claim about a file nothing here parses.
 */
export interface MessagingInboundFile {
  /**
   * The sender's own file name, extension included — what the model sees at the end of the
   * `[attached file: …]` path, and what a refusal notice names. Channel text, so it is
   * neither trusted nor pre-sanitized here: the attachment writer maps it onto a name that
   * is safe on disk (see services/task-attachments.ts). A channel with no name for a file
   * says so with a plain fallback rather than inventing one, since a made-up extension
   * would tell the model the file is something it is not.
   */
  fileName: string;
  /** Downloads the file; the same two failure shapes MessagingInboundImage.fetch documents. */
  fetch(maxBytes: number): Promise<Buffer>;
}

/** One inbound chat message, normalized across channels. */
export interface MessagingInboundMessage {
  /**
   * Channel-scoped chat id, and the reply target for direct chats. Opaque to the bridge, for
   * the same reason `messageId` is: the connector both mints it here and consumes it in
   * `sendText`, so a channel whose replies need more routing context than a chat identity
   * encodes it (Telegram appends the forum topic). It is stored verbatim as the binding's
   * last known chat, so whatever is encoded here is what survives a restart.
   */
  chatId: string;
  /** Direct chat with the bot, or a group chat (groups prefer reply-to-message). */
  chatKind: "direct" | "group";
  /**
   * Channel-scoped id of the inbound message itself (the group reply target). Opaque to
   * the bridge: the connector both mints it here and consumes it in `replyText`, so a
   * channel whose native message ids are not globally unique encodes whatever context a
   * reply needs (Telegram packs `chatId:messageId`). It is also the bridge's inbound
   * dedupe key, so it must identify the MESSAGE and not the delivery: a channel that
   * redelivers one message must mint the same id both times. `""` opts the channel out of
   * deduplication entirely — the honest answer for a connector with no message identity,
   * and better than every message after the first reading as a duplicate.
   */
  messageId: string;
  /**
   * The message's plain text; null for anything that carries none (stickers, voice, …) — a
   * message with no text, no image and no file gets the not-supported notice. An image or a
   * file sent with a caption puts the caption here: the caption IS that message's text, so
   * a channel needs no second field for it and the bridge no second rule. A channel that
   * carries a caption on media it does NOT deliver must still report null, or the model
   * answers a question about an attachment it never received.
   */
  text: string | null;
  /**
   * Images attached to this message (absent or empty when there are none). Handles rather
   * than bytes — see MessagingInboundImage. A channel that carries several images in one
   * message lists them in the order the user sees them.
   */
  images?: readonly MessagingInboundImage[];
  /**
   * Non-image files attached to this message, in the order the user sees them (absent or
   * empty when there are none) — see MessagingInboundFile.
   *
   * Optional, like `images`, so a channel that delivers no files simply never populates it
   * rather than carrying an empty list through its whole normalizer. A message may carry
   * text, images and files together; the bridge composes one composer input out of whatever
   * is there.
   */
  files?: readonly MessagingInboundFile[];
  /** Sender display name when the channel's event carries one. */
  senderName?: string;
}

export interface MessagingConnectorHandlers {
  onMessage(msg: MessagingInboundMessage): void | Promise<void>;
  /** The connection completed a handshake (may fire again after an automatic reconnect). */
  onReady?(): void;
  /**
   * The connection failed and the channel gave up (or the initial connect failed). A
   * {@link MessagingChannelError} says whether the outage clears without anyone acting.
   */
  onError?(err: unknown): void;
}

/** A live inbound event stream; `close` ends it (idempotent). */
export interface MessagingConnection {
  close(): void;
}

/**
 * A channel failure that carries its connector's verdict on whether anybody has to act.
 *
 * `recovers` answers one question: made again with nothing changed, does the same attempt go
 * through? A connection the connector's own retry brings back — a network drop, a reset TLS
 * handshake, a deadline, a platform restarting — does, and so does a send the next message
 * gets past (a 5xx, a rate limit). A credential the platform refused, a permission never
 * granted or a console setting in the way does not, however eagerly the connector retries.
 *
 * The verdict is decided where the failure is understood — the transport that read the
 * platform's status and its own code, or the connection loop that knows why it gave up on a
 * socket — and error-kind.ts reads the boolean and nothing else: a wording match would tie
 * the dashboard's "needs a human" count to how a platform phrases itself.
 */
export class MessagingChannelError extends Error {
  constructor(
    message: string,
    /** Whether the same attempt, made again with nothing changed, goes through. */
    readonly recovers: boolean,
  ) {
    super(message);
    this.name = "MessagingChannelError";
  }
}

/**
 * Whether a request the platform answered with this HTTP status may go through unchanged next
 * time: 408 and 429 say "not now" and a 5xx is the platform's own fault, while any other 4xx is
 * a refusal that repeats until someone changes something — the line core draws for an LLM
 * provider's status.
 */
export function httpStatusRecovers(status: number | undefined): boolean {
  return status === 408 || status === 429 || (status !== undefined && status >= 500);
}

/**
 * A successful credential check's optional payload: whatever the probe learned that the test
 * endpoint's feedback can act on. Every member is independently optional — a channel reports
 * the ones its check happens to answer and omits the rest, so a check that learned nothing
 * beyond "these credentials work" returns an empty object.
 */
export interface MessagingAccountInfo {
  /** A short human-readable label of the account the credentials sign in as (Telegram: the bot's `@username`). */
  accountLabel?: string;
  /**
   * Whether this ACCOUNT is set up to receive ordinary messages in the groups it belongs to
   * — as opposed to only the ones a platform hands a bot by default.
   *
   * Telegram's privacy mode is the case that needs saying: it is on for every bot whose
   * owner has not turned it off in @BotFather, and under it `getUpdates` simply omits
   * everything in a group that is not a command addressed to this bot or a reply to one of
   * its messages. Nothing errors — the messages are never delivered, so a binding that works
   * perfectly in a direct chat looks dead in a group. It is one account-wide setting and
   * Telegram overrides it in any group the bot administers, so `false` says the account is
   * muted where it is an ordinary member, never that some particular group is silent. Absent
   * when the channel has no such notion, or reports nothing about it: unknown must never be
   * reported as a problem.
   */
  readsGroupMessages?: boolean;
}

/**
 * What a send had to give up in order to land, as a short readable phrase. The message DID
 * arrive — a send that did not throws — so this is not a failure: it says the message is
 * somewhere less right than it was addressed to, which is otherwise invisible from the
 * outside. A channel that always delivers as addressed returns nothing at all; Telegram is
 * the one that reports, a forum topic deleted under a live conversation sending the reply to
 * General instead.
 */
export type MessagingSendNote = string;

/** One file on its way out to a chat: the bytes, plus the name the chat should show. */
export interface MessagingOutboundFile {
  /** Display name — the base name of the Workspace-relative path the reply mentioned. */
  fileName: string;
  data: Buffer;
}

/** How one outbound text should be rendered. Absent throughout means plain text. */
export interface MessagingSendOptions {
  /**
   * Read the text as Markdown and render it in whatever this channel's markup is.
   *
   * A REQUEST, not an instruction: the connector owns both what its channel can show and
   * what to do when the channel refuses the rendered form, and it must fall back to sending
   * this same text plainly rather than let a formatting failure cost the message. What
   * survives the conversion differs per channel and is documented at each renderer
   * (telegram-html.ts, feishu-card.ts, qq-markdown.ts).
   *
   * Only a relayed assistant message ever sets it. The fixed notices and the test message
   * carry no markup and are sent as they are written, so a bug in a renderer can never
   * reach the one message a user sends to check whether the binding works at all.
   */
  markdown?: boolean;
}

/** Outbound half of one bound account. Every method throws on failure with a readable reason. */
export interface MessagingClient {
  /** Credential check (used by the test endpoint); resolving means the config signs in. */
  checkCredentials(): Promise<MessagingAccountInfo | null>;
  /** Sends a text message into a chat by chat id; resolves a MessagingSendNote when it degraded. */
  sendText(
    chatId: string,
    text: string,
    opts?: MessagingSendOptions,
  ): Promise<MessagingSendNote | void>;
  /** Replies a text message to a specific inbound message (threads correctly in group chats). */
  replyText(
    messageId: string,
    text: string,
    opts?: MessagingSendOptions,
  ): Promise<MessagingSendNote | void>;
  /**
   * Sends a picture into a chat, so a chart the Agent drew arrives as something the reader
   * can see rather than as a download. Channels that need an upload step first do it here —
   * the bridge holds bytes and a name, never a channel's file handle.
   */
  sendImage(chatId: string, file: MessagingOutboundFile): Promise<void>;
  /** Sends any other file into a chat as an attachment. */
  sendFile(chatId: string, file: MessagingOutboundFile): Promise<void>;
}

export interface MessagingChannelConnector {
  readonly channel: MessagingChannel;
  /**
   * How many outbound messages this channel will accept in answer to ONE inbound message,
   * or undefined where no such limit exists (Feishu and Telegram both send freely).
   *
   * A channel that declares one enforces it itself — the connector is the only place that
   * knows what the platform rejects and how to combine messages so nothing is lost. What
   * the bridge does with the number is narrower: it caps the one-message-per-line split at
   * it, because that option's own ceiling is sized for a channel with no such budget and
   * would otherwise ask for more messages than the channel can ever deliver.
   */
  readonly replyBudget?: number;
  /** Builds the outbound client for one stored config (throws on a malformed document). */
  createClient(config: Record<string, unknown>): Promise<MessagingClient>;
  /**
   * Opens the inbound event stream for one stored config. Resolves as soon as the
   * connection is constructed and connecting — lifecycle arrives via the handlers
   * (`onReady` / `onError`), because channels reconnect on their own and a single promise
   * cannot carry a lifecycle.
   */
  connect(
    config: Record<string, unknown>,
    handlers: MessagingConnectorHandlers,
  ): Promise<MessagingConnection>;
}