@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/telegram.js

@@ -0,0 +1,1045 @@
+import { chmod, mkdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import {
+  CONVERSATION_FILE_TRANSFER_TIMEOUT_MS,
+  KIT_CONTRACT_VERSION,
+  ORIGINAL_UUID,
+  PERSONAL_BOT_DISCONNECT_RELATIVE_PATH,
+  PERSONAL_BOT_OFFSET_RELATIVE_PATH,
+  PERSONAL_BOT_TOKEN_RELATIVE_PATH,
+  TELEGRAM_BOT_API_TIMEOUT_MS,
+  TELEGRAM_CONTROL_KEYBOARD_COMMANDS,
+  TELEGRAM_DELIVERY_BATCH_MAX,
+  TELEGRAM_DELIVERY_KINDS,
+  TELEGRAM_DOWNLOAD_CEILING_BYTES,
+  TELEGRAM_GATEWAY_POLL_MS,
+  TELEGRAM_IMAGE_UPLOAD_CEILING_BYTES,
+  TELEGRAM_INGRESS_BATCH_MAX,
+  TELEGRAM_MEDIA_KINDS,
+  TELEGRAM_UNSUPPORTED_MEDIA_FIELDS,
+  TELEGRAM_UPDATE_OUTCOMES,
+  telegramApiUrl,
+  telegramFileUrl,
+} from "./contract.js";
+import { heldControl, houseRequest, maintainControl, openSession } from "./house.js";
+import { KitRefusal } from "./refusal.js";
+import { writeText } from "./state.js";
+
+const TOKEN_PROMPT = "Paste the BotFather token for this Environment: ";
+const AMBIGUOUS_DELIVERY = Object.freeze({ telegram_message_id: null, telegram_topic_id: null });
+const DELIVERY_KINDS = new Set(TELEGRAM_DELIVERY_KINDS);
+
+function plain(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function identifier(value) {
+  return typeof value === "number" || typeof value === "string";
+}
+
+function asId(value) {
+  return String(value);
+}
+
+function cancelled(error) {
+  return error instanceof KitRefusal && error.code === "kit_command_cancelled";
+}
+
+function telegramFile(value) {
+  if (!plain(value)) return null;
+  if (typeof value.file_id !== "string" || value.file_id.length === 0) return null;
+  if (typeof value.file_unique_id !== "string" || value.file_unique_id.length === 0) return null;
+  if (value.file_name !== undefined && typeof value.file_name !== "string") return null;
+  if (value.mime_type !== undefined && typeof value.mime_type !== "string") return null;
+  if (value.file_size !== undefined && (!Number.isSafeInteger(value.file_size) || value.file_size < 0)) {
+    return null;
+  }
+  if (value.width !== undefined && typeof value.width !== "number") return null;
+  if (value.height !== undefined && typeof value.height !== "number") return null;
+  return value;
+}
+
+function telegramPhoto(value) {
+  const file = telegramFile(value);
+  if (file === null) return null;
+  if (!Number.isSafeInteger(file.width) || file.width < 1 || file.width > 1_000_000) return null;
+  if (!Number.isSafeInteger(file.height) || file.height < 1 || file.height > 1_000_000) return null;
+  return file;
+}
+
+function telegramUser(value) {
+  if (!plain(value) || !identifier(value.id)) return null;
+  if (value.is_bot !== undefined && typeof value.is_bot !== "boolean") return null;
+  if (value.username !== undefined && typeof value.username !== "string") return null;
+  if (value.has_topics_enabled !== undefined && typeof value.has_topics_enabled !== "boolean") {
+    return null;
+  }
+  return value;
+}
+
+function telegramMessage(value) {
+  if (!plain(value) || !identifier(value.message_id)) return null;
+  if (!plain(value.chat) || !identifier(value.chat.id) || typeof value.chat.type !== "string") return null;
+  if (value.from !== undefined && telegramUser(value.from) === null) return null;
+  if (value.text !== undefined && typeof value.text !== "string") return null;
+  if (value.caption !== undefined && typeof value.caption !== "string") return null;
+  if (value.message_thread_id !== undefined && !identifier(value.message_thread_id)) return null;
+  for (const kind of TELEGRAM_MEDIA_KINDS) {
+    if (kind === "photo" || value[kind] === undefined) continue;
+    if (telegramFile(value[kind]) === null) return null;
+  }
+  if (value.photo !== undefined) {
+    if (!Array.isArray(value.photo) || value.photo.some((one) => telegramPhoto(one) === null)) return null;
+  }
+  return value;
+}
+
+function telegramCallback(value) {
+  if (!plain(value) || !identifier(value.id) || telegramUser(value.from) === null) return null;
+  if (value.data !== undefined && typeof value.data !== "string") return null;
+  if (value.message !== undefined && telegramMessage(value.message) === null) return null;
+  return value;
+}
+
+export function parseTelegramBotIdentity(value) {
+  if (!plain(value) || !identifier(value.id) || value.is_bot !== true) return null;
+  if (typeof value.username !== "string" || value.username.length === 0) return null;
+  return {
+    telegramBotUserId: asId(value.id),
+    botUsername: value.username,
+    hasTopicsEnabled: value.has_topics_enabled === true,
+  };
+}
+
+function attachmentOf(kind, value) {
+  const file = kind === "photo" ? telegramPhoto(value) : telegramFile(value);
+  if (file === null) return null;
+  return {
+    file_id: file.file_id,
+    file_unique_id: file.file_unique_id,
+    media_kind: kind,
+    original_name: file.file_name ?? null,
+    media_type: file.mime_type ?? null,
+    byte_size: file.file_size ?? null,
+    ...(kind === "photo" ? { dimensions: { width: file.width, height: file.height } } : {}),
+  };
+}
+
+function largestPhoto(photos) {
+  if (!Array.isArray(photos) || photos.length === 0) return null;
+  const chosen = photos.reduce((best, candidate) =>
+    (candidate.file_size ?? 0) > (best.file_size ?? 0) ? candidate : best,
+  );
+  return attachmentOf("photo", { ...chosen, mime_type: chosen.mime_type ?? "image/jpeg" });
+}
+
+function mediaOf(message) {
+  if (message === undefined) return { caption: null, attachments: [], unsupported: false };
+  const attachments = [];
+  const photo = largestPhoto(message.photo);
+  if (photo !== null) attachments.push(photo);
+  for (const kind of TELEGRAM_MEDIA_KINDS) {
+    if (kind === "photo") continue;
+    const attachment = attachmentOf(kind, message[kind]);
+    if (attachment !== null) attachments.push(attachment);
+  }
+  return {
+    caption: message.caption ?? null,
+    attachments,
+    unsupported: TELEGRAM_UNSUPPORTED_MEDIA_FIELDS.some((field) => message[field] !== undefined),
+  };
+}
+
+function updateKind(input) {
+  if (input.chatType !== "private" || input.fromIsBot) return "foreign";
+  if (input.callback) return "callback";
+  if (input.edited) return "edited_message";
+  if (input.text !== null && TELEGRAM_CONTROL_KEYBOARD_COMMANDS.includes(input.text)) return "control";
+  return "ordinary_message";
+}
+
+export function normalizeTelegramUpdate(telegramBotUserId, value) {
+  if (!plain(value) || !identifier(value.update_id)) return null;
+  const callback = value.callback_query === undefined ? undefined : telegramCallback(value.callback_query);
+  const edited = value.edited_message === undefined ? undefined : telegramMessage(value.edited_message);
+  const posted = value.message === undefined ? undefined : telegramMessage(value.message);
+  if (callback === null || edited === null || posted === null) return null;
+  const message = callback?.message ?? edited ?? posted;
+  if (message === undefined && callback === undefined) return null;
+  const from = callback?.from ?? message?.from;
+  if (from === undefined) return null;
+  const chat = message?.chat;
+  const text = callback === undefined ? (message?.text ?? null) : null;
+  const media = callback === undefined ? mediaOf(message) : mediaOf(undefined);
+  const fromIsBot = from.is_bot === true;
+  return {
+    telegram_bot_user_id: telegramBotUserId,
+    update_id: asId(value.update_id),
+    kind: updateKind({
+      chatType: chat?.type ?? "private",
+      fromIsBot,
+      text,
+      callback: callback !== undefined,
+      edited: edited !== undefined,
+    }),
+    chat_id: chat === undefined ? asId(from.id) : asId(chat.id),
+    topic_id: message?.message_thread_id === undefined ? null : asId(message.message_thread_id),
+    from_telegram_user_id: asId(from.id),
+    from_is_bot: fromIsBot,
+    message_id: message === undefined ? null : asId(message.message_id),
+    text,
+    caption: media.caption,
+    attachments: media.attachments,
+    unsupported_media: media.unsupported,
+    callback_correlation: callback?.data ?? null,
+  };
+}
+
+export function telegramRetryAfter(answered) {
+  if (!plain(answered) || answered.ok !== false || !plain(answered.parameters)) return null;
+  const retryAfter = answered.parameters.retry_after;
+  if (!Number.isSafeInteger(retryAfter) || retryAfter <= 0) return null;
+  return retryAfter;
+}
+
+function botApiAccepted(answered) {
+  return plain(answered) && answered.ok === true;
+}
+
+function botApiRefused(answered) {
+  return plain(answered) && answered.ok === false;
+}
+
+function inlineKeyboard(delivery) {
+  return {
+    inline_keyboard: delivery.options.map((option) => [
+      { text: option.label, callback_data: option.correlation },
+    ]),
+  };
+}
+
+function sendBody(delivery) {
+  const body = { chat_id: Number(delivery.chat_id), text: delivery.text ?? "" };
+  if (delivery.topic_id !== null) body.message_thread_id = Number(delivery.topic_id);
+  if (delivery.reply_to_message_id !== null) {
+    body.reply_to_message_id = Number(delivery.reply_to_message_id);
+  }
+  if (delivery.kind === "agent_choice") body.reply_markup = inlineKeyboard(delivery);
+  if (delivery.kind === "interaction_card" && delivery.options.length > 0) {
+    body.reply_markup = inlineKeyboard(delivery);
+  }
+  if (delivery.kind === "control_keyboard") {
+    body.reply_markup = {
+      keyboard: [TELEGRAM_CONTROL_KEYBOARD_COMMANDS.map((command) => ({ text: command }))],
+      is_persistent: true,
+      resize_keyboard: true,
+    };
+  }
+  return body;
+}
+
+export function draftCall(draft) {
+  return {
+    method: "sendRichMessageDraft",
+    body: {
+      chat_id: Number(draft.chat_id),
+      message_thread_id: Number(draft.topic_id),
+      draft_id: Number(draft.draft_id),
+      rich_message: draft.rich_message,
+    },
+  };
+}
+
+export function deliveryCall(delivery) {
+  if (delivery.kind === "conversation_topic") {
+    return {
+      method: "createForumTopic",
+      body: { chat_id: Number(delivery.chat_id), name: delivery.text ?? "" },
+    };
+  }
+  if (delivery.rich_message !== undefined && delivery.rich_message !== null) {
+    const body = { chat_id: Number(delivery.chat_id), rich_message: delivery.rich_message };
+    if (delivery.topic_id !== null) body.message_thread_id = Number(delivery.topic_id);
+    if (delivery.edit_telegram_message_id !== null) {
+      body.message_id = Number(delivery.edit_telegram_message_id);
+      return { method: "editMessageText", body };
+    }
+    return { method: "sendRichMessage", body };
+  }
+  if (delivery.edit_telegram_message_id !== null) {
+    const body = {
+      chat_id: Number(delivery.chat_id),
+      message_id: Number(delivery.edit_telegram_message_id),
+      text: delivery.text ?? "",
+    };
+    if (delivery.kind === "interaction_card" && delivery.options.length > 0) {
+      body.reply_markup = inlineKeyboard(delivery);
+    }
+    return { method: "editMessageText", body };
+  }
+  return { method: "sendMessage", body: sendBody(delivery) };
+}
+
+function acceptedDelivery(delivery, result) {
+  if (delivery.kind === "conversation_topic") {
+    const threadId = plain(result) ? result.message_thread_id : undefined;
+    if (!identifier(threadId)) return null;
+    return { telegram_message_id: null, telegram_topic_id: asId(threadId) };
+  }
+  const messageId = plain(result) ? result.message_id : undefined;
+  if (!identifier(messageId)) return null;
+  return { telegram_message_id: asId(messageId), telegram_topic_id: null };
+}
+
+export function deliveryOutcome(delivery, answered) {
+  if (botApiAccepted(answered)) {
+    const delivered = acceptedDelivery(delivery, answered.result);
+    if (delivered !== null) return { outcome: "delivered", report: delivered };
+  }
+  if (botApiRefused(answered)) return { outcome: "failed", report: AMBIGUOUS_DELIVERY };
+  return { outcome: "delivery_unknown", report: AMBIGUOUS_DELIVERY };
+}
+
+export function uploadFields(upload) {
+  const fields = { chat_id: upload.chat_id };
+  if (upload.topic_id !== null) fields.message_thread_id = upload.topic_id;
+  if (upload.caption !== null) fields.caption = upload.caption;
+  return fields;
+}
+
+export function uploadOutcome(answered) {
+  if (botApiAccepted(answered)) {
+    const messageId = plain(answered.result) ? answered.result.message_id : undefined;
+    if (identifier(messageId)) {
+      return {
+        outcome: "delivered",
+        report: { telegram_message_id: asId(messageId), reason: null },
+      };
+    }
+  }
+  if (botApiRefused(answered)) {
+    return { outcome: "failed", report: { telegram_message_id: null, reason: "send_refused" } };
+  }
+  return {
+    outcome: "delivery_unknown",
+    report: { telegram_message_id: null, reason: "provider_response_ambiguous" },
+  };
+}
+
+function refuseAnswer() {
+  throw new KitRefusal("kit_telegram_response_invalid");
+}
+
+function queuedDelivery(value) {
+  if (!plain(value) || !ORIGINAL_UUID.test(value.id)) refuseAnswer();
+  if (!DELIVERY_KINDS.has(value.kind) || typeof value.chat_id !== "string") refuseAnswer();
+  if (value.topic_id !== null && typeof value.topic_id !== "string") refuseAnswer();
+  if (value.text !== null && typeof value.text !== "string") refuseAnswer();
+  if (value.reply_to_message_id !== null && typeof value.reply_to_message_id !== "string") refuseAnswer();
+  if (value.edit_telegram_message_id !== null && typeof value.edit_telegram_message_id !== "string") {
+    refuseAnswer();
+  }
+  if (value.rich_message !== undefined && value.rich_message !== null && !plain(value.rich_message)) {
+    refuseAnswer();
+  }
+  if (!Array.isArray(value.options)) refuseAnswer();
+  for (const option of value.options) {
+    if (!plain(option) || typeof option.correlation !== "string" || typeof option.label !== "string") {
+      refuseAnswer();
+    }
+  }
+  return value;
+}
+
+function queuedDraft(value) {
+  if (!plain(value) || !plain(value.rich_message)) refuseAnswer();
+  for (const named of ["conversation_id", "turn_id", "chat_id", "topic_id", "draft_id"]) {
+    if (typeof value[named] !== "string" || value[named].length === 0) refuseAnswer();
+  }
+  return value;
+}
+
+function queuedUpload(value) {
+  if (!plain(value) || !ORIGINAL_UUID.test(value.id)) refuseAnswer();
+  if (typeof value.chat_id !== "string" || typeof value.file_name !== "string") refuseAnswer();
+  if (value.topic_id !== null && typeof value.topic_id !== "string") refuseAnswer();
+  if (value.caption !== null && typeof value.caption !== "string") refuseAnswer();
+  return value;
+}
+
+function queueOf(answer) {
+  if (!Array.isArray(answer?.queue) || answer.queue.length > TELEGRAM_DELIVERY_BATCH_MAX) refuseAnswer();
+  return answer.queue.map((item) => {
+    if (!plain(item)) refuseAnswer();
+    if (item.type === "message") return { type: "message", delivery: queuedDelivery(item.delivery) };
+    if (item.type === "draft") return { type: "draft", draft: queuedDraft(item.draft) };
+    if (item.type !== "file") refuseAnswer();
+    return { type: "file", upload: queuedUpload(item.upload) };
+  });
+}
+
+function fetchesOf(answer) {
+  if (!Array.isArray(answer?.fetches) || answer.fetches.length > TELEGRAM_DELIVERY_BATCH_MAX) {
+    refuseAnswer();
+  }
+  for (const pending of answer.fetches) {
+    if (!plain(pending) || !ORIGINAL_UUID.test(pending.id)) refuseAnswer();
+    if (typeof pending.file_id !== "string" || pending.file_id.length === 0) refuseAnswer();
+    if (pending.byte_size !== null && (!Number.isSafeInteger(pending.byte_size) || pending.byte_size < 0)) {
+      refuseAnswer();
+    }
+  }
+  return answer.fetches;
+}
+
+function submissionOf(answer) {
+  if (!plain(answer) || !TELEGRAM_UPDATE_OUTCOMES.includes(answer.outcome)) refuseAnswer();
+  return answer.outcome;
+}
+
+function abandonedOf(answer) {
+  if (!plain(answer) || !Number.isSafeInteger(answer.abandoned) || answer.abandoned < 0) refuseAnswer();
+  return answer.abandoned;
+}
+
+function updatesOf(result) {
+  if (!Array.isArray(result)) throw new KitRefusal("telegram_get_updates_invalid");
+  return result;
+}
+
+function telegramFileLocation(result) {
+  if (!plain(result) || typeof result.file_id !== "string" || result.file_id.length === 0) {
+    throw new KitRefusal("telegram_get_file_invalid");
+  }
+  if (typeof result.file_path !== "string" || result.file_path.length === 0) {
+    throw new KitRefusal("telegram_get_file_invalid");
+  }
+  return result;
+}
+
+function tokenPath(directory) {
+  return join(directory, PERSONAL_BOT_TOKEN_RELATIVE_PATH);
+}
+
+function offsetPath(directory) {
+  return join(directory, PERSONAL_BOT_OFFSET_RELATIVE_PATH);
+}
+
+function disconnectPath(directory) {
+  return join(directory, PERSONAL_BOT_DISCONNECT_RELATIVE_PATH);
+}
+
+async function writeOwned(path, contents, signal) {
+  const parent = join(path, "..");
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  await chmod(parent, 0o700);
+  await writeText(path, contents, signal);
+}
+
+async function readSecret(directory) {
+  let stored;
+  try {
+    stored = (await readFile(tokenPath(directory), "utf8")).trim();
+  } catch {
+    throw new KitRefusal("telegram_bot_token_required");
+  }
+  if (stored.length === 0) throw new KitRefusal("telegram_bot_token_required");
+  return stored;
+}
+
+async function disconnecting(directory) {
+  return readFile(disconnectPath(directory)).then(
+    () => true,
+    () => false,
+  );
+}
+
+async function readOffset(directory) {
+  let stored;
+  try {
+    stored = await readFile(offsetPath(directory), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return 0;
+    throw new KitRefusal("telegram_offset_unreadable");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stored);
+  } catch {
+    throw new KitRefusal("telegram_offset_unreadable");
+  }
+  if (!plain(parsed) || !Number.isSafeInteger(parsed.offset) || parsed.offset < 0) {
+    throw new KitRefusal("telegram_offset_unreadable");
+  }
+  return parsed.offset;
+}
+
+async function writeOffset(directory, offset, signal) {
+  await writeOwned(offsetPath(directory), `${JSON.stringify({ offset })}\n`, signal);
+}
+
+function boundedSignal(gateway, timeoutMs) {
+  const signals = [AbortSignal.timeout(timeoutMs)];
+  if (gateway.signal !== undefined) signals.push(gateway.signal);
+  return AbortSignal.any(signals);
+}
+
+function transportRefusal(gateway, code, detail = null) {
+  if (gateway.signal?.aborted === true) return new KitRefusal("kit_command_cancelled");
+  return new KitRefusal(code, detail);
+}
+
+async function telegramPost(gateway, url, body) {
+  const fetcher = gateway.dependencies.fetch ?? fetch;
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: "POST",
+      redirect: "error",
+      signal: boundedSignal(gateway, TELEGRAM_BOT_API_TIMEOUT_MS),
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch {
+    throw transportRefusal(gateway, "telegram_bot_api_invalid");
+  }
+  return response.json().catch(() => null);
+}
+
+async function telegramUpload(gateway, url, fields, file) {
+  const fetcher = gateway.dependencies.fetch ?? fetch;
+  const form = new FormData();
+  for (const [name, value] of Object.entries(fields)) form.append(name, value);
+  form.append(file.field, new Blob([file.bytes]), file.name);
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: "POST",
+      redirect: "error",
+      signal: boundedSignal(gateway, CONVERSATION_FILE_TRANSFER_TIMEOUT_MS),
+      body: form,
+    });
+  } catch {
+    throw transportRefusal(gateway, "telegram_bot_api_invalid");
+  }
+  return response.json().catch(() => null);
+}
+
+async function telegramCall(gateway, token, method, body = {}) {
+  const answered = await telegramPost(gateway, telegramApiUrl(token, method), body);
+  const retryAfter = telegramRetryAfter(answered);
+  if (retryAfter !== null) {
+    gateway.gate.hold(retryAfter);
+    throw new KitRefusal("telegram_bot_rate_limited");
+  }
+  if (!botApiAccepted(answered)) throw new KitRefusal("telegram_bot_api_invalid");
+  return answered.result;
+}
+
+async function downloadTelegramFile(gateway, url) {
+  const fetcher = gateway.dependencies.fetch ?? fetch;
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: "GET",
+      redirect: "error",
+      signal: boundedSignal(gateway, CONVERSATION_FILE_TRANSFER_TIMEOUT_MS),
+    });
+  } catch {
+    throw transportRefusal(gateway, "telegram_get_file_invalid");
+  }
+  if (!response.ok || response.body === null) {
+    await response.body?.cancel();
+    throw new KitRefusal("telegram_get_file_invalid");
+  }
+  const bytes = await readCapped(response, TELEGRAM_DOWNLOAD_CEILING_BYTES);
+  if (bytes.length > TELEGRAM_DOWNLOAD_CEILING_BYTES) {
+    throw new KitRefusal("telegram_inbound_too_large");
+  }
+  return bytes;
+}
+
+async function readCapped(response, ceiling) {
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      chunks.push(chunk.value);
+      if (size > ceiling) break;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function houseCall(gateway, path, body = {}) {
+  return heldControl(gateway.session, gateway.signal).then((authorization) =>
+    houseRequest(
+      gateway.session.house,
+      authorization,
+      `/kit/telegram/${path}`,
+      body,
+      gateway.dependencies,
+      gateway.signal,
+    ),
+  );
+}
+
+async function pushInboundBytes(gateway, id, bytes) {
+  const signal = boundedSignal(gateway, CONVERSATION_FILE_TRANSFER_TIMEOUT_MS);
+  const authorization = await heldControl(gateway.session, signal);
+  const fetcher = gateway.dependencies.fetch ?? fetch;
+  let response;
+  try {
+    response = await fetcher(`${gateway.session.house}/kit/telegram/inbound/${id}/bytes`, {
+      method: "POST",
+      redirect: "error",
+      signal,
+      headers: {
+        authorization,
+        "content-type": "application/octet-stream",
+        "x-house-kit-version": KIT_CONTRACT_VERSION,
+      },
+      body: bytes,
+    });
+  } catch {
+    throw transportRefusal(gateway, "kit_inbound_unavailable", id);
+  }
+  const answer = await response.json().catch(() => null);
+  if (!response.ok || answer?.ok !== true) throw new KitRefusal("kit_inbound_unavailable", id);
+}
+
+async function pullOutboundBytes(gateway, upload) {
+  const signal = boundedSignal(gateway, CONVERSATION_FILE_TRANSFER_TIMEOUT_MS);
+  const authorization = await heldControl(gateway.session, signal);
+  const fetcher = gateway.dependencies.fetch ?? fetch;
+  let response;
+  try {
+    response = await fetcher(`${gateway.session.house}/kit/telegram/outbound/${upload.id}/stream`, {
+      method: "POST",
+      redirect: "error",
+      signal,
+      headers: {
+        authorization,
+        "content-type": "application/json",
+        "x-house-kit-version": KIT_CONTRACT_VERSION,
+      },
+      body: "{}",
+    });
+  } catch {
+    throw transportRefusal(gateway, "kit_outbound_unavailable", upload.id);
+  }
+  if (!response.ok || response.body === null) {
+    await response.body?.cancel();
+    throw new KitRefusal("kit_outbound_unavailable", upload.id);
+  }
+  return readCapped(response, TELEGRAM_IMAGE_UPLOAD_CEILING_BYTES);
+}
+
+function rateGate(now) {
+  let until = 0;
+  return {
+    open: () => now() < until,
+    hold: (retryAfter) => {
+      until = Math.max(until, now() + retryAfter * 1000);
+    },
+  };
+}
+
+function pause(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted === true) {
+      reject(new KitRefusal("kit_command_cancelled"));
+      return;
+    }
+    const timer = setTimeout(finish, milliseconds);
+    function finish() {
+      signal?.removeEventListener("abort", cancel);
+      resolve();
+    }
+    function cancel() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", cancel);
+      reject(new KitRefusal("kit_command_cancelled"));
+    }
+    signal?.addEventListener("abort", cancel, { once: true });
+  });
+}
+
+async function gatewayToken(gateway) {
+  if (await disconnecting(gateway.directory)) throw new KitRefusal("telegram_bot_disconnecting");
+  return readSecret(gateway.directory);
+}
+
+async function submitUpdates(gateway) {
+  if (gateway.gate.open()) return;
+  const token = await gatewayToken(gateway);
+  const identity = parseTelegramBotIdentity(await telegramCall(gateway, token, "getMe"));
+  if (identity === null) throw new KitRefusal("telegram_bot_identity_invalid");
+  const offset = await readOffset(gateway.directory);
+  const updates = updatesOf(
+    await telegramCall(gateway, token, "getUpdates", {
+      offset,
+      limit: TELEGRAM_INGRESS_BATCH_MAX,
+      timeout: 0,
+      allowed_updates: ["message", "callback_query"],
+    }),
+  );
+  for (const update of updates) {
+    const event = normalizeTelegramUpdate(identity.telegramBotUserId, update);
+    if (event === null) throw new KitRefusal("telegram_update_invalid");
+    const outcome = submissionOf(await houseCall(gateway, "updates", event));
+    await writeOffset(gateway.directory, Number(event.update_id) + 1, gateway.signal);
+    gateway.summary.submitted.push({ update: event.update_id, kind: event.kind, outcome });
+  }
+}
+
+async function relayInboundFiles(gateway) {
+  if (gateway.gate.open()) return;
+  const token = await gatewayToken(gateway);
+  const pending = fetchesOf(
+    await houseCall(gateway, "inbound/fetches/acquire", { max: TELEGRAM_DELIVERY_BATCH_MAX }),
+  );
+  for (const file of pending) {
+    if (gateway.gate.open()) return;
+    try {
+      if (file.byte_size !== null && file.byte_size > TELEGRAM_DOWNLOAD_CEILING_BYTES) {
+        throw new KitRefusal("telegram_inbound_too_large");
+      }
+      const located = telegramFileLocation(
+        await telegramCall(gateway, token, "getFile", { file_id: file.file_id }),
+      );
+      const bytes = await downloadTelegramFile(gateway, telegramFileUrl(token, located.file_path));
+      await pushInboundBytes(gateway, file.id, bytes);
+      gateway.summary.relayed.push({ attachment: file.id, bytes: bytes.length });
+    } catch (error) {
+      if (cancelled(error) || !(error instanceof KitRefusal)) throw error;
+      gateway.summary.failures.push({ activity: "inbound", item: file.id, code: error.code });
+    }
+  }
+}
+
+async function reportDelivery(gateway, delivery, settled) {
+  await houseCall(gateway, `deliveries/${delivery.id}/outcome`, {
+    outcome: settled.outcome,
+    telegram_message_id: settled.report.telegram_message_id,
+    telegram_topic_id: settled.report.telegram_topic_id,
+  });
+  gateway.summary.deliveries.push({ delivery: delivery.id, outcome: settled.outcome });
+}
+
+async function reportUpload(gateway, upload, settled) {
+  await houseCall(gateway, `outbound/${upload.id}/outcome`, {
+    outcome: settled.outcome,
+    telegram_message_id: settled.report.telegram_message_id,
+    reason: settled.report.reason,
+  });
+  gateway.summary.uploads.push({
+    upload: upload.id,
+    outcome: settled.outcome,
+    reason: settled.report.reason,
+  });
+}
+
+async function sendQueuedMessage(gateway, token, delivery) {
+  await houseCall(gateway, `deliveries/${delivery.id}/attempt`);
+  const call = deliveryCall(delivery);
+  let answered;
+  try {
+    answered = await telegramPost(gateway, telegramApiUrl(token, call.method), call.body);
+  } catch (error) {
+    if (cancelled(error)) throw error;
+    await reportDelivery(gateway, delivery, {
+      outcome: "delivery_unknown",
+      report: AMBIGUOUS_DELIVERY,
+    });
+    return false;
+  }
+  await reportDelivery(gateway, delivery, deliveryOutcome(delivery, answered));
+  const retryAfter = telegramRetryAfter(answered);
+  if (retryAfter === null) return false;
+  gateway.gate.hold(retryAfter);
+  return true;
+}
+
+async function sendQueuedUpload(gateway, token, upload) {
+  let bytes;
+  try {
+    bytes = await pullOutboundBytes(gateway, upload);
+  } catch (error) {
+    if (cancelled(error)) throw error;
+    await reportUpload(gateway, upload, {
+      outcome: "failed",
+      report: { telegram_message_id: null, reason: "transfer_failed" },
+    });
+    return false;
+  }
+  if (bytes.length > TELEGRAM_IMAGE_UPLOAD_CEILING_BYTES) {
+    await reportUpload(gateway, upload, {
+      outcome: "failed",
+      report: { telegram_message_id: null, reason: "file_too_large" },
+    });
+    return false;
+  }
+  let answered;
+  try {
+    answered = await telegramUpload(
+      gateway,
+      telegramApiUrl(token, "sendPhoto"),
+      uploadFields(upload),
+      { field: "photo", name: upload.file_name, bytes },
+    );
+  } catch (error) {
+    if (cancelled(error)) throw error;
+    await reportUpload(gateway, upload, {
+      outcome: "delivery_unknown",
+      report: { telegram_message_id: null, reason: "provider_response_ambiguous" },
+    });
+    return false;
+  }
+  await reportUpload(gateway, upload, uploadOutcome(answered));
+  const retryAfter = telegramRetryAfter(answered);
+  if (retryAfter === null) return false;
+  gateway.gate.hold(retryAfter);
+  return true;
+}
+
+export async function streamDrafts(drafts, gate, post) {
+  for (const draft of drafts) {
+    if (gate.open()) return;
+    const call = draftCall(draft);
+    let answered;
+    try {
+      answered = await post(call);
+    } catch (error) {
+      if (cancelled(error)) throw error;
+      return;
+    }
+    const retryAfter = telegramRetryAfter(answered);
+    if (retryAfter !== null) {
+      gate.hold(retryAfter);
+      return;
+    }
+  }
+}
+
+async function streamQueuedDrafts(gateway, token, drafts) {
+  if (gateway.gate.open()) return;
+  await streamDrafts(drafts, gateway.gate, (call) =>
+    telegramPost(gateway, telegramApiUrl(token, call.method), call.body),
+  );
+}
+
+async function drainOutboundQueue(gateway) {
+  if (gateway.gate.open()) return;
+  const token = await gatewayToken(gateway);
+  const queue = queueOf(
+    await houseCall(gateway, "queue/acquire", { max: TELEGRAM_DELIVERY_BATCH_MAX }),
+  );
+  const drafts = [];
+  for (const item of queue) {
+    if (item.type === "draft") {
+      drafts.push(item.draft);
+      continue;
+    }
+    const gated =
+      item.type === "file"
+        ? await sendQueuedUpload(gateway, token, item.upload)
+        : await sendQueuedMessage(gateway, token, item.delivery);
+    if (gated) return;
+  }
+  await streamQueuedDrafts(gateway, token, drafts);
+}
+
+async function onePass(gateway, activity, work) {
+  try {
+    await work(gateway);
+  } catch (error) {
+    if (cancelled(error) || !(error instanceof KitRefusal)) throw error;
+    gateway.summary.failures.push({ activity, item: null, code: error.code });
+  }
+}
+
+async function paceActivity(gateway, stopping, activity, work) {
+  try {
+    for (let index = 0; index < gateway.passes; index += 1) {
+      if (gateway.signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+      await onePass(gateway, activity, work);
+      if (index + 1 < gateway.passes) await gateway.wait(TELEGRAM_GATEWAY_POLL_MS, gateway.signal);
+    }
+  } catch (error) {
+    stopping.abort();
+    throw error;
+  }
+}
+
+async function serveActivities(gateway, stopping) {
+  const settled = await Promise.allSettled([
+    paceActivity(gateway, stopping, "ingress", submitUpdates),
+    paceActivity(gateway, stopping, "inbound", relayInboundFiles),
+    paceActivity(gateway, stopping, "outbound", drainOutboundQueue),
+  ]);
+  const failures = settled.filter((one) => one.status === "rejected").map((one) => one.reason);
+  const reported = failures.find((error) => !cancelled(error)) ?? failures[0];
+  if (reported !== undefined) throw reported;
+}
+
+function emptySummary() {
+  return {
+    abandoned: 0,
+    submitted: [],
+    relayed: [],
+    deliveries: [],
+    uploads: [],
+    failures: [],
+  };
+}
+
+async function askForToken(dependencies) {
+  const input = dependencies.input ?? process.stdin;
+  const output = dependencies.output ?? process.stderr;
+  if (input.isTTY !== true) {
+    const reader = createInterface({ input, terminal: false });
+    try {
+      output.write(TOKEN_PROMPT);
+      for await (const line of reader) return line;
+      return "";
+    } finally {
+      reader.close();
+    }
+  }
+  const hidden = new Writable({
+    write(_chunk, _encoding, written) {
+      written();
+    },
+  });
+  const reader = createInterface({ input, output: hidden, terminal: true });
+  output.write(TOKEN_PROMPT);
+  try {
+    return await new Promise((entered) => reader.question("", entered));
+  } finally {
+    reader.close();
+    output.write("\n");
+  }
+}
+
+async function proveOwner(gateway, token, telegramBotUserId) {
+  const updates = updatesOf(
+    await telegramCall(gateway, token, "getUpdates", {
+      offset: 0,
+      limit: TELEGRAM_INGRESS_BATCH_MAX,
+      timeout: 0,
+      allowed_updates: ["message"],
+    }),
+  );
+  for (const update of updates) {
+    const event = normalizeTelegramUpdate(telegramBotUserId, update);
+    if (
+      event !== null &&
+      event.kind === "ordinary_message" &&
+      !event.from_is_bot &&
+      event.topic_id === null
+    ) {
+      await writeOffset(gateway.directory, Number(event.update_id) + 1, gateway.signal);
+      return event.from_telegram_user_id;
+    }
+  }
+  throw new KitRefusal("telegram_owner_not_proven");
+}
+
+function gatewayContext(session, options, dependencies, signal, summary = emptySummary()) {
+  return {
+    session,
+    directory: options.directory,
+    dependencies,
+    signal,
+    gate: rateGate(() => session.now().getTime()),
+    wait: dependencies.wait ?? pause,
+    passes: options.passes ?? Number.POSITIVE_INFINITY,
+    summary,
+  };
+}
+
+export async function connectPersonalBot(options, dependencies = {}) {
+  const session = await openSession(options, dependencies);
+  const gateway = gatewayContext(session, options, dependencies, options.signal);
+  const ask = dependencies.prompt ?? (() => askForToken(dependencies));
+  const token = (await ask()).trim();
+  if (token.length === 0) throw new KitRefusal("telegram_bot_token_required");
+  const identity = parseTelegramBotIdentity(await telegramCall(gateway, token, "getMe"));
+  if (identity === null) throw new KitRefusal("telegram_bot_identity_invalid");
+  if (!identity.hasTopicsEnabled) throw new KitRefusal("telegram_threaded_mode_required");
+  await houseCall(gateway, "personal-bot/preflight", {
+    telegram_bot_user_id: identity.telegramBotUserId,
+    bot_username: identity.botUsername,
+    has_topics_enabled: true,
+  });
+  await telegramCall(gateway, token, "deleteWebhook", { drop_pending_updates: false });
+  const setup = {
+    telegram_bot_user_id: identity.telegramBotUserId,
+    bot_username: identity.botUsername,
+    owner_telegram_user_id: await proveOwner(gateway, token, identity.telegramBotUserId),
+    has_topics_enabled: true,
+  };
+  await writeOwned(tokenPath(options.directory), `${token}\n`, options.signal);
+  try {
+    await houseCall(gateway, "personal-bot", setup);
+  } catch (error) {
+    await rm(tokenPath(options.directory), { force: true });
+    throw error;
+  }
+  return setup;
+}
+
+export async function disconnectPersonalBot(options, dependencies = {}) {
+  const session = await openSession(options, dependencies);
+  const gateway = gatewayContext(session, options, dependencies, options.signal);
+  const directory = options.directory;
+  const marked = await disconnecting(directory);
+  let token = null;
+  try {
+    token = await readSecret(directory);
+  } catch (error) {
+    if (!marked) throw error;
+  }
+  if (!marked) await writeOwned(disconnectPath(directory), "{}\n", options.signal);
+  if (token !== null) {
+    await telegramCall(gateway, token, "deleteWebhook", { drop_pending_updates: false });
+    await Promise.all([
+      rm(tokenPath(directory), { force: true }),
+      rm(offsetPath(directory), { force: true }),
+    ]);
+  }
+  await houseCall(gateway, "personal-bot/disconnect");
+  await rm(disconnectPath(directory), { force: true });
+  return { revoked: token !== null, resumed: marked };
+}
+
+export async function serveTelegramGateway(options, dependencies = {}) {
+  const session = await openSession(options, dependencies);
+  const summary = emptySummary();
+  try {
+    await maintainControl(
+      session,
+      async (signal) => {
+        const stopping = new AbortController();
+        const shared = AbortSignal.any([signal, stopping.signal]);
+        const gateway = gatewayContext(session, options, dependencies, shared, summary);
+        summary.abandoned = abandonedOf(await houseCall(gateway, "deliveries/abandoned"));
+        await serveActivities(gateway, stopping);
+      },
+      options.signal,
+    );
+  } catch (error) {
+    if (!cancelled(error)) throw error;
+  }
+  return summary;
+}