@ycodium-ai/plugin-im 0.2.3220 → 0.2.3230

package/dist/index.js

@@ -126460,9 +126460,21 @@ var makeConclusionLedger = (core) => {
       unpersisted.delete(key);
       if (added) await recover?.(debt);
     },
+    /** selection 为 null 表示执行视图不可读且本会话仍有欠账，须等恢复器判定后投递。 */
     forTurn: async (threadId, turnId = null) => {
       await Promise.all(registering.get(threadId) ?? []);
-      const execution = await core.host.projections.getThreadExecution(threadId);
+      const execution = await core.host.projections.getThreadExecution(threadId).catch((error) => {
+        const owes = Object.values(conclusionDebtsOf(core.state)).some(
+          (debt) => debt.threadId === threadId
+        );
+        if (!owes) return null;
+        core.host.log.warn("chat deferred a conclusion until its execution can be read", {
+          threadId,
+          error: describeError(error)
+        });
+        return void 0;
+      });
+      if (execution === void 0) return { selection: null, handled: false, execution: null };
       return {
         execution,
         ...execution === null ? { selection: void 0, handled: false } : forExecutionTurn(
@@ -133354,6 +133366,87 @@ var makeCommands = (core, deps) => {
   return { handleCommand, executeCommand, targetOf };
 };
 
+// src/connectionError.ts
+var NETWORK_HINTS = {
+  ENOTFOUND: "networkDns",
+  EAI_AGAIN: "networkDns",
+  ECONNREFUSED: "networkRefused",
+  ECONNRESET: "networkReset",
+  EPIPE: "networkReset",
+  UND_ERR_SOCKET: "networkReset",
+  ENETUNREACH: "networkUnreachable",
+  EHOSTUNREACH: "networkUnreachable",
+  ERR_NETWORK_ACCESS_DENIED: "networkUnreachable",
+  CERT_HAS_EXPIRED: "networkTls",
+  CERT_NOT_YET_VALID: "networkTls",
+  DEPTH_ZERO_SELF_SIGNED_CERT: "networkTls",
+  SELF_SIGNED_CERT_IN_CHAIN: "networkTls",
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: "networkTls",
+  UNABLE_TO_GET_ISSUER_CERT_LOCALLY: "networkTls",
+  ERR_TLS_CERT_ALTNAME_INVALID: "networkTls",
+  ERR_SSL_WRONG_VERSION_NUMBER: "networkTls",
+  ERR_TLS_HANDSHAKE_TIMEOUT: "networkTls",
+  ERR_SSL_TLSV1_ALERT_INTERNAL_ERROR: "networkTls",
+  ETIMEDOUT: "networkTimeout",
+  UND_ERR_CONNECT_TIMEOUT: "networkTimeout",
+  UND_ERR_HEADERS_TIMEOUT: "networkTimeout",
+  UND_ERR_BODY_TIMEOUT: "networkTimeout",
+  timeout: "networkTimeout",
+  ERR_PROXY_CONNECTION_FAILED: "networkProxy"
+};
+var NETWORK_REASONS = new Set(Object.keys(NETWORK_HINTS));
+var GENERIC_REASONS = /* @__PURE__ */ new Set(["timeout"]);
+var MAX_NODES = 16;
+var recordOf = (value2) => value2 !== null && typeof value2 === "object" ? value2 : void 0;
+var httpStatusOf = (value2) => typeof value2 === "number" && Number.isInteger(value2) && value2 >= 100 && value2 <= 599 ? value2 : void 0;
+var networkReason = (value2) => typeof value2 === "string" && NETWORK_REASONS.has(value2) ? value2 : void 0;
+var canonicalCode = (entry) => entry["name"] === "TimeoutError" ? "timeout" : entry["code"];
+var visitedErrors = (error) => {
+  const queue = [error];
+  const seen = /* @__PURE__ */ new Set();
+  const chain = [];
+  while (queue.length > 0 && chain.length < MAX_NODES) {
+    const entry = recordOf(queue.shift());
+    if (entry === void 0 || seen.has(entry)) continue;
+    seen.add(entry);
+    chain.push(entry);
+    if (recordOf(entry["cause"]) !== void 0) queue.push(entry["cause"]);
+    if (Array.isArray(entry["errors"])) queue.push(...entry["errors"].slice(0, MAX_NODES));
+  }
+  return chain;
+};
+var connectionFacts = (error) => {
+  const nodes = visitedErrors(error).map((entry) => {
+    const response = recordOf(entry["response"]);
+    const fromCode = networkReason(canonicalCode(entry));
+    return {
+      reasons: fromCode === void 0 ? [] : [fromCode],
+      httpStatus: httpStatusOf(entry["status"] ?? entry["statusCode"] ?? response?.["status"])
+    };
+  });
+  const all2 = [...new Set(nodes.flatMap((node) => node.reasons))];
+  const precise = all2.filter((reason) => !GENERIC_REASONS.has(reason));
+  const httpStatus = nodes.find((node) => node.httpStatus !== void 0)?.httpStatus;
+  return {
+    reasons: precise.length > 0 ? precise : all2,
+    ...httpStatus !== void 0 ? { httpStatus } : {}
+  };
+};
+var connectionHint = (error) => {
+  const { reasons, httpStatus } = connectionFacts(error);
+  if (reasons.length > 1) return "networkMultipleCauses";
+  const mapped = reasons[0] !== void 0 ? NETWORK_HINTS[reasons[0]] : void 0;
+  if (mapped !== void 0) return mapped;
+  if (httpStatus === 407) return "networkProxy";
+  if (httpStatus === 429) return "platformRateLimited";
+  if (httpStatus !== void 0 && httpStatus >= 500) return "platformUnavailable";
+  return void 0;
+};
+var connectionHintFields = (error, platformHint) => {
+  const hint = platformHint ?? connectionHint(error);
+  return hint === void 0 ? {} : { hint };
+};
+
 // src/inboundStore.ts
 import * as NodeCrypto from "node:crypto";
 import * as NodeFSP from "node:fs/promises";
@@ -134068,7 +134161,7 @@ var startConnections = (core, inboundHandlersFor, inboundState, recovery) => {
               state: "failed",
               ...status.reason === void 0 ? {} : { reason: status.reason },
               ...status.error === void 0 ? {} : { error: redactor.redact(describeError(status.error)) },
-              ...status.hint === void 0 ? {} : { hint: status.hint }
+              ...connectionHintFields(status.error, status.hint)
             });
           }
         });
