arisa 5.1.49 → 5.1.64

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,69 @@ export function createChatStateStore() {
   };
 }
 
-export function queueChatPrompt(chatState, prompt, { replace = false, ctx = null } = {}) {
+export function createPromptExecutionReceipt(onStart = null) {
+  let resolve;
+  let reject;
+  let started = false;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return {
+    promise,
+    resolve,
+    reject,
+    start() {
+      if (started) return;
+      started = true;
+      onStart?.({ resolve, reject, promise });
+    }
+  };
+}
+
+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 +103,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 +124,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 +153,7 @@ export async function drainChatPromptQueue({
   chatState,
   initialPrompt,
   initialCtx = null,
+  initialReceipt = null,
   processPrompt,
   onPromptFailure,
   onPromptInterrupted,
@@ -91,6 +161,7 @@ export async function drainChatPromptQueue({
 }) {
   let currentPrompt = initialPrompt;
   let currentCtx = initialCtx;
+  let currentReceipt = initialReceipt;
 
   try {
     await beforeInitialPrompt?.();
@@ -104,11 +175,15 @@ 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 });
+        currentReceipt?.start?.();
+        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 +192,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/reply-topic-routing.js

@@ -0,0 +1,111 @@
+const replyTopicMarkerPattern = /\s*\[\[ARISA_REPLY_TOPIC:(\d+)\]\]\s*$/u;
+const proposalMarkerPattern = /\s*\[\[ARISA_PROPOSE_TOPIC:([^\]\r\n]{1,80})\]\]\s*$/u;
+const anyRoutingMarkerPattern = /\s*\[\[ARISA_(?:REPLY_TOPIC|PROPOSE_TOPIC):[^\]]*\]\]\s*$/u;
+
+function singleLine(value, maxLength) {
+  return String(value || "").replace(/\s+/g, " ").trim().slice(0, maxLength);
+}
+
+export function isGeneralWorkspaceRoute(route) {
+  return Boolean(route?.workspace
+    && route.threadId == null
+    && route.topicThreadId === route.generalTopicId);
+}
+
+function activeTopics(topics = []) {
+  return topics
+    .map((topic) => ({
+      threadId: Number(topic?.threadId),
+      name: singleLine(topic?.name, 80),
+      description: singleLine(topic?.description, 240)
+    }))
+    .filter((topic) => Number.isSafeInteger(topic.threadId) && topic.threadId > 0 && topic.name)
+    .sort((left, right) => left.threadId - right.threadId)
+    .slice(0, 32);
+}
+
+export function buildGeneralReplyRoutingInstruction(topics = [], recentProposals = []) {
+  const available = activeTopics(topics);
+  const options = available.length
+    ? available.map((topic) => [
+      `- ${topic.threadId}: ${topic.name}`,
+      topic.description ? ` — ${topic.description}` : ""
+    ].join(""))
+    : ["- No named topics are registered yet."];
+  const proposals = recentProposals
+    .map((proposal) => singleLine(proposal?.name, 80))
+    .filter(Boolean)
+    .slice(0, 12);
+  return [
+    "Telegram General-topic management instruction:",
+    "This applies only because the incoming message was written in General inside an owner workspace supergroup. It never applies to a private chat with the bot.",
+    "The original message must stay in General and the conversation remains in the General session.",
+    "If, and only if, your final response clearly belongs to exactly one registered topic below, append [[ARISA_REPLY_TOPIC:<id>]] as the final line. Do not mention this routing marker.",
+    "If the relationship is weak, ambiguous, or no topic fits, do not append a reply marker and the response will remain in General.",
+    "You may occasionally propose a new topic only when the General conversation shows a substantial theme recurring across multiple turns and no registered topic fits. Ask for explicit confirmation in the visible response and append [[ARISA_PROPOSE_TOPIC:<short name>]] as the final line. Never create a topic without explicit confirmation.",
+    proposals.length ? `Do not repeat these recent topic proposals: ${proposals.join(", ")}.` : null,
+    "Registered reply topics:",
+    ...options
+  ].filter(Boolean).join("\n");
+}
+
+export function appendGeneralReplyRoutingInstruction(prompt, topics = [], recentProposals = []) {
+  return `${String(prompt || "")}\n\n${buildGeneralReplyRoutingInstruction(topics, recentProposals)}`;
+}
+
+export function extractReplyTopicMetadata(text, topics = []) {
+  let cleanedText = String(text || "");
+  let requestedThreadId = null;
+  let proposal = "";
+  let changed = true;
+  while (changed) {
+    changed = false;
+    const replyMatch = cleanedText.match(replyTopicMarkerPattern);
+    if (replyMatch) {
+      requestedThreadId ??= Number(replyMatch[1]);
+      cleanedText = cleanedText.replace(replyTopicMarkerPattern, "");
+      changed = true;
+      continue;
+    }
+    const proposalMatch = cleanedText.match(proposalMarkerPattern);
+    if (proposalMatch) {
+      proposal ||= singleLine(proposalMatch[1], 80);
+      cleanedText = cleanedText.replace(proposalMarkerPattern, "");
+      changed = true;
+      continue;
+    }
+    if (anyRoutingMarkerPattern.test(cleanedText)) {
+      cleanedText = cleanedText.replace(anyRoutingMarkerPattern, "");
+      changed = true;
+    }
+  }
+
+  const available = activeTopics(topics);
+  const allowed = available.some((topic) => topic.threadId === requestedThreadId);
+  return {
+    text: cleanedText.trimEnd(),
+    threadId: allowed ? requestedThreadId : null,
+    proposal
+  };
+}
+
+export function routeGeneralWorkspaceReply({ route, text, topics = [] }) {
+  const generalWorkspaceRoute = isGeneralWorkspaceRoute(route);
+  const extracted = extractReplyTopicMetadata(text, generalWorkspaceRoute ? topics : []);
+  if (!generalWorkspaceRoute) {
+    return { text: extracted.text, route, topic: null, proposal: "" };
+  }
+
+  const topic = activeTopics(topics).find((item) => item.threadId === extracted.threadId) || null;
+  if (!topic) return { text: extracted.text, route, topic: null, proposal: extracted.proposal };
+  return {
+    text: extracted.text,
+    route: {
+      ...route,
+      threadId: topic.threadId,
+      topicThreadId: topic.threadId
+    },
+    topic,
+    proposal: ""
+  };
+}

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

@@ -1,9 +1,55 @@
+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 boundedTimeout(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.min(Math.round(parsed), 60 * 60_000)
+    : fallback;
+}
+
+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" || result?.lastOutcome === "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,
@@ -12,24 +58,26 @@ export function createTelegramTaskDispatcher({
   toolRegistry,
   resourceNotes,
   agentManager,
+  taskTimeouts = {},
   logger
 }) {
+  const agentTimeoutMs = boundedTimeout(taskTimeouts.agentTimeoutMs, 15 * 60_000);
+  const eventTimeoutMs = boundedTimeout(taskTimeouts.eventTimeoutMs, 5 * 60_000);
+
   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,
+      timeoutMs: agentTimeoutMs
     });
-    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 +91,64 @@ export function createTelegramTaskDispatcher({
       chatId,
       prompt: await buildAsyncEventPrompt(task, resourceNotes),
       label: `agent event ${task.id}`,
-      telegramContext: task.payload.telegramContext
+      route: task.route,
+      timeoutMs: eventTimeoutMs
     });
-    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,
+    laneKey(task) {
+      if (task.kind === "poll_tool") {
+        return `poll:${task.payload?.chatId}:${task.payload?.toolName || task.id}`;
+      }
+      const destination = task.route?.transport === "telegram" ? task.route.destination : null;
+      if (!destination?.chatId || Number(destination.threadId) === 1) {
+        return `agent:${task.payload?.chatId}`;
+      }
+      return `agent:${destination.chatId}:${destination.threadId || 0}`;
+    },
+    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
+  };
+}