Skip to content

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

8.1 KB
Raw Blame
/**
 * The media questions every messaging channel has to answer the same way: which files the
 * chat should render as a picture rather than offer as an attachment, what MIME type a
 * downloaded image's bytes carry, and how to read a download without letting the remote
 * side decide how much memory it may use.
 *
 * It sits beside the connectors instead of inside one because the answers must not differ
 * per channel: a `.png` the Agent wrote has to arrive as a picture in Feishu AND in
 * Telegram, or the same reply reads differently depending on where it landed. The
 * connectors keep only what is genuinely channel-shaped (which endpoint, which field
 * name); the classification lives here.
 */

/**
 * The extensions sent as an image, mapped to the MIME type that names them.
 *
 * Deliberately the intersection of what both channels' image endpoints accept and both
 * clients render inline — Feishu's upload also takes BMP/ICO/TIFF/HEIC and Telegram's
 * `sendPhoto` re-encodes what it is given, but a set that holds on one channel and not the
 * other would make the same reply look different in two chats. SVG is excluded on purpose:
 * neither channel renders it as a picture, and it is a scriptable document (see
 * WorkspaceFileContent.scriptable) — it travels as a file attachment instead.
 */
const IMAGE_MIME_BY_EXT: Readonly<Record<string, string>> = {
  png: "image/png",
  jpg: "image/jpeg",
  jpeg: "image/jpeg",
  gif: "image/gif",
  webp: "image/webp",
};

/** The MIME type implied by a file name's extension, or null when it is not one of the image kinds. */
export function imageMimeOfName(name: string): string | null {
  const dot = name.lastIndexOf(".");
  if (dot < 0) return null;
  return IMAGE_MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? null;
}

/** Whether a file name should be sent as a picture (see IMAGE_MIME_BY_EXT for the set and why). */
export function isImageFileName(name: string): boolean {
  return imageMimeOfName(name) !== null;
}

/**
 * The image type the bytes themselves declare, or null for anything unrecognized.
 *
 * An inbound download names its type unreliably — Feishu's resource endpoint answers with
 * whatever content type the sender's upload carried, and a channel that answers
 * `application/octet-stream` would otherwise produce a data URL no provider accepts. The
 * magic bytes are the one source that cannot be wrong, so they win where they are
 * conclusive and the header stays the fallback.
 */
export function sniffImageMime(bytes: Uint8Array): string | null {
  const at = (i: number): number => bytes[i] ?? -1;
  if (at(0) === 0x89 && at(1) === 0x50 && at(2) === 0x4e && at(3) === 0x47) return "image/png";
  if (at(0) === 0xff && at(1) === 0xd8 && at(2) === 0xff) return "image/jpeg";
  if (at(0) === 0x47 && at(1) === 0x49 && at(2) === 0x46) return "image/gif";
  // RIFF....WEBP — the four-byte size field between the two tags is not part of the tag.
  if (
    at(0) === 0x52 &&
    at(1) === 0x49 &&
    at(2) === 0x46 &&
    at(3) === 0x46 &&
    at(8) === 0x57 &&
    at(9) === 0x45 &&
    at(10) === 0x42 &&
    at(11) === 0x50
  ) {
    return "image/webp";
  }
  return null;
}

/**
 * A transfer refused for its size, as opposed to one that failed.
 *
 * The distinction exists because the two have nothing in common but the outcome, and the
 * user's next move differs: a size refusal is theirs to fix by sending something smaller,
 * while a failure is a fault somewhere else — a permission the bot was never granted, a
 * network blip — that no amount of resending will clear. A notice that covers both says
 * neither, which is how a real permission error was first reported to us as "the image is
 * too large or the download failed".
 */
export class MessagingMediaTooLargeError extends Error {
  /**
   * The ceiling that actually refused this transfer, which is not necessarily the one the
   * caller asked for: a connector may narrow it further because its own platform does (the
   * Bot API serves a bot no file over 20MB, whatever the server would accept). The notice
   * has to name the number that bit, or it sends the user to shrink a file against a limit
   * that was never the one in the way.
   */
  readonly maxBytes: number;

  constructor(what: string, maxBytes: number) {
    super(`${what} is larger than the ${Math.floor(maxBytes / (1024 * 1024))}MB limit`);
    this.name = "MessagingMediaTooLargeError";
    this.maxBytes = maxBytes;
  }
}

/**
 * A transfer the channel refused because the bot's own app lacks a permission.
 *
 * Its own class because it is the one transfer failure the person in the chat can fix, and
 * only if they are told what to grant and where: "Request failed with status code 403" sends
 * them to a log, while the scope name and the console link are ten seconds of work. Feishu
 * hands both back in its refusal (`code` 99991672) — see the connector's scopeDenialDetail.
 *
 * `scopes` is what the channel said would satisfy the call (any ONE of them, in Feishu's
 * wording); `grantUrl` is the channel's own console link, or null when the refusal carried
 * none. Nothing else off the channel's error travels with it: the raw SDK error carries the
 * request config, and that is where credentials live.
 */
export class MessagingPermissionError extends Error {
  constructor(
    readonly scopes: readonly string[],
    readonly grantUrl: string | null,
    message: string,
  ) {
    super(message);
    this.name = "MessagingPermissionError";
  }
}

/**
 * A transfer the channel cannot carry at all — a permanent shape of the platform, not a fault.
 *
 * Its own class because it is the one failure here that nothing will ever clear: no permission
 * to grant, no smaller file to send, no retry that behaves differently. QQ's outbound media is
 * the case it exists for — the platform's rich-media path registers bytes against a PUBLICLY
 * REACHABLE https URL, which is the same requirement that ruled webhook mode out, and this
 * server has no such address to offer.
 *
 * It matters beyond the wording: `error-kind.ts` files it as `expected`, so a channel refusing
 * what it was never able to do stops being counted among the errors that need someone to look.
 * `message` must say what could not be carried and why, because that text is what the error
 * record says about it.
 */
export class MessagingUnsupportedError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "MessagingUnsupportedError";
  }
}

/**
 * A file a reply mentioned that the bridge held back at one of its OWN outbound caps — the
 * per-file byte ceiling or the per-reply count — rather than one the channel refused.
 *
 * Its own class so `error-kind.ts` can file it as `expected` by type at the two capture points
 * that record it (`messaging_file_too_large`, `messaging_files_skipped`): the caps are known
 * limits, nothing is broken, and the Web App still has every file. `message` must name the
 * files (or how many), the channel and the cap, because that text is the whole of what the
 * error record says — none of it is posted into the chat.
 */
export class MessagingOutboundCapError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "MessagingOutboundCapError";
  }
}

/**
 * Reads a download into memory, refusing at the byte that crosses `maxBytes`.
 *
 * Buffering `await res.arrayBuffer()` and checking the length afterwards would be a
 * remote-controlled allocation: a declared size is a claim, and both channels can serve
 * far more than this server wants to hold (Feishu's resource endpoint goes to 100MB). The
 * count is kept over the chunks actually received, so a lying `content-length` — or none
 * at all — buys nothing.
 *
 * `what` names the transfer in the error message; it must never carry a URL, since
 * Telegram's file endpoint embeds the bot token in one.
 */
export async function collectUnderCap(
  chunks: AsyncIterable<Uint8Array>,
  maxBytes: number,
  what: string,
): Promise<Buffer> {
  const parts: Uint8Array[] = [];
  let total = 0;
  for await (const chunk of chunks) {
    total += chunk.byteLength;
    if (total > maxBytes) throw new MessagingMediaTooLargeError(what, maxBytes);
    parts.push(chunk);
  }
  return Buffer.concat(parts);
}