@@ -134081,7 +134174,7 @@ var startConnections = (core, inboundHandlersFor, inboundState, recovery) => {
           record4(bot.rowId, {
             state: "failed",
             error: detail,
-            ...error instanceof InboxUnreadableError ? { reason: "inbox-unreadable", hint: "inboxUnreadable" } : {}
+            ...error instanceof InboxUnreadableError ? { reason: "inbox-unreadable", hint: "inboxUnreadable" } : connectionHintFields(error)
           });
         host.log.warn("chat could not start an inbound connection", {
           bot: bot.displayName,
@@ -135640,11 +135733,11 @@ var parseNumberedReply = (item, text4, t) => {
 // src/questionFlow.ts
 var makeQuestionFlow = (host) => {
   const { t } = host;
-  const recordOf = (requestId) => questionsOf(host.state())[requestId];
-  const itemOf = (requestId, questionId) => recordOf(requestId)?.items.find((item) => item.id === questionId);
+  const recordOf2 = (requestId) => questionsOf(host.state())[requestId];
+  const itemOf = (requestId, questionId) => recordOf2(requestId)?.items.find((item) => item.id === questionId);
   const hasButtons = (chatKey) => host.target(chatKey)?.adapter.choiceCards !== void 0;
   const redraw = async (requestId, questionId) => {
-    const record4 = recordOf(requestId);
+    const record4 = recordOf2(requestId);
     const item = itemOf(requestId, questionId);
     const target2 = record4 === void 0 ? void 0 : host.target(record4.chatKey);
     if (record4 === void 0 || item?.cardId === void 0 || target2 === void 0) return;
@@ -135660,7 +135753,7 @@ var makeQuestionFlow = (host) => {
     }
   };
   const freeze = async (requestId, questionId) => {
-    const record4 = recordOf(requestId);
+    const record4 = recordOf2(requestId);
     const item = itemOf(requestId, questionId);
     const target2 = record4 === void 0 ? void 0 : host.target(record4.chatKey);
     if (record4 === void 0 || item?.cardId === void 0 || target2 === void 0) return;
@@ -135681,7 +135774,7 @@ var makeQuestionFlow = (host) => {
     }
   };
   const sayNext = async (requestId) => {
-    const record4 = recordOf(requestId);
+    const record4 = recordOf2(requestId);
     if (record4 === void 0 || record4.resolved) return;
     const item = record4.items.find(isUnanswered);
     if (item === void 0) return;
@@ -135691,7 +135784,7 @@ var makeQuestionFlow = (host) => {
     );
   };
   const post = async (requestId) => {
-    const first = recordOf(requestId);
+    const first = recordOf2(requestId);
     const target2 = first === void 0 ? void 0 : host.target(first.chatKey);
     if (first === void 0 || target2 === void 0) return;
     const cards = target2.adapter.choiceCards;
@@ -135700,7 +135793,7 @@ var makeQuestionFlow = (host) => {
       return;
     }
     for (const questionId of first.items.map((item) => item.id)) {
-      const record4 = recordOf(requestId);
+      const record4 = recordOf2(requestId);
       const item = itemOf(requestId, questionId);
       if (record4 === void 0 || record4.resolved || item === void 0) return;
       try {
@@ -135710,7 +135803,7 @@ var makeQuestionFlow = (host) => {
         );
         if (cardId === null) continue;
         host.commit("question-carded", { requestId, questionId, cardId });
-        const after = recordOf(requestId);
+        const after = recordOf2(requestId);
         if (after?.resolved === true || itemOf(requestId, questionId)?.answer !== void 0) {
           await freeze(requestId, questionId);
         }
@@ -135727,7 +135820,7 @@ var makeQuestionFlow = (host) => {
       host.warn("chat cannot show questions on this platform");
       return;
     }
-    const fresh = pending.filter((request) => recordOf(request.requestId) === void 0);
+    const fresh = pending.filter((request) => recordOf2(request.requestId) === void 0);
     for (const request of buttons ? fresh : fresh.slice(0, 1)) {
       host.commit("question-offered", {
         chatKey,
@@ -135750,18 +135843,18 @@ var makeQuestionFlow = (host) => {
           ...question.multiSelect ? { submitToken: host.newToken() } : {}
         }))
       });
-      if (recordOf(request.requestId) === void 0) continue;
+      if (recordOf2(request.requestId) === void 0) continue;
       host.outbound(chatKey, () => post(request.requestId));
     }
   };
   const answer = async (requestId, questionId, value2, label) => {
-    const before = recordOf(requestId);
+    const before = recordOf2(requestId);
     const item = itemOf(requestId, questionId);
     if (before === void 0 || before.resolved || item === void 0 || !isUnanswered(item)) {
       return false;
     }
     host.commit("question-answered", { requestId, questionId, answer: value2, label });
-    const after = recordOf(requestId);
+    const after = recordOf2(requestId);
     if (after === void 0) return false;
     const complete = after.items.every((entry) => !isUnanswered(entry));
     if (complete) host.commit("question-resolved", { requestId, ending: "here" });
@@ -135840,7 +135933,7 @@ var makeQuestionFlow = (host) => {
   };
   const answerText = (input) => answer(input.requestId, input.questionId, input.value, input.label);
   const resolved = (requestId, outcome) => {
-    const record4 = recordOf(requestId);
+    const record4 = recordOf2(requestId);
     if (record4 === void 0 || record4.resolved) return;
     const ending = outcome === "answered" ? "elsewhere" : "cancelled";
     host.commit("question-resolved", { requestId, ending });
@@ -135938,7 +136031,7 @@ var makeQueueFlow = (host, deps) => {
   const { t } = host;
   const shown = /* @__PURE__ */ new Map();
   const notes = /* @__PURE__ */ new Map();
-  const recordOf = (intentId) => queueOf(host.state())[intentId];
+  const recordOf2 = (intentId) => queueOf(host.state())[intentId];
   const factsOf = (execution, intentId) => ({
     activeTurnId: execution.activeTurnId,
     queuePaused: execution.queuePaused,
@@ -135976,7 +136069,7 @@ var makeQueueFlow = (host, deps) => {
       resumeToken: host.newToken()
     });
     host.outbound(chatKey, async () => {
-      const record4 = recordOf(intentId);
+      const record4 = recordOf2(intentId);
       if (record4 === void 0) return;
       try {
         const latest = await deps.readExecution(threadId) ?? execution;
@@ -136002,7 +136095,7 @@ var makeQueueFlow = (host, deps) => {
     });
   };
   const redraw = async (intentId, released) => {
-    const record4 = recordOf(intentId);
+    const record4 = recordOf2(intentId);
     const target2 = record4 === void 0 ? void 0 : host.target(record4.chatKey);
     if (record4 === void 0 || record4.settled !== void 0 || target2 === void 0) return;
     if (record4.cardId === void 0) return;
@@ -138406,6 +138499,9 @@ var fetchUserName = async (input) => {
 };
 var sendChatText = async (input) => postMessage({ ...input, operation: "send", msgType: "text", content: { text: input.text } });
 var LARK_WORKING_REACTION = "OnIt";
+var LARK_DONE_REACTION = "DONE";
+var LARK_FAILED_REACTION = "ERROR";
+var LARK_REACTION_TIMEOUT_MS = 2e3;
 var addReaction = async (input) => {
   const response = await input.http(
     `${LARK_BASE}/im/v1/messages/${encodeURIComponent(input.messageId)}/reactions`,
@@ -138415,7 +138511,8 @@ var addReaction = async (input) => {
         authorization: `Bearer ${input.token}`,
         "content-type": "application/json; charset=utf-8"
       },
-      body: JSON.stringify({ reaction_type: { emoji_type: input.emojiType } })
+      body: JSON.stringify({ reaction_type: { emoji_type: input.emojiType } }),
+      ...input.signal === void 0 ? {} : { signal: input.signal }
     }
   );
   const body = await readEnvelope("reactions.create", response);
@@ -138426,7 +138523,8 @@ var removeReaction = async (input) => {
     `${LARK_BASE}/im/v1/messages/${encodeURIComponent(input.messageId)}/reactions/${encodeURIComponent(input.reactionId)}`,
     {
       method: "DELETE",
-      headers: { authorization: `Bearer ${input.token}` }
+      headers: { authorization: `Bearer ${input.token}` },
+      ...input.signal === void 0 ? {} : { signal: input.signal }
     }
   );
   await readEnvelope("reactions.delete", response);
@@ -144251,7 +144349,7 @@ var startLarkInbound = (input) => {
         state: "failed",
         reason: hint === "larkCredentials" ? "credentials-rejected" : "disconnected",
         error,
-        ...hint === void 0 ? {} : { hint }
+        ...connectionHintFields(error, hint)
       });
     }
   };
@@ -144310,6 +144408,22 @@ var larkInboundPersistence = (contextFor) => ({
   }
 });
 
+// src/deadline.ts
+var withDeadline2 = async (timeoutMs, load) => {
+  const signal = AbortSignal.timeout(timeoutMs);
+  let onAbort = () => {
+  };
+  const aborted = new Promise((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([load(signal), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+};
+
 // src/boundedSeen.ts
 var makeBoundedSeen = (limit) => {
   const seen = /* @__PURE__ */ new Set();
@@ -144328,22 +144442,6 @@ var makeBoundedSeen = (limit) => {
   };
 };
 
-// src/deadline.ts
-var withDeadline2 = async (timeoutMs, load) => {
-  const signal = AbortSignal.timeout(timeoutMs);
-  let onAbort = () => {
-  };
-  const aborted = new Promise((_, reject) => {
-    onAbort = () => reject(signal.reason);
-    signal.addEventListener("abort", onAbort, { once: true });
-  });
-  try {
-    return await Promise.race([load(signal), aborted]);
-  } finally {
-    signal.removeEventListener("abort", onAbort);
-  }
-};
-
 // src/replyReference.ts
 import * as NodeCrypto4 from "node:crypto";
 
@@ -144977,12 +145075,11 @@ var makeLarkAdapter = (deps) => {
           detail: `token ok; expiresIn=${String(expiresInSeconds)}s`
         };
       } catch (error) {
-        const hint = larkConnectionHint(error);
         return {
           stage: "tenant_access_token",
           ok: false,
           detail: describeError(error),
-          ...hint === void 0 ? {} : { hint }
+          ...connectionHintFields(error, larkConnectionHint(error))
         };
       }
     },
@@ -145087,13 +145184,22 @@ var makeLarkAdapter = (deps) => {
       messageId,
       emojiType: LARK_WORKING_REACTION
     }),
-    clearAcknowledge: async (binding, messageId, ackId) => {
-      await removeReaction({
-        http: deps.http,
-        token: await tenantToken(binding),
-        messageId,
-        reactionId: ackId
-      });
+    clearAcknowledge: async (binding, messageId, ackId, outcome) => {
+      const token = await tenantToken(binding);
+      await withDeadline2(
+        LARK_REACTION_TIMEOUT_MS,
+        (signal) => removeReaction({ http: deps.http, token, messageId, reactionId: ackId, signal })
+      );
+      const emojiType = outcome === "done" ? LARK_DONE_REACTION : outcome === "failed" ? LARK_FAILED_REACTION : null;
+      if (emojiType === null) return;
+      try {
+        await withDeadline2(
+          LARK_REACTION_TIMEOUT_MS,
+          (signal) => addReaction({ http: deps.http, token, messageId, emojiType, signal })
+        );
+      } catch (error) {
+        deps.log.warn("lark could not react to the message", { error: describeError(error) });
+      }
     },
     fetchResource: async (binding, input) => {
       const resource = input.resource;
@@ -145330,6 +145436,13 @@ var en_default = {
     turnFailedNoDetail: "This turn didn't finish. Reference {{ref}}. Send the message again; if it keeps failing, send /new to start a new conversation.",
     turnFailedBrief: "This turn didn't finish: {{detail}}\nSend the message again; if it keeps failing, send /new to start a new conversation.",
     turnFailedBriefNoDetail: "This turn didn't finish. Send the message again; if it keeps failing, send /new to start a new conversation.",
+    turnFailedWithReference: "{{message}}\nReference {{ref}}.",
+    turnFailedQuota: "The model quota or balance is insufficient, so this turn didn't finish. Send /model to switch to another model, or ask an administrator to add quota, then try again.",
+    turnFailedRateLimit: "The model service is rate-limiting requests, so this turn didn't finish. Please try again later.",
+    turnFailedContextLimit: "This conversation exceeds the model context limit, so this turn didn't finish. Send /new to start a new conversation, then send your request again.",
+    turnFailedAuth: "The model credentials are missing or invalid, so this turn didn't finish. Ask an administrator to check the model settings, then try again.",
+    turnFailedModelUnavailable: "The current model does not exist or does not support the selected settings, so this turn didn't finish. Send /model to list models, then send /model followed by a number (for example /model 2) to pick one for this chat, and send your request again.",
+    turnFailedTransport: "The model service is temporarily unreachable, so this turn didn't finish. Please try again later.",
     attachmentReceived: "Got {{names}} ({{count}} waiting). Tell me what to do with them.",
     attachmentFailed: "Could not take {{name}}: {{reason}}.",
     attachmentReason: {
@@ -145681,6 +145794,16 @@ var en_default = {
       failed: "Connection failed",
       notSaved: "Save this row first (credentials are read from saved config only).",
       hint: {
+        networkMultipleCauses: "This failure has more than one network cause. Check this machine's network and this bot's Proxy setting, then check again.",
+        networkDns: "The service's domain name could not be resolved. Check this machine's DNS and network settings, then check again.",
+        networkRefused: "The connection was refused. Check whether a firewall or security software on this machine or its network is blocking it, then check again.",
+        networkReset: "The connection was cut off by the other side. Check this machine's network and whether the target service is running normally, then check again.",
+        networkUnreachable: "The target network is unreachable. Check this machine's outbound network access and access restrictions, then check again.",
+        networkTls: "TLS or certificate validation failed. Check this machine's system clock, certificate chain and network settings, and whether a proxy or security software is intercepting HTTPS, then check again.",
+        networkTimeout: "The request timed out. Check whether the target service is running normally and check this machine's network, then check again.",
+        networkProxy: "Proxy connection or authentication failed. Check this row's Proxy setting and the selected proxy's configuration on this machine; if no proxy is set, check other proxies on this machine or its network, then check again.",
+        platformRateLimited: "The platform is rate limiting requests. Try again later.",
+        platformUnavailable: "The target service is temporarily having problems. Try again later.",
         connecting: "Still connecting. There is usually a result within 20 seconds; check again in a moment.",
         badToken: "This does not look like a bot token. Copy it again from BotFather: digits, a colon, then the key.",
         unauthorized: "Telegram does not accept this token. It may have been revoked; get the current one from BotFather. Save the corrected token here to reconnect automatically; if nothing needs changing, use Reconnect below.",
@@ -146100,6 +146223,13 @@ var zh_CN_default = {
     turnFailedNoDetail: "\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u53C2\u8003\u53F7 {{ref}}\u3002\u53EF\u4EE5\u76F4\u63A5\u518D\u53D1\u4E00\u6B21\uFF1B\u4E00\u76F4\u4E0D\u884C\u5C31\u53D1 /new \u5F00\u4E2A\u65B0\u4F1A\u8BDD\u3002",
     turnFailedBrief: "\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\uFF1A{{detail}}\n\u53EF\u4EE5\u76F4\u63A5\u518D\u53D1\u4E00\u6B21\uFF1B\u4E00\u76F4\u4E0D\u884C\u5C31\u53D1 /new \u5F00\u4E2A\u65B0\u4F1A\u8BDD\u3002",
     turnFailedBriefNoDetail: "\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u53EF\u4EE5\u76F4\u63A5\u518D\u53D1\u4E00\u6B21\uFF1B\u4E00\u76F4\u4E0D\u884C\u5C31\u53D1 /new \u5F00\u4E2A\u65B0\u4F1A\u8BDD\u3002",
+    turnFailedWithReference: "{{message}}\n\u53C2\u8003\u53F7 {{ref}}\u3002",
+    turnFailedQuota: "\u6A21\u578B\u989D\u5EA6\u6216\u4F59\u989D\u4E0D\u8DB3\uFF0C\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u53EF\u4EE5\u53D1 /model \u6362\u4E2A\u6A21\u578B\u518D\u8BD5\uFF0C\u6216\u8BF7\u7BA1\u7406\u5458\u8865\u5145\u989D\u5EA6\u540E\u91CD\u8BD5\u3002",
+    turnFailedRateLimit: "\u6A21\u578B\u670D\u52A1\u6B63\u5728\u9650\u6D41\uFF0C\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
+    turnFailedContextLimit: "\u5F53\u524D\u4F1A\u8BDD\u5185\u5BB9\u8D85\u8FC7\u6A21\u578B\u4E0A\u4E0B\u6587\u4E0A\u9650\uFF0C\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u8BF7\u53D1 /new \u5F00\u4E2A\u65B0\u4F1A\u8BDD\uFF0C\u518D\u628A\u8BF7\u6C42\u91CD\u65B0\u53D1\u4E00\u904D\u3002",
+    turnFailedAuth: "\u6A21\u578B\u51ED\u636E\u7F3A\u5931\u6216\u65E0\u6548\uFF0C\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u8BF7\u7BA1\u7406\u5458\u68C0\u67E5\u6A21\u578B\u914D\u7F6E\uFF0C\u4E4B\u540E\u4F60\u518D\u53D1\u4E00\u6B21\u3002",
+    turnFailedModelUnavailable: "\u5F53\u524D\u6A21\u578B\u4E0D\u5B58\u5728\u6216\u4E0D\u652F\u6301\u6240\u9009\u914D\u7F6E\uFF0C\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u8BF7\u53D1 /model \u67E5\u770B\u53EF\u9009\u6A21\u578B\uFF0C\u518D\u53D1 /model \u52A0\u7F16\u53F7\uFF08\u4F8B\u5982 /model 2\uFF09\u4E3A\u8FD9\u4E2A\u804A\u5929\u9009\u4E00\u4E2A\uFF0C\u7136\u540E\u91CD\u53D1\u8BF7\u6C42\u3002",
+    turnFailedTransport: "\u6682\u65F6\u65E0\u6CD5\u8FDE\u63A5\u6A21\u578B\u670D\u52A1\uFF0C\u8FD9\u4E00\u8F6E\u6CA1\u80FD\u5B8C\u6210\u3002\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
     attachmentReceived: "\u6536\u5230 {{names}}\uFF08\u73B0\u6709 {{count}} \u4E2A\u5F85\u5904\u7406\uFF09\u3002\u8BF4\u4E00\u53E5\u60F3\u8BA9\u6211\u600E\u4E48\u5904\u7406\u3002",
     attachmentFailed: "\u6CA1\u80FD\u6536\u4E0B {{name}}\uFF1A{{reason}}\u3002",
     attachmentReason: {
@@ -146451,6 +146581,16 @@ var zh_CN_default = {
       failed: "\u8FDE\u63A5\u5931\u8D25",
       notSaved: "\u8BF7\u5148\u4FDD\u5B58\u8FD9\u4E00\u884C\u518D\u68C0\u67E5\u8FDE\u63A5\uFF08\u51ED\u636E\u53EA\u4ECE\u5DF2\u4FDD\u5B58\u914D\u7F6E\u8BFB\u53D6\uFF09\u3002",
       hint: {
+        networkMultipleCauses: "\u8FD9\u6B21\u5931\u8D25\u80CC\u540E\u4E0D\u6B62\u4E00\u79CD\u7F51\u7EDC\u95EE\u9898\u3002\u8BF7\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u7684\u7F51\u7EDC\u548C\u8FD9\u4E2A\u673A\u5668\u4EBA\u7684\u300C\u4EE3\u7406\u300D\u8BBE\u7F6E\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkDns: "\u670D\u52A1\u57DF\u540D\u89E3\u6790\u5931\u8D25\u3002\u8BF7\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u7684 DNS \u548C\u7F51\u7EDC\u8BBE\u7F6E\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkRefused: "\u76EE\u6807\u62D2\u7EDD\u4E86\u8FDE\u63A5\u3002\u8BF7\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u548C\u6240\u5728\u7F51\u7EDC\u7684\u9632\u706B\u5899\u3001\u5B89\u5168\u8F6F\u4EF6\u662F\u5426\u62E6\u4E86\u8FD9\u4E2A\u8FDE\u63A5\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkReset: "\u8FDE\u63A5\u88AB\u5BF9\u65B9\u4E2D\u65AD\u3002\u8BF7\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u7684\u7F51\u7EDC\uFF0C\u4EE5\u53CA\u76EE\u6807\u670D\u52A1\u662F\u5426\u5728\u6B63\u5E38\u8FD0\u884C\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkUnreachable: "\u76EE\u6807\u7F51\u7EDC\u4E0D\u53EF\u8FBE\u3002\u8BF7\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u7684\u7F51\u7EDC\u51FA\u53E3\u548C\u8BBF\u95EE\u9650\u5236\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkTls: "TLS \u6216\u8BC1\u4E66\u6821\u9A8C\u5931\u8D25\u3002\u8BF7\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u7684\u7CFB\u7EDF\u65F6\u95F4\u3001\u8BC1\u4E66\u94FE\u548C\u7F51\u7EDC\u8BBE\u7F6E\uFF0C\u4EE5\u53CA\u4EE3\u7406\u6216\u5B89\u5168\u8F6F\u4EF6\u662F\u5426\u62E6\u622A\u4E86 HTTPS \u8FDE\u63A5\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkTimeout: "\u8BF7\u6C42\u8D85\u65F6\u3002\u8BF7\u786E\u8BA4\u76EE\u6807\u670D\u52A1\u662F\u5426\u5728\u6B63\u5E38\u8FD0\u884C\uFF0C\u5E76\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u7684\u7F51\u7EDC\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        networkProxy: "\u4EE3\u7406\u8FDE\u63A5\u6216\u8BA4\u8BC1\u5931\u8D25\u3002\u8BF7\u68C0\u67E5\u8FD9\u4E00\u884C\u7684\u300C\u4EE3\u7406\u300D\u8BBE\u7F6E\u548C\u6240\u9009\u4EE3\u7406\u5728\u8FD9\u53F0\u673A\u5668\u4E0A\u7684\u914D\u7F6E\uFF1B\u6CA1\u8BBE\u4EE3\u7406\u7684\u8BDD\uFF0C\u68C0\u67E5\u8FD9\u53F0\u673A\u5668\u6216\u6240\u5728\u7F51\u7EDC\u4E0A\u7684\u5176\u4ED6\u4EE3\u7406\uFF0C\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
+        platformRateLimited: "\u5E73\u53F0\u6B63\u5728\u9650\u6D41\u3002\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
+        platformUnavailable: "\u76EE\u6807\u670D\u52A1\u6682\u65F6\u5F02\u5E38\u3002\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
         connecting: "\u8FD8\u5728\u8FDE\u63A5\uFF0C\u4E00\u822C 20 \u79D2\u5185\u4F1A\u6709\u7ED3\u679C\uFF0C\u7A0D\u540E\u518D\u68C0\u67E5\u4E00\u6B21\u3002",
         badToken: "\u8FD9\u4E0D\u50CF\u673A\u5668\u4EBA\u7684 token\u3002\u5230 BotFather \u91CD\u65B0\u590D\u5236\u4E00\u4EFD\uFF1A\u6570\u5B57\u3001\u5192\u53F7\uFF0C\u540E\u9762\u662F\u5BC6\u94A5\u3002",
         unauthorized: "Telegram \u4E0D\u8BA4\u8FD9\u4E2A token\uFF0C\u53EF\u80FD\u5DF2\u7ECF\u4F5C\u5E9F\u3002\u5230 BotFather \u53D6\u73B0\u5728\u7684\u90A3\u4E00\u4EFD\u3002\u6539\u597D\u540E\u5728\u8FD9\u91CC\u4FDD\u5B58\uFF0C\u673A\u5668\u4EBA\u4F1A\u81EA\u52A8\u91CD\u65B0\u8FDE\u63A5\uFF1B\u6CA1\u6709\u8981\u6539\u7684\u4E5F\u53EF\u4EE5\u70B9\u4E0B\u65B9\u7684\u300C\u91CD\u65B0\u8FDE\u63A5\u300D\u3002",
@@ -146856,11 +146996,11 @@ var makeConclusionRecovery = (core, ledger, delivery, failures) => {
     enqueueConclusion(core, ledger, binding, selection, async (owed) => {
       try {
         if (turn.state === "error") {
-          const detail = execution.latestTurn?.state === "error" && execution.latestTurn.turnId === turn.turnId ? execution.session?.lastError : void 0;
+          const session = execution.latestTurn?.state === "error" && execution.latestTurn.turnId === turn.turnId ? execution.session : void 0;
           return delivery.sendText(
             binding,
             debt.threadId,
-            failures.forFailure(debt.threadId, detail),
+            failures.forFailure(debt.threadId, session?.lastError, session?.failureCategory),
             true,
             turn.turnId,
             owed
@@ -146978,7 +147118,7 @@ var makeNotifications = (core, deps) => {
         (debt) => debt.threadId === threadId
       );
       const { selection, handled, execution } = said || owes || targets.length > 0 ? await conclusions.forTurn(threadId) : { selection: void 0, handled: false, execution: null };
-      if (selection !== void 0) {
+      if (selection !== void 0 && selection !== null) {
         const binding = bindingForChatKey(selection.debt.chatKey);
         if (binding !== void 0 && !streamsTo(binding, threadId) && execution?.session?.activeTurnId == null && execution?.latestTurn?.state !== "running" && execution?.latestTurn?.state !== "error" && payload.session?.status !== "error") {
           const turnId = execution?.latestTurn?.turnId ?? null;
@@ -146987,7 +147127,7 @@ var makeNotifications = (core, deps) => {
             return send(binding, { recovered: false, streaming: false, owed });
           });
         }
-      } else if (said && !handled) {
+      } else if (selection !== null && said && !handled) {
         const send = await delivery.prepareConclusion(threadId);
         for (const binding of targets) {
           const streaming = streamsTo(binding, threadId);
@@ -147018,16 +147158,17 @@ var makeNotifications = (core, deps) => {
     await ready;
     const targets = targetsForProject(threadId, await projectOfThread(threadId));
     const { selection, handled, execution } = await conclusions.forTurn(threadId);
-    const debtBinding = selection === void 0 ? void 0 : bindingForChatKey(selection.debt.chatKey);
-    const recipients = selection !== void 0 ? debtBinding === void 0 ? [] : [debtBinding] : targets;
-    const textTargets = handled ? [] : recipients.filter(
+    const debtBinding = selection == null ? void 0 : bindingForChatKey(selection.debt.chatKey);
+    const recipients = selection == null ? targets : debtBinding === void 0 ? [] : [debtBinding];
+    const textTargets = handled || selection === null ? [] : recipients.filter(
       (binding) => !(streamsTo(binding, threadId) && turnCards.covers(threadId))
     );
     const drawingTurn = turnCards.drawingTurn(threadId);
-    const notice = textTargets.length > 0 || drawingTurn !== null ? failures.forFailure(threadId, readThreadFailed(event)?.detail) : null;
+    const failure2 = readThreadFailed(event);
+    const notice = textTargets.length > 0 || drawingTurn !== null ? failures.forFailure(threadId, failure2?.detail, failure2?.failureCategory) : null;
     if (notice !== null && drawingTurn !== null)
       failures.holdForCard(threadId, drawingTurn, notice);
-    if (notice !== null) {
+    if (notice !== null && selection !== null) {
       for (const binding of textTargets) {
         const send = (owed) => delivery.sendText(binding, threadId, notice, false, null, owed);
         enqueueConclusion(core, conclusions, binding, selection, send);
@@ -147602,6 +147743,17 @@ var makeProjectRows = (core) => {
 };
 
 // src/failureNotices.ts
+var PROVIDER_FAILURES = {
+  quota: { code: "MODEL_QUOTA", messageKey: "reply.turnFailedQuota" },
+  "rate-limit": { code: "MODEL_RATE_LIMIT", messageKey: "reply.turnFailedRateLimit" },
+  "context-limit": { code: "MODEL_CONTEXT_LIMIT", messageKey: "reply.turnFailedContextLimit" },
+  auth: { code: "MODEL_AUTH", messageKey: "reply.turnFailedAuth" },
+  "model-unavailable": {
+    code: "MODEL_UNAVAILABLE",
+    messageKey: "reply.turnFailedModelUnavailable"
+  },
+  transport: { code: "MODEL_TRANSPORT", messageKey: "reply.turnFailedTransport" }
+};
 var excerptSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 var graphemeExcerpt = (value2) => {
   const characters = Array.from(
@@ -147639,9 +147791,20 @@ var makeFailureNotices = (core) => {
       return core.t("reply.turnRetrying", { ref: reference2 });
     },
     /** 一次失败通知的那句话（带新参考号，同号进日志）：实时失败事件与重启补发各取一次。 */
-    forFailure: (threadId, detail) => {
+    forFailure: (threadId, detail, category) => {
       const reference2 = diagnosticRef("msg");
-      core.host.log.warn("chat turn failed", { threadId, reference: reference2 });
+      const failure2 = category === void 0 || category === "unknown" ? null : PROVIDER_FAILURES[category];
+      core.host.log.warn("chat turn failed", {
+        threadId,
+        reference: reference2,
+        code: failure2?.code ?? null,
+        detail
+      });
+      if (failure2 !== null)
+        return core.t("reply.turnFailedWithReference", {
+          message: core.t(failure2.messageKey),
+          ref: reference2
+        });
       const said = reasonOf2(detail);
       const text4 = said === "" ? core.t("reply.turnFailedNoDetail", { ref: reference2 }) : core.t("reply.turnFailed", { detail: said, ref: reference2 });
       return text4;
@@ -147654,11 +147817,13 @@ var makeFailureNotices = (core) => {
      * 卡收尾（无论怎么收的都调）：清掉这条会话的寄存。失败收尾时，寄存是这一轮的就用它（同一个号），
      * 否则只写原因与下一步，不另取号。不是失败收尾回 null。
      */
-    forCard: (threadId, turnId, detail, failed) => {
+    forCard: (threadId, turnId, detail, failed, category) => {
       const held = heldForCard.get(threadId);
       heldForCard.delete(threadId);
       if (!failed) return null;
       if (held !== void 0 && held.turnId === turnId) return held.text;
+      if (category !== void 0 && category !== "unknown")
+        return core.t(PROVIDER_FAILURES[category].messageKey);
       const said = reasonOf2(detail);
       return said === "" ? core.t("reply.turnFailedBriefNoDetail") : core.t("reply.turnFailedBrief", { detail: said });
     }
@@ -148009,7 +148174,8 @@ var makeReplyCards = (core, failures, anchors, conclusions, delivery) => {
         threadId,
         turnId,
         session?.lastError,
-        outcome === "failed"
+        outcome === "failed",
+        session?.failureCategory
       );
       if (errorText2 !== null) return { status: "error", errorText: errorText2 };
       if (stopped || outcome === "stopped") {
@@ -148022,6 +148188,7 @@ var makeReplyCards = (core, failures, anchors, conclusions, delivery) => {
     finalize: async (threadId, turnId, chatKey, send) => {
       const { selection, handled } = await conclusions.forTurn(threadId, turnId);
       if (handled) return true;
+      if (selection === null) return false;
       if (selection === void 0) return send();
       if (!await conclusions.deliver(selection, send)) return false;
       const binding = bindingForChatKey(chatKey);
@@ -148032,7 +148199,7 @@ var makeReplyCards = (core, failures, anchors, conclusions, delivery) => {
     },
     fallback: async (threadId, turnId, chatKey, view) => {
       const { selection, handled } = await conclusions.forTurn(threadId, turnId);
-      if (handled) return;
+      if (handled || selection === null) return;
       const binding = bindingForChatKey(chatKey);
       if (binding === void 0) return;
       const text4 = [view.body, view.errorText ?? ""].filter((part) => part !== "").join("\n\n");
@@ -148499,12 +148666,14 @@ import * as NodeCrypto6 from "node:crypto";
 // src/telegramApiResponse.ts
 var TelegramApiError = class extends Error {
   code;
+  status;
   /** 限流（429）时平台给的等待秒数；别的错误没有。 */
   retryAfterSeconds;
-  constructor(method, code2, description, retryAfterSeconds) {
-    super(`telegram ${method} failed (${String(code2 ?? "?")}): ${description}`);
+  constructor(method, code2, description, retryAfterSeconds, options) {
+    super(`telegram ${method} failed (${String(code2 ?? "?")}): ${description}`, options);
     this.name = "TelegramApiError";
     this.code = code2;
+    this.status = options?.status;
     this.retryAfterSeconds = retryAfterSeconds;
   }
 };
@@ -148519,7 +148688,8 @@ var readTelegramResponse = async (method, response) => {
       method,
       response.status === 401 ? 401 : envelope?.error_code ?? (response.ok ? void 0 : response.status),
       envelope?.description ?? "no reason",
-      envelope?.parameters?.retry_after
+      envelope?.parameters?.retry_after,
+      { status: response.status }
     );
   }
   return envelope.result;
@@ -148653,7 +148823,13 @@ var makeTelegramApi = (input) => {
       return await input.http(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
     } catch (error) {
       if (error instanceof Error && error.name === "TimeoutError") {
-        throw new TelegramApiError(method, void 0, `timed out after ${String(timeoutMs)} ms`);
+        throw new TelegramApiError(
+          method,
+          void 0,
+          `timed out after ${String(timeoutMs)} ms`,
+          void 0,
+          { cause: error }
+        );
       }
       throw error;
     }
@@ -148878,6 +149054,98 @@ var TELEGRAM_MENU = [
 ];
 var telegramCommandMenu = (t) => TELEGRAM_MENU.map((item) => ({ command: item.command, description: t(item.key) }));
 
+// src/telegramConnectionCheck.ts
+var webhookHost = (url) => {
+  try {
+    return new URL(url).host;
+  } catch {
+    return "(unreadable)";
+  }
+};
+var NOT_BOT_DETAIL = "token is not a bot's";
+var webhookActiveDetail = (url) => `webhook is set (host ${webhookHost(url)})`;
+var transportFailure = (stage, error) => ({
+  ok: false,
+  stage,
+  detail: describeError(error),
+  error
+});
+var probeTelegramBot = async (api) => {
+  let own;
+  try {
+    own = await api.getMe();
+  } catch (error) {
+    return transportFailure("getMe", error);
+  }
+  if (own.is_bot !== true) {
+    return { ok: false, stage: "getMe", hint: "notBot", detail: NOT_BOT_DETAIL };
+  }
+  let webhook = "";
+  try {
+    webhook = (await api.getWebhookInfo()).url ?? "";
+  } catch (error) {
+    return transportFailure("getWebhookInfo", error);
+  }
+  if (webhook !== "") {
+    return {
+      ok: false,
+      stage: "getWebhookInfo",
+      hint: "webhookActive",
+      detail: webhookActiveDetail(webhook)
+    };
+  }
+  return { ok: true, username: own.username, id: own.id };
+};
+var TelegramConnectGateError = class extends Error {
+  hint;
+  constructor(hint, detail) {
+    super(detail);
+    this.name = "TelegramConnectGateError";
+    this.hint = hint;
+  }
+};
+var assertTelegramPollingReady = async (api) => {
+  const probed = await probeTelegramBot(api);
+  if (!probed.ok) {
+    if ("error" in probed) throw probed.error;
+    throw new TelegramConnectGateError(probed.hint, probed.detail);
+  }
+  return { username: probed.username ?? null, id: probed.id };
+};
+var telegramPollingFailureHint = (error) => error instanceof TelegramConnectGateError ? error.hint : error instanceof TelegramApiError && error.code === 409 ? "webhookActive" : void 0;
+var checkTelegramConnection = async (bot, token, apiFor) => {
+  if (token === "") {
+    return { stage: "credentials", ok: false, detail: "missing bot token in saved config" };
+  }
+  if (!isTelegramToken(token)) {
+    return {
+      stage: "token-format",
+      ok: false,
+      detail: "saved token is not in the BotFather format",
+      hint: "badToken"
+    };
+  }
+  const api = await apiFor(bot);
+  const probed = await probeTelegramBot(api);
+  if (probed.ok) {
+    const name = probed.username;
+    const username = name !== void 0 && name !== "" ? `@${name}` : "(no username)";
+    return { stage: "getMe", ok: true, detail: `username=${username} webhook=none` };
+  }
+  if ("error" in probed) {
+    return {
+      stage: probed.stage,
+      ok: false,
+      detail: probed.detail,
+      ...connectionHintFields(
+        probed.error,
+        probed.stage === "getMe" && isTelegramCredentialsRejected(probed.error) ? "unauthorized" : void 0
+      )
+    };
+  }
+  return { stage: probed.stage, ok: false, detail: probed.detail, hint: probed.hint };
+};
+
 // src/telegramChoice.ts
 var renderChoiceCard = (card) => ({
   text: [card.title, card.heading ?? "", card.body, card.note ?? ""].filter((part) => part !== "").join("\n\n"),
@@ -149069,15 +149337,13 @@ var tokenFingerprint = (bot) => NodeCrypto6.createHash("sha256").update(tokenOf(
 var REACTION_WORKING = "\u{1F440}";
 var REACTION_DONE = "\u{1F44D}";
 var REACTION_FAILED = "\u{1F44E}";
-var telegramConfigIssues = (binding) => tokenOf(binding) === "" ? [{ column: "telegramToken", code: "required" }] : [];
-var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
-var webhookHost = (url) => {
-  try {
-    return new URL(url).host;
-  } catch {
-    return "(unreadable)";
-  }
+var telegramConfigIssues = (binding) => {
+  const token = tokenOf(binding);
+  if (token === "") return [{ column: "telegramToken", code: "required" }];
+  if (!isTelegramToken(token)) return [{ column: "telegramToken", code: "format" }];
+  return [];
 };
+var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 var makeTelegramAdapter = (deps) => {
   const apis = /* @__PURE__ */ new Map();
   const sleep4 = deps.sleep ?? defaultSleep;
@@ -149179,7 +149445,7 @@ var makeTelegramAdapter = (deps) => {
     quotesReplies: true,
     columns: COLUMNS2,
     validate: telegramConfigIssues,
-    isConfigured: (binding) => telegramConfigIssues(binding).length === 0,
+    isConfigured: (binding) => telegramConfigIssues(binding).every((issue) => issue.code !== "required"),
     connect: async (binding, handlers) => {
       let stop = () => {
       };
@@ -149217,8 +149483,8 @@ var makeTelegramAdapter = (deps) => {
             liveApi = api;
             if (!running) return;
             if (botUsername == null) {
-              const own = await api.getMe();
-              botUsername = own.username ?? null;
+              const own = await assertTelegramPollingReady(api);
+              botUsername = own.username;
               botId = own.id;
               if (running) handlers.onConnectionState?.({ state: "connected" });
             }
@@ -149344,7 +149610,12 @@ var makeTelegramAdapter = (deps) => {
               });
               return;
             }
-            if (checkingConnection) handlers.onConnectionState?.({ state: "failed", error });
+            if (checkingConnection)
+              handlers.onConnectionState?.({
+                state: "failed",
+                error,
+                ...connectionHintFields(error, telegramPollingFailureHint(error))
+              });
             handlers.onError(error instanceof Error ? error.message : String(error));
             await Promise.race([(deps.sleep ?? defaultSleep)(backoff), stopped]);
             backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
@@ -149366,50 +149637,7 @@ var makeTelegramAdapter = (deps) => {
       const api = await apiFor(binding);
       await api.sendMessage(binding.chatId, text4, options?.retry, binding.reply?.messageId);
     },
-    checkConnection: async (bot) => {
-      const token = tokenOf(bot);
-      if (token === "") {
-        return { stage: "credentials", ok: false, detail: "missing bot token in saved config" };
-      }
-      if (!isTelegramToken(token)) {
-        return {
-          stage: "token-format",
-          ok: false,
-          detail: "saved token is not in the BotFather format",
-          hint: "badToken"
-        };
-      }
-      const api = await apiFor(bot);
-      let username;
-      try {
-        const me = await api.getMe();
-        if (me.is_bot !== true) {
-          return { stage: "getMe", ok: false, detail: "token is not a bot's", hint: "notBot" };
-        }
-        username = me.username !== void 0 && me.username !== "" ? `@${me.username}` : "(no username)";
-      } catch (error) {
-        return {
-          stage: "getMe",
-          ok: false,
-          detail: describeError(error),
-          ...isTelegramCredentialsRejected(error) ? { hint: "unauthorized" } : {}
-        };
-      }
-      try {
-        const webhook = (await api.getWebhookInfo()).url ?? "";
-        if (webhook !== "") {
-          return {
-            stage: "getWebhookInfo",
-            ok: false,
-            detail: `webhook is set (host ${webhookHost(webhook)})`,
-            hint: "webhookActive"
-          };
-        }
-      } catch (error) {
-        return { stage: "getWebhookInfo", ok: false, detail: describeError(error) };
-      }
-      return { stage: "getMe", ok: true, detail: `username=${username} webhook=none` };
-    },
+    checkConnection: (bot) => checkTelegramConnection(bot, tokenOf(bot), apiFor),
     sendTyping: async (binding) => {
       await (await apiFor(binding)).sendTyping(binding.chatId);
     },
@@ -150150,7 +150378,13 @@ var probe = async (adapters, bot) => {
       result2.hint
     );
   } catch (error) {
-    return reportOf(bot, "check", false, redactor.redact(describeError(error)));
+    return reportOf(
+      bot,
+      "check",
+      false,
+      redactor.redact(describeError(error)),
+      connectionHint(error)
+    );
   }
 };
 var emitReport = (emit, report, action) => {
@@ -150676,6 +150910,16 @@ var makeWechatAdapter = (deps) => {
   };
 };
 
+// src/wecomAckError.ts
+var WecomAckError = class extends Error {
+  code;
+  constructor(code2, msg) {
+    super(`WeCom ack failed: ${String(code2)} ${msg}`);
+    this.name = "WecomAckError";
+    this.code = code2;
+  }
+};
+
 // src/wecomUpload.ts
 import * as NodeCrypto8 from "node:crypto";
 var WECOM_CHUNK_BYTES = 512 * 1024;
@@ -150888,15 +151132,12 @@ var parseWecomMessage = (frame, botId) => {
   };
 };
 var splitForWecom = (text4, limit = WECOM_TEXT_MAX_CHARS) => splitMessage(text4, limit);
-var decoder = new TextDecoder();
-var WecomAckError = class extends Error {
-  code;
-  constructor(code2, msg) {
-    super(`WeCom ack failed: ${String(code2)} ${msg}`);
-    this.name = "WecomAckError";
-    this.code = code2;
+var sendWecomText = async (text4, sendChunk) => {
+  for (const [index, content] of splitForWecom(text4).entries()) {
+    await sendChunk(content, index === 0);
   }
 };
+var decoder = new TextDecoder();
 var subscriptionHint = (error) => {
   if (!(error instanceof WecomAckError)) return void 0;
   switch (error.code) {
@@ -151029,41 +151270,39 @@ var runWecomClient = (input) => {
       return false;
     }
   );
-  const sendText = async (chatId, text4) => {
-    for (const [index, content] of splitForWecom(text4).entries()) {
-      const inboundRequestId = index === 0 ? pendingRequests.get(chatId) : void 0;
-      if (inboundRequestId !== void 0) {
-        pendingRequests.delete(chatId);
-        await send({
-          cmd: "aibot_respond_msg",
-          headers: { req_id: inboundRequestId },
-          body: {
-            msgtype: "stream",
-            stream: { id: nextRequestId("stream"), finish: true, content }
-          }
-        });
-        continue;
-      }
-      const requestId = nextRequestId("aibot_send_msg");
-      const ack = new Promise((resolve2, reject) => {
-        pendingAcks.set(requestId, { resolve: () => resolve2(), reject });
-        setTimeout(() => {
-          if (pendingAcks.delete(requestId)) resolve2();
-        }, SEND_ACK_TIMEOUT_MS);
+  const sendTextChunk = async (chatId, content, firstChunk) => {
+    const inboundRequestId = firstChunk ? pendingRequests.get(chatId) : void 0;
+    if (inboundRequestId !== void 0) {
+      pendingRequests.delete(chatId);
+      await send({
+        cmd: "aibot_respond_msg",
+        headers: { req_id: inboundRequestId },
+        body: {
+          msgtype: "stream",
+          stream: { id: nextRequestId("stream"), finish: true, content }
+        }
       });
-      try {
-        await Promise.all([
-          send({
-            cmd: "aibot_send_msg",
-            headers: { req_id: requestId },
-            body: { chatid: chatId, msgtype: "markdown", markdown: { content } }
-          }),
-          ack
-        ]);
-      } catch (error) {
-        pendingAcks.delete(requestId);
-        throw error;
-      }
+      return;
+    }
+    const requestId = nextRequestId("aibot_send_msg");
+    const ack = new Promise((resolve2, reject) => {
+      pendingAcks.set(requestId, { resolve: () => resolve2(), reject });
+      setTimeout(() => {
+        if (pendingAcks.delete(requestId)) resolve2();
+      }, SEND_ACK_TIMEOUT_MS);
+    });
+    try {
+      await Promise.all([
+        send({
+          cmd: "aibot_send_msg",
+          headers: { req_id: requestId },
+          body: { chatid: chatId, msgtype: "markdown", markdown: { content } }
+        }),
+        ack
+      ]);
+    } catch (error) {
+      pendingAcks.delete(requestId);
+      throw error;
     }
   };
   const request = async (cmd, body) => {
@@ -151140,7 +151379,8 @@ var runWecomClient = (input) => {
     };
   };
   return {
-    sendText,
+    sendText: (chatId, text4) => sendWecomText(text4, (content, firstChunk) => sendTextChunk(chatId, content, firstChunk)),
+    sendTextChunk,
     sendMedia,
     rememberConversation: (chatId, conversation) => {
       conversations.set(chatId, conversation);
@@ -151245,6 +151485,38 @@ var fetchWecomMedia = async (input) => {
   return { bytes, name };
 };
 
+// src/wecomSendError.ts
+var WecomSendError = class extends Error {
+  operation;
+  code;
+  providerCode;
+  constructor(cause, operation, code2, providerCode) {
+    super(
+      providerCode === void 0 && cause instanceof Error ? cause.message : `WeCom ${operation} failed (${code2}, provider=${providerCode ?? "-"})`,
+      { cause }
+    );
+    this.name = "WecomSendError";
+    this.operation = operation;
+    this.code = code2;
+    this.providerCode = providerCode;
+  }
+};
+var wecomSendError = (error, operation) => {
+  if (error instanceof ImNotConnectedError || error instanceof WecomSendError || error instanceof Error && error.name === "AbortError" || error instanceof TypeError || error instanceof ReferenceError || error instanceof SyntaxError)
+    return error;
+  const providerCode = error instanceof WecomAckError ? error.code : void 0;
+  let code2 = providerCode === void 0 ? "channel-delivery-uncertain" : "channel-delivery-failed";
+  if (providerCode === 48002) code2 = "channel-permission";
+  if (providerCode === 45009) code2 = "channel-rate-limit";
+  return new WecomSendError(error, operation, code2, providerCode);
+};
+var wecomSendDiagnostic = (error) => error instanceof WecomSendError ? {
+  operation: error.operation,
+  code: error.code,
+  providerCode: error.providerCode
+} : void 0;
+var wecomSendVerdict = (error) => error instanceof ImNotConnectedError || error instanceof WecomSendError && error.code === "channel-rate-limit" ? { retry: true } : NO_RETRY;
+
 // src/wecomAdapter.ts
 var WECOM_CARD_THROTTLE_MS = 400;
 var LIVE_STREAM_LIMIT = 200;
@@ -151271,6 +151543,16 @@ var makeWecomAdapter = (deps) => {
   const clients = /* @__PURE__ */ new Map();
   const managedConnections = /* @__PURE__ */ new Map();
   const t = deps.translate;
+  const sending = async (operation, request) => {
+    try {
+      return await request();
+    } catch (error) {
+      const failure2 = wecomSendError(error, operation);
+      const diagnostic = wecomSendDiagnostic(failure2);
+      if (diagnostic !== void 0) deps.log.warn("wecom send failed", diagnostic);
+      throw failure2;
+    }
+  };
   const liveStreams = /* @__PURE__ */ new Map();
   const rememberStream = (key, entry) => {
     liveStreams.set(key, entry);
@@ -151291,19 +151573,19 @@ var makeWecomAdapter = (deps) => {
         shown = `${t("card.truncated", { count: body.length - kept.length })}
 ${kept}`;
       }
-      await entry.stream.send(joinParts(head, shown, foot), false);
+      await sending("replyStream", () => entry.stream.send(joinParts(head, shown, foot), false));
       return;
     }
     const chunks = splitForWecom(joinParts(head, body, foot));
-    const delivered = await entry.stream.send(chunks[0] ?? "", true);
+    const delivered = await sending("replyStream", () => entry.stream.send(chunks[0] ?? "", true));
     for (const chunk of delivered ? chunks.slice(1) : chunks) {
-      await entry.client.sendText(entry.chatId, chunk);
+      await sending("sendMessage", () => entry.client.sendText(entry.chatId, chunk));
     }
   };
   const sendMedia = async (binding, kind, media) => {
     const client = clients.get(binding.rowId);
     if (client === void 0) throw new Error("WeCom is not connected right now");
-    await client.sendMedia(binding.chatId, kind, media);
+    await sending("sendMedia", () => client.sendMedia(binding.chatId, kind, media));
     deps.log.info("wecom delivered a file", { name: media.name, as: kind });
   };
   return {
@@ -151418,13 +151700,26 @@ ${kept}`;
         }
       };
     },
-    // 不看 `options.retry`：长连接的回执没有核实过的限流码，也没有幂等键，失败一律说不清发没发出去。
-    sendText: async (binding, text4) => {
-      const client = clients.get(binding.rowId);
-      if (client === void 0) {
-        throw new ImNotConnectedError(`wecom bot '${binding.displayName}' has no connection.`);
-      }
-      await client.sendText(binding.chatId, text4);
+    sendText: async (binding, text4, options) => {
+      await sendWecomText(
+        text4,
+        (chunk, firstChunk) => sendWithRetry(
+          async () => {
+            const client = clients.get(binding.rowId);
+            if (client === void 0) {
+              throw new ImNotConnectedError(
+                `wecom bot '${binding.displayName}' has no connection.`
+              );
+            }
+            await sending(
+              "sendMessage",
+              () => client.sendTextChunk(binding.chatId, chunk, firstChunk)
+            );
+          },
+          wecomSendVerdict,
+          options?.retry
+        )
+      );
     },
     checkConnection: async (bot) => {
       const managed = managedConnections.get(bot.rowId);
@@ -151498,7 +151793,10 @@ ${kept}`;
       }
     },
     askApproval: async (binding, request) => {
-      await (clients.get(binding.rowId)?.sendText(binding.chatId, numberedApprovalText(request)) ?? Promise.resolve());
+      const client = clients.get(binding.rowId);
+      const text4 = numberedApprovalText(request);
+      if (client !== void 0)
+        await sending("sendMessage", () => client.sendText(binding.chatId, text4));
       return null;
     },
     turnCards: {
@@ -151555,6 +151853,7 @@ var REQUEST_TIMEOUT_MS = 15e3;
 var MEDIA_TIMEOUT_MS = 6e4;
 var WecomAppApiError = class extends Error {
   code;
+  status;
   providerCode;
   hint;
   invalidUsers;
@@ -151562,6 +151861,7 @@ var WecomAppApiError = class extends Error {
     super(message);
     this.name = "WecomAppApiError";
     this.code = code2;
+    this.status = extras?.status;
     this.providerCode = extras?.providerCode;
     this.hint = extras?.hint;
     this.invalidUsers = extras?.invalidUsers ?? [];
@@ -151771,30 +152071,31 @@ var WecomAppApi = class {
       });
     }
   }
-  #apiError(errcode, errmsg, invalidUsers) {
+  #apiError(errcode, errmsg, invalidUsers, status) {
     const code2 = String(errcode);
+    const details = { providerCode: code2, status };
     const message = typeof errmsg === "string" && errmsg !== "" ? `WeCom API failed (${code2}): ${errmsg}` : `WeCom API failed (${code2}).`;
     if (TOKEN_INVALID_CODES.has(code2)) this.invalidateToken();
     if (errcode === 60020) {
       return new WecomAppApiError("trusted-ip", "WeCom rejected the outbound IP (errcode 60020).", {
-        providerCode: code2,
+        ...details,
         hint: "wecomTrustedIp"
       });
     }
     if (errcode === 81013) {
       return new WecomAppApiError("invalid-user", message, {
-        providerCode: code2,
+        ...details,
         hint: "wecomInvalidUser",
         invalidUsers: parseInvalidUsers(invalidUsers)
       });
     }
     if (errcode === 40056) {
       return new WecomAppApiError("invalid-agent", message, {
-        providerCode: code2,
+        ...details,
         hint: "wecomInvalidAgent"
       });
     }
-    return new WecomAppApiError("api-failed", message, { providerCode: code2 });
+    return new WecomAppApiError("api-failed", message, details);
   }
   async #withRequest(url, init, timeoutMs, read) {
     const deadline = new AbortController();
@@ -151821,15 +152122,29 @@ var WecomAppApi = class {
       } catch {
         throw new WecomAppApiError(
           "bad-response",
-          `WeCom returned non-JSON (HTTP ${String(response.status)}).`
+          `WeCom returned non-JSON (HTTP ${String(response.status)}).`,
+          { status: response.status }
         );
       }
       if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
-        throw new WecomAppApiError("bad-response", "WeCom returned a non-object JSON body.");
+        throw new WecomAppApiError("bad-response", "WeCom returned a non-object JSON body.", {
+          status: response.status
+        });
       }
       const result2 = payload;
       const errcode = Number(result2["errcode"] ?? 0);
-      if (errcode !== 0) throw this.#apiError(errcode, result2["errmsg"], result2["invaliduser"]);
+      if (errcode !== 0) {
+        throw this.#apiError(errcode, result2["errmsg"], result2["invaliduser"], response.status);
+      }
+      if (!response.ok) {
+        throw new WecomAppApiError(
+          "bad-response",
+          `WeCom returned HTTP ${String(response.status)}.`,
+          {
+            status: response.status
+          }
+        );
+      }
       return result2;
     });
   }
@@ -152565,7 +152880,10 @@ var makeWecomAppAdapter = (deps) => {
           stage: "gettoken",
           ok: false,
           detail: describeError(error),
-          ...error instanceof WecomAppApiError && error.hint !== void 0 ? { hint: error.hint } : {}
+          ...connectionHintFields(
+            error,
+            error instanceof WecomAppApiError ? error.hint : void 0
+          )
         };
       }
     },
@@ -152584,7 +152902,7 @@ var makeWecomAppAdapter = (deps) => {
       const report = (state) => {
         if (closed) return;
         handlers.onConnectionState?.(
-          state.state === "failed" && state.error instanceof WecomAppApiError && state.error.hint !== void 0 ? { ...state, hint: state.error.hint } : state
+          state.state === "failed" && state.error instanceof WecomAppApiError && state.error.hint !== void 0 ? { ...state, hint: state.error.hint } : state.state === "failed" ? { ...state, ...connectionHintFields(state.error, state.hint) } : state
         );
       };
       apis.set(bot.rowId, { api, report });