arisa 5.1.49 → 5.1.60

package/src/transport/telegram/chat-queue.js

@@ -6,6 +6,8 @@ export function createChatStateStore() {
       processing: false,
       pendingPrompts: [],
       pendingPromptContexts: [],
+      pendingPromptReceipts: [],
+      pendingPromptCoalescible: [],
       continueAfterClose: false,
       historyRevision: 0,
       beforeNextPrompt: null,
@@ -29,20 +31,59 @@ export function createChatStateStore() {
   };
 }
 
-export function queueChatPrompt(chatState, prompt, { replace = false, ctx = null } = {}) {
+export function createPromptExecutionReceipt() {
+  let resolve;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function rejectQueuedReceipts(chatState, error) {
+  for (const receipt of chatState.pendingPromptReceipts || []) receipt?.reject(error);
+}
+
+const COALESCED_PROMPT_SEPARATOR = "\n\n--- next direct message ---\n\n";
+
+function coalesceLastQueuedPrompt(chatState, prompt, ctx) {
+  const coalescible = chatState.pendingPromptCoalescible ||= [];
+  const index = chatState.pendingPrompts.length - 1;
+  if (index < 0 || !coalescible[index]) return false;
+  chatState.pendingPrompts[index] += `${COALESCED_PROMPT_SEPARATOR}${prompt}`;
+  (chatState.pendingPromptContexts ||= [])[index] = ctx;
+  return true;
+}
+
+export function queueChatPrompt(chatState, prompt, {
+  replace = false,
+  ctx = null,
+  receipt = null,
+  coalescible = false
+} = {}) {
   chatState.pendingPromptContexts ||= [];
+  chatState.pendingPromptReceipts ||= [];
+  chatState.pendingPromptCoalescible ||= [];
   if (replace) {
+    rejectQueuedReceipts(chatState, Object.assign(new Error("Queued prompt was superseded"), { code: "PROMPT_SUPERSEDED" }));
     chatState.pendingPrompts = [];
     chatState.pendingPromptContexts = [];
+    chatState.pendingPromptReceipts = [];
+    chatState.pendingPromptCoalescible = [];
   }
   chatState.pendingPrompts.push(prompt);
   chatState.pendingPromptContexts.push(ctx);
+  chatState.pendingPromptReceipts.push(receipt);
+  chatState.pendingPromptCoalescible.push(coalescible);
 }
 
 function takeQueuedPrompt(chatState) {
+  (chatState.pendingPromptCoalescible ||= []).shift();
   return {
     prompt: chatState.pendingPrompts.shift() || "",
-    ctx: (chatState.pendingPromptContexts ||= []).shift() || null
+    ctx: (chatState.pendingPromptContexts ||= []).shift() || null,
+    receipt: (chatState.pendingPromptReceipts ||= []).shift() || null
   };
 }
 
@@ -52,7 +93,19 @@ export function resolveTelegramBusyMessageMode(config, chatId) {
   return mode === "steer" ? "steer" : "queue";
 }
 
-export async function routeBusyPrompt({ chatState, prompt, mode = "queue", replaceQueued = false, ctx = null }) {
+export async function routeBusyPrompt({
+  chatState,
+  prompt,
+  mode = "queue",
+  replaceQueued = false,
+  ctx = null,
+  receipt = null,
+  coalesceQueued = false
+}) {
+  if (coalesceQueued && !replaceQueued && !receipt && coalesceLastQueuedPrompt(chatState, prompt, ctx)) {
+    return { disposition: "coalesced" };
+  }
+
   const session = chatState.activeSession;
   if (
     mode === "steer"
@@ -61,17 +114,23 @@ export async function routeBusyPrompt({ chatState, prompt, mode = "queue", repla
     && !chatState.beforeNextPrompt
     && session?.isStreaming
     && typeof session.steer === "function"
+    && !receipt
   ) {
     try {
       await session.steer(prompt);
       return { disposition: "steered" };
     } catch (error) {
-      queueChatPrompt(chatState, prompt, { ctx });
+      queueChatPrompt(chatState, prompt, { ctx, receipt, coalescible: coalesceQueued });
       return { disposition: "queued", steerError: error };
     }
   }
 
-  queueChatPrompt(chatState, prompt, { replace: replaceQueued, ctx });
+  queueChatPrompt(chatState, prompt, {
+    replace: replaceQueued,
+    ctx,
+    receipt,
+    coalescible: coalesceQueued
+  });
   return { disposition: "queued" };
 }
 
@@ -84,6 +143,7 @@ export async function drainChatPromptQueue({
   chatState,
   initialPrompt,
   initialCtx = null,
+  initialReceipt = null,
   processPrompt,
   onPromptFailure,
   onPromptInterrupted,
@@ -91,6 +151,7 @@ export async function drainChatPromptQueue({
 }) {
   let currentPrompt = initialPrompt;
   let currentCtx = initialCtx;
+  let currentReceipt = initialReceipt;
 
   try {
     await beforeInitialPrompt?.();
@@ -104,11 +165,14 @@ export async function drainChatPromptQueue({
         const queued = takeQueuedPrompt(chatState);
         currentPrompt = queued.prompt;
         currentCtx = queued.ctx;
+        currentReceipt = queued.receipt;
         chatState.continueAfterClose = false;
       }
       try {
-        await processPrompt({ prompt: currentPrompt, ctx: currentCtx });
+        await processPrompt({ prompt: currentPrompt, ctx: currentCtx, receipt: currentReceipt });
+        currentReceipt?.resolve({ status: "completed" });
       } catch (error) {
+        currentReceipt?.reject(error);
         if (chatState.continueAfterClose && chatState.pendingPrompts.length) {
           await onPromptInterrupted?.(error);
         } else {
@@ -117,11 +181,13 @@ export async function drainChatPromptQueue({
         }
       } finally {
         currentCtx = null;
+        currentReceipt = null;
       }
 
       const queued = takeQueuedPrompt(chatState);
       currentPrompt = queued.prompt;
       currentCtx = queued.ctx;
+      currentReceipt = queued.receipt;
       chatState.continueAfterClose = false;
     }
   } finally {

package/src/transport/telegram/prompt-builders.js

@@ -1,5 +1,6 @@
 import { formatLocationText } from "./media.js";
 import { normalizeArtifactForReasoning, shouldNormalizeArtifactToText } from "../../core/artifacts/normalize-for-reasoning.js";
+import { clampModelSpeed } from "../../core/agent/model-speed.js";
 
 const slowPromptNoticeMs = 300_000;
 
@@ -169,6 +170,14 @@ export function isScheduledTaskPrompt(prompt) {
   return String(prompt || "").startsWith("Scheduled task fired.\n");
 }
 
+export function scheduledPromptSpeedOptions({ prompt, session, speedController, configuredSpeed }) {
+  return {
+    speedController,
+    speed: isScheduledTaskPrompt(prompt) ? 1 : undefined,
+    restoreSpeed: () => clampModelSpeed(session.model, configuredSpeed)
+  };
+}
+
 export async function withPromptSpeed({ speedController, speed, restoreSpeed }, work) {
   if (!speedController || speed === undefined) return work();
   speedController.setSpeed(speed);

package/src/transport/telegram/task-dispatcher.js

@@ -1,9 +1,48 @@
+import { NonRetryableTaskError, createTaskRunner } from "../../core/tasks/task-runner.js";
 import { buildAsyncEventPrompt, buildAsyncTaskPrompt } from "./prompt-builders.js";
 
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+function requireChatId(task) {
+  const chatId = task.payload?.chatId;
+  if (chatId == null || chatId === "") {
+    throw new NonRetryableTaskError(`Task missing chatId: ${task.kind}`);
+  }
+  return chatId;
+}
+
+function safeErrorSummary(error) {
+  return errorMessage(error)
+    .replace(/(bearer\s+)[^\s]+/gi, "$1[redacted]")
+    .replace(/((?:api[_-]?key|token|secret|password)\s*[=:]\s*)[^\s,;]+/gi, "$1[redacted]")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 300) || "Unknown error";
+}
+
+function failureDestination(task) {
+  const destination = task.route?.transport === "telegram" ? task.route.destination : null;
+  return {
+    chatId: destination?.chatId || task.payload?.chatId,
+    threadId: destination?.threadId || null
+  };
+}
+
+function buildFailureNotice({ task, result, error }) {
+  const uncertain = result?.status === "outcome_uncertain";
+  const recurring = result?.terminalFailure === true && result?.status === "pending";
+  const lines = [
+    uncertain ? "⚠️ Arisa task outcome is uncertain" : "⚠️ Arisa task failed",
+    `Task: ${task.kind || "unknown"} (${task.id})`,
+    `Error: ${safeErrorSummary(error)}`
+  ];
+  if (recurring) lines.push(`Next run: ${result.runAt}`);
+  else lines.push("No further retries are scheduled.");
+  return lines.join("\n");
+}
+
 export function createTelegramTaskDispatcher({
   taskStore,
   sendMessage,
@@ -15,21 +54,18 @@ export function createTelegramTaskDispatcher({
   logger
 }) {
   async function dispatchAgentTask(task, chatId) {
-    if (!task.payload.prompt) {
-      await taskStore.fail(task.id, "agent_task missing prompt");
-      return;
-    }
+    if (!task.payload.prompt) throw new NonRetryableTaskError("agent_task missing prompt");
     logger?.log("tasks", `running task ${task.id} for chat ${chatId}`);
     await enqueueAsyncPrompt({
       chatId,
       prompt: await buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, resourceNotes, logger }),
       label: `scheduled task ${task.id}`,
-      telegramContext: task.payload.telegramContext
+      route: task.route
     });
-    await taskStore.complete(task.id);
   }
 
   async function dispatchAgentEvent(task, chatId) {
+    if (!task.payload?.prompt) throw new NonRetryableTaskError("agent_event missing prompt");
     logger?.log("tasks", `agent event ${task.id} for chat ${chatId}`);
     const acknowledgement = String(task.payload?.acknowledgement || "").trim();
     if (acknowledgement) {
@@ -43,52 +79,53 @@ export function createTelegramTaskDispatcher({
       chatId,
       prompt: await buildAsyncEventPrompt(task, resourceNotes),
       label: `agent event ${task.id}`,
-      telegramContext: task.payload.telegramContext
+      route: task.route
     });
-    await taskStore.complete(task.id);
   }
 
   async function dispatchPollTool(task, chatId) {
     const toolName = task.payload?.toolName;
-    if (!toolName) {
-      await taskStore.fail(task.id, "poll_tool missing toolName");
-      return;
-    }
+    if (!toolName) throw new NonRetryableTaskError("poll_tool missing toolName");
     logger?.log("tasks", `polling tool ${toolName} (task ${task.id}) for chat ${chatId}`);
-    try {
-      await agentManager.runTool({
-        name: toolName,
-        request: { args: task.payload.args || {} },
-        chatId
-      });
-    } catch (error) {
-      logger?.log("tasks", `poll_tool ${toolName} failed: ${errorMessage(error)}`);
+    const result = await agentManager.runTool({
+      name: toolName,
+      request: { args: task.payload.args || {} },
+      chatId
+    });
+    if (result?.ok === false) {
+      const error = new Error(result.error || `poll_tool ${toolName} failed`);
+      if (result.status === "needs_config") error.retryable = false;
+      if (result.status === "outcome_uncertain") {
+        error.retryable = false;
+        error.outcomeUncertain = true;
+      }
+      throw error;
     }
-    await taskStore.complete(task.id);
   }
 
   async function dispatchTask(task) {
-    const chatId = task.payload?.chatId;
-    if (!chatId) {
-      await taskStore.fail(task.id, `Task missing chatId: ${task.kind}`);
-      return;
-    }
+    const chatId = requireChatId(task);
     if (task.kind === "agent_task") return dispatchAgentTask(task, chatId);
     if (task.kind === "agent_event") return dispatchAgentEvent(task, chatId);
     if (task.kind === "poll_tool") return dispatchPollTool(task, chatId);
-    await taskStore.fail(task.id, `Unsupported task: ${task.kind}`);
+    throw new NonRetryableTaskError(`Unsupported task: ${task.kind}`);
   }
 
-  async function dispatchDueTasks() {
-    const tasks = await taskStore.claimDue(10);
-    for (const task of tasks) {
-      try {
-        await dispatchTask(task);
-      } catch (error) {
-        await taskStore.fail(task.id, errorMessage(error));
-      }
+  async function notifyTerminalFailure(details) {
+    const destination = failureDestination(details.task);
+    if (!destination.chatId) {
+      logger?.log("tasks", `task ${details.task.id} has no Telegram failure-notification destination`);
+      return;
     }
+    const options = destination.threadId ? { message_thread_id: destination.threadId } : undefined;
+    await sendMessage(destination.chatId, buildFailureNotice(details), options);
   }
 
-  return { dispatchTask, dispatchDueTasks };
+  const runner = createTaskRunner({
+    taskStore,
+    dispatch: dispatchTask,
+    onTerminalFailure: notifyTerminalFailure,
+    logger
+  });
+  return { dispatchTask, dispatchDueTasks: runner.dispatchDueTasks, runClaimedTask: runner.runClaimedTask };
 }

package/src/transport/telegram/telegram-auth-controller.js

@@ -0,0 +1,180 @@
+import {
+  buildPiAuthRecoveryBlockedMessage,
+  buildPiAuthTelegramMessage,
+  getErrorMessage,
+  getPiAuthIssue,
+  getPiAuthStatus
+} from "../../core/agent/auth-flow.js";
+import { createPiOAuthLogin } from "../../core/agent/pi-auth-login.js";
+import { buildDeviceCodeTelegramMessage } from "./device-code-message.js";
+import { getIncomingMessageText } from "./prompt-builders.js";
+
+function chatKey(chatId) {
+  return String(chatId);
+}
+
+export function selectTelegramLoginOption(options = []) {
+  return options.find((option) => /device/i.test(`${option.id} ${option.label}`))
+    || options.find((option) => /browser|oauth|web/i.test(`${option.id} ${option.label}`))
+    || options[0]
+    || null;
+}
+
+export function createTelegramAuthController({
+  config,
+  api,
+  agentManager,
+  logger,
+  markPromptErrorNotified = () => {}
+}) {
+  const renewals = new Map();
+  let issue = null;
+
+  function rememberIssue(error) {
+    const detected = getPiAuthIssue(error);
+    if (detected) issue = detected;
+    return detected;
+  }
+
+  function rememberValidationFailure(error) {
+    const detected = rememberIssue(error) || {
+      kind: "validation-failed",
+      message: getErrorMessage(error)
+    };
+    issue = detected;
+    return detected;
+  }
+
+  async function notifyIssueIfNeeded(chatId, error) {
+    const detected = rememberIssue(error);
+    if (!detected) return false;
+
+    try {
+      await api.sendMessage(chatId, buildPiAuthTelegramMessage({ config, chatId, issue: detected }));
+      markPromptErrorNotified(error);
+      return true;
+    } catch (notifyError) {
+      logger?.error("telegram", `auth issue notice failed for chat ${chatId}: ${getErrorMessage(notifyError)}`);
+      return false;
+    }
+  }
+
+  async function finishRenewal(chatId, renewal) {
+    try {
+      await renewal.promise;
+      await agentManager.validateAgent();
+      agentManager.clearSessionCache(chatId);
+      issue = null;
+      logger?.log("telegram", `Pi auth renewal completed for chat ${chatId}`);
+      await api.sendMessage(chatId, buildPiAuthTelegramMessage({ config, chatId, verified: true }));
+    } catch (error) {
+      const detected = rememberValidationFailure(error);
+      logger?.error("telegram", `Pi auth renewal failed for chat ${chatId}: ${getErrorMessage(error)}`);
+      await api.sendMessage(chatId, buildPiAuthTelegramMessage({ config, chatId, issue: detected })).catch((notifyError) => {
+        logger?.error("telegram", `auth renewal failure notice failed for chat ${chatId}: ${getErrorMessage(notifyError)}`);
+      });
+    } finally {
+      renewals.delete(chatKey(chatId));
+    }
+  }
+
+  async function startRenewal(chatId) {
+    const key = chatKey(chatId);
+    const existing = renewals.get(key);
+    if (existing) return { started: false, renewal: existing };
+
+    const renewal = createPiOAuthLogin({
+      provider: config.pi.provider,
+      onSelect: async ({ message, options }) => {
+        const selected = selectTelegramLoginOption(options);
+        if (!selected) return undefined;
+        logger?.log("telegram", `Pi auth option for chat ${chatId}: ${selected.id}`);
+        await api.sendMessage(chatId, `${message}\nUsing: ${selected.label || selected.id}`);
+        return selected.id;
+      },
+      onAuth: async ({ url, instructions }) => {
+        await api.sendMessage(chatId, [
+          instructions || "Open this URL to continue Pi authentication:",
+          url,
+          "After login, paste the full redirect URL back here."
+        ].join("\n"));
+      },
+      onDeviceCode: async ({ userCode, verificationUri, expiresInSeconds }) => {
+        const payload = buildDeviceCodeTelegramMessage({ userCode, verificationUri, expiresInSeconds });
+        const { text, ...options } = payload;
+        await api.sendMessage(chatId, text, options);
+      },
+      onPrompt: async ({ message, controller }) => {
+        await api.sendMessage(chatId, `${message}\nReply here with the value.`);
+        return controller.waitForManualCode();
+      },
+      onProgress: (message) => {
+        if (message) logger?.log("telegram", `Pi auth progress for chat ${chatId}: ${message}`);
+      }
+    });
+
+    renewals.set(key, renewal);
+    finishRenewal(chatId, renewal);
+    return { started: true, renewal };
+  }
+
+  async function submitRenewalInput(ctx) {
+    const renewal = renewals.get(chatKey(ctx.chat.id));
+    const text = getIncomingMessageText(ctx.message).trim();
+    if (!renewal || !renewal.manualInputRequested || !text) return false;
+    if (!renewal.submitManualCode(text)) return false;
+    await ctx.reply("Got it. Finishing Pi login now...");
+    return true;
+  }
+
+  function buildBlockedMessage(chatId) {
+    return buildPiAuthRecoveryBlockedMessage({
+      config,
+      chatId,
+      issue,
+      renewalActive: renewals.has(chatKey(chatId))
+    });
+  }
+
+  async function handleCommand(ctx, { authorize, withTyping }) {
+    const authorization = await authorize(ctx);
+    if (!authorization.ok) return;
+
+    const status = getPiAuthStatus(config, ctx.chat.id);
+    if (status.hasApiKey || !status.supportsOAuth) {
+      await withTyping(ctx, async () => {
+        try {
+          await agentManager.validateAgent();
+          agentManager.clearSessionCache(ctx.chat.id);
+          issue = null;
+          await ctx.reply(buildPiAuthTelegramMessage({ config, chatId: ctx.chat.id, verified: true }));
+        } catch (error) {
+          const detected = rememberValidationFailure(error);
+          await ctx.reply(buildPiAuthTelegramMessage({ config, chatId: ctx.chat.id, issue: detected }));
+        }
+      });
+      return;
+    }
+
+    try {
+      const { started } = await startRenewal(ctx.chat.id);
+      await ctx.reply(started
+        ? "Starting Pi login from Telegram..."
+        : "Pi login is already in progress. Paste the redirect URL or code here when you have it.");
+    } catch (error) {
+      const detected = rememberValidationFailure(error);
+      await ctx.reply(buildPiAuthTelegramMessage({ config, chatId: ctx.chat.id, issue: detected }));
+    }
+  }
+
+  return {
+    buildBlockedMessage,
+    getIssue: () => issue,
+    handleCommand,
+    hasActiveRenewal: (chatId) => renewals.has(chatKey(chatId)),
+    notifyIssueIfNeeded,
+    rememberIssue,
+    startRenewal,
+    submitRenewalInput
+  };
+}

package/src/transport/telegram/telegram-session-bridge.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+import { InputFile } from "grammy";
+import { cancelRestartReceipt, prepareRestartReceipt } from "../../runtime/restart-receipt.js";
+import { isSilentReply } from "./prompt-builders.js";
+import { renderTelegramHtml } from "./text-format.js";
+import { resolveTelegramWorkspaceRoute, topicSessionId } from "./workspace-group.js";
+
+function deliveryMethod(artifact, method) {
+  if (method) return method;
+  if (artifact.metadata?.delivery?.method) return artifact.metadata.delivery.method;
+  if (artifact.kind === "audio" || artifact.mimeType?.startsWith("audio/")) return "audio";
+  if (artifact.kind === "image" || artifact.mimeType?.startsWith("image/")) return "photo";
+  if (artifact.kind === "video" || artifact.mimeType?.startsWith("video/")) return "video";
+  return "document";
+}
+
+function safeCaption(caption) {
+  return caption && !/(^|\s)(\/[^\s]|[A-Za-z]:[\\/])/.test(caption) ? caption : undefined;
+}
+
+export function createTelegramSessionBridgeController({
+  config,
+  api,
+  agentManager,
+  artifactStore,
+  sessionSeeds,
+  getChatState,
+  buildTopicInitializationHandoff,
+  logger
+}) {
+  function createWorkspaceAccessGuard(route) {
+    return async () => {
+      if (!route.workspace) return;
+      const current = await resolveTelegramWorkspaceRoute({
+        config,
+        api,
+        ctx: {
+          chat: { id: route.transportChatId, type: "supergroup", is_forum: true },
+          from: { id: route.ownerChatId },
+          message: { message_thread_id: route.threadId }
+        }
+      });
+      if (!current.ok) throw new Error("Owner-only workspace access is paused.");
+    };
+  }
+
+  function createSessionBridge(route) {
+    const messageOptions = (extra = {}) => route.workspace && route.threadId
+      ? { ...extra, message_thread_id: route.threadId }
+      : extra;
+    const initializeForumTopic = async ({ messageThreadId, name, context }) => {
+      if (!route.workspace) throw new Error("Telegram topic initialization is only available from the owner workspace forum.");
+      await createWorkspaceAccessGuard(route)();
+      const initializedSessionId = topicSessionId({
+        ownerChatId: route.ownerChatId,
+        groupChatId: route.transportChatId,
+        threadId: messageThreadId,
+        generalTopicId: route.generalTopicId
+      });
+      if (initializedSessionId === String(route.ownerChatId)) {
+        throw new Error("The General topic already uses the owner's private session and cannot be reinitialized here.");
+      }
+      const handoff = buildTopicInitializationHandoff({ name, context });
+      await sessionSeeds.set(initializedSessionId, handoff);
+      agentManager.resetSession(initializedSessionId, { handoff });
+      await agentManager.waitForSessionClose(initializedSessionId);
+      return {
+        ok: true,
+        chatId: route.transportChatId,
+        messageThreadId,
+        sessionId: initializedSessionId,
+        name,
+        initialized: true
+      };
+    };
+    return {
+      sendMedia: async (filePath, { method = "audio", caption, filename } = {}) => {
+        logger?.log("telegram", `sending ${method} reply for chat ${route.transportChatId}`);
+        const input = new InputFile(filePath, filename || undefined);
+        const options = messageOptions({ caption });
+        if (method === "voice") return api.sendVoice(route.transportChatId, input, options);
+        if (method === "document") return api.sendDocument(route.transportChatId, input, options);
+        if (method === "photo" || method === "image") return api.sendPhoto(route.transportChatId, input, options);
+        if (method === "video") return api.sendVideo(route.transportChatId, input, options);
+        return api.sendAudio(route.transportChatId, input, options);
+      },
+      createForumTopic: async (name, context) => {
+        if (!route.workspace) throw new Error("Telegram topic creation is only available from the owner workspace forum.");
+        await createWorkspaceAccessGuard(route)();
+        const topic = await api.createForumTopic(route.transportChatId, name);
+        return initializeForumTopic({
+          messageThreadId: topic.message_thread_id,
+          name: topic.name,
+          context
+        });
+      },
+      initializeForumTopic,
+      prepareRestartReceipt: (summary) => prepareRestartReceipt({
+        transportChatId: route.transportChatId,
+        threadId: route.threadId
+      }, { reason: String(summary || "Agent-requested restart").trim() }),
+      cancelRestartReceipt,
+      getTaskContext: () => route.workspace ? {
+        transport: "telegram",
+        destination: {
+          chatId: route.transportChatId,
+          threadId: route.topicThreadId
+        }
+      } : null
+    };
+  }
+
+  async function sendTextReply({ sendText, sendDocument, chatId, artifactChatId = chatId, text }) {
+    const maxInlineReplyLength = 3500;
+    if (isSilentReply(text)) {
+      logger?.log("telegram", `suppressing silent reply for chat ${chatId}`);
+      return;
+    }
+
+    if (text.length > maxInlineReplyLength) {
+      logger?.log("telegram", `sending long reply as markdown attachment for chat ${chatId}`);
+      const chatArtifactStore = artifactStore.forChat(artifactChatId);
+      const artifact = await chatArtifactStore.createGeneratedFile({
+        fileName: `reply-${Date.now()}.md`,
+        content: text,
+        kind: "document",
+        mimeType: "text/markdown",
+        source: { type: "assistant", chatId },
+        metadata: { delivery: "telegram-document" }
+      });
+      await sendDocument(new InputFile(artifact.path, path.basename(artifact.path)), {
+        caption: "Response attached as Markdown."
+      });
+      return;
+    }
+
+    logger?.log("telegram", `sending text reply for chat ${chatId}`);
+    const sent = await sendText(renderTelegramHtml(text), { parse_mode: "HTML" });
+    if (sent?.message_id) {
+      const messages = getChatState(chatId).assistantMessages;
+      messages.set(sent.message_id, text);
+      while (messages.size > 50) messages.delete(messages.keys().next().value);
+    }
+  }
+
+  function installArtifactDeliveryHandler() {
+    agentManager.setArtifactDeliveryHandler?.(async ({ chatId, artifact, caption, method }) => {
+      const resolvedMethod = deliveryMethod(artifact, method);
+      await createSessionBridge({
+        workspace: false,
+        sessionId: String(chatId),
+        scopeChatId: chatId,
+        transportChatId: chatId,
+        threadId: null
+      }).sendMedia(artifact.path, {
+        method: resolvedMethod,
+        caption: safeCaption(caption),
+        filename: path.basename(artifact.path)
+      });
+      return { ok: true, artifactId: artifact.id, method: resolvedMethod };
+    });
+  }
+
+  return {
+    createSessionBridge,
+    createWorkspaceAccessGuard,
+    installArtifactDeliveryHandler,
+    sendTextReply
+  };
+}