A local-first multi-agent app development platform, built on PenguinHarness
/**
* 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);
}