chatccc 0.2.229 → 0.2.230

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.229",
+  "version": "0.2.230",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/session.test.ts

@@ -23,6 +23,12 @@ const mockStreamStates = new Map<string, {
   turnCount?: number;
   finalReplySentTurn?: number;
   finalReplySentAt?: number;
+  terminalError?: {
+    kind: "network_timeout" | "network" | "authentication" | "rate_limit" | "provider" | "process" | "resource" | "unknown";
+    title: string;
+    message: string;
+    occurredAt: number;
+  };
 }>();
 vi.mock("../stream-state.ts", () => ({
   readStreamState: async (sid: string) => {
@@ -35,6 +41,7 @@ vi.mock("../stream-state.ts", () => ({
       activity: state.activity,
       finalReplySentTurn: state.finalReplySentTurn,
       finalReplySentAt: state.finalReplySentAt,
+      terminalError: state.terminalError,
       autoEndedAt: state.autoEndedAt,
       status: state.status ?? "running",
       chunkCount: 0,
@@ -60,6 +67,12 @@ vi.mock("../stream-state.ts", () => ({
     turnCount?: number;
     finalReplySentTurn?: number;
     finalReplySentAt?: number;
+    terminalError?: {
+      kind: "network_timeout" | "network" | "authentication" | "rate_limit" | "provider" | "process" | "resource" | "unknown";
+      title: string;
+      message: string;
+      occurredAt: number;
+    };
   }) => {
     mockStreamStates.set(state.sessionId, {
       accumulatedContent: state.accumulatedContent,
@@ -70,6 +83,7 @@ vi.mock("../stream-state.ts", () => ({
       turnCount: state.turnCount,
       finalReplySentTurn: state.finalReplySentTurn,
       finalReplySentAt: state.finalReplySentAt,
+      terminalError: state.terminalError,
     });
   },
   createEmptyStreamState: (sid: string, cwd: string, tool: string, turnCount: number) => ({
@@ -510,6 +524,51 @@ describe("runAgentSession process monitor", () => {
     );
   });
 
+  it("persists and sends the root cause when the agent stream fails before producing output", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const platform = mockPlatform("feishu");
+    platform.cardCreate = vi.fn(async () => {
+      throw new Error("CardKit unavailable");
+    });
+    setSessionPlatform(platform);
+    bindChatToSession("sid-stream-error", "chat-stream-error");
+    recordLastActiveChat("sid-stream-error", "chat-stream-error");
+
+    const adapter: ToolAdapter = {
+      displayName: "CCC Agent",
+      sessionDescPrefix: "CCC Session:",
+      createSession: async () => ({ sessionId: "sid-stream-error" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "/tmp" }),
+      closeSession: async () => {},
+      prompt: async function* () {
+        throw new Error(
+          "Failed after 3 attempts. Last error: Cannot connect to API: " +
+          "Connect Timeout Error (timeout: 10000ms)",
+        );
+      },
+    };
+    _setAdapterForToolForTest("ccc", adapter);
+
+    const outcome = await runAgentSession(
+      "sid-stream-error",
+      "prompt",
+      platform,
+      "chat-stream-error",
+      Date.now(),
+      "ccc",
+    );
+
+    const state = mockStreamStates.get("sid-stream-error");
+    expect(outcome).toBe("error");
+    expect(state?.status).toBe("error");
+    expect(state?.terminalError?.kind).toBe("network_timeout");
+    expect(state?.terminalError?.message).toContain("已重试 3 次");
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-stream-error",
+      expect.stringContaining("网络连接超时"),
+    );
+  });
+
   it("recreates the progress card when the initial CardKit send fails", async () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const platform = mockPlatform("feishu");
@@ -1635,6 +1694,110 @@ describe("unified display loop terminal card update", () => {
     expect(displayCards.has("chat-auto-ended")).toBe(false);
   });
 
+  it("shows the stream root cause in the error card without a duplicate text notice", async () => {
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+
+    bindChatToSession("sid-network-error", "chat-network-error");
+    recordLastActiveChat("sid-network-error", "chat-network-error");
+    sessionInfoMap.set("chat-network-error", {
+      sessionId: "sid-network-error",
+      turnCount: 1,
+      lastContextTokens: 0,
+      startTime: 0,
+      tool: "ccc",
+    });
+    displayCards.set("chat-network-error", {
+      cardId: "card-network-error",
+      sequence: 1,
+      cardBusy: false,
+      cardCreatedAt: Date.now(),
+      lastSentContent: "",
+      streamErrorNotified: false,
+      sessionId: "sid-network-error",
+      turnCount: 1,
+      dotCount: 0,
+    });
+    mockStreamStates.set("sid-network-error", {
+      accumulatedContent: "",
+      finalReply: "",
+      status: "error",
+      turnCount: 1,
+      terminalError: {
+        kind: "network_timeout",
+        title: "网络连接超时",
+        message: "连接模型服务失败，已重试 3 次，单次连接等待 10 秒。请检查网络、VPN或模型服务状态后重试。",
+        occurredAt: Date.now(),
+      },
+    });
+
+    startUnifiedDisplayLoop();
+    await vi.advanceTimersByTimeAsync(3_000);
+
+    const payload = vi.mocked(platform.cardUpdate).mock.calls[0]?.[1];
+    const card = JSON.parse(payload as string) as {
+      header: { title: { content: string }; template?: string };
+      body: { elements: Array<{ content?: string }> };
+    };
+    expect(card.header.title.content).toBe("异常结束 · 网络连接超时");
+    expect(card.header.template).toBe("red");
+    expect(card.body.elements[0]?.content).toContain("已重试 3 次");
+    expect(platform.sendText).not.toHaveBeenCalled();
+    expect(mockStreamStates.get("sid-network-error")?.finalReplySentTurn).toBe(1);
+    expect(displayCards.has("chat-network-error")).toBe(false);
+  });
+
+  it("falls back to a root-cause text when the error card cannot be updated", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const platform = mockPlatform("feishu");
+    platform.cardUpdate = vi.fn(async () => {
+      throw new Error("CardKit unavailable");
+    });
+    setSessionPlatform(platform);
+
+    bindChatToSession("sid-error-fallback", "chat-error-fallback");
+    recordLastActiveChat("sid-error-fallback", "chat-error-fallback");
+    sessionInfoMap.set("chat-error-fallback", {
+      sessionId: "sid-error-fallback",
+      turnCount: 1,
+      lastContextTokens: 0,
+      startTime: 0,
+      tool: "ccc",
+    });
+    displayCards.set("chat-error-fallback", {
+      cardId: "card-error-fallback",
+      sequence: 1,
+      cardBusy: false,
+      cardCreatedAt: Date.now(),
+      lastSentContent: "",
+      streamErrorNotified: false,
+      sessionId: "sid-error-fallback",
+      turnCount: 1,
+      dotCount: 0,
+    });
+    mockStreamStates.set("sid-error-fallback", {
+      accumulatedContent: "",
+      finalReply: "",
+      status: "error",
+      turnCount: 1,
+      terminalError: {
+        kind: "network_timeout",
+        title: "网络连接超时",
+        message: "连接模型服务失败，已重试 3 次。",
+        occurredAt: Date.now(),
+      },
+    });
+
+    startUnifiedDisplayLoop();
+    await vi.advanceTimersByTimeAsync(3_000);
+
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-error-fallback",
+      expect.stringContaining("异常结束：网络连接超时"),
+    );
+    expect(displayCards.has("chat-error-fallback")).toBe(false);
+  });
+
   it("does not repeat the same terminal CardKit sequence while the prompt is still active", async () => {
     const platform = mockPlatform("feishu");
     platform.cardUpdate = vi.fn(async () => {

package/src/__tests__/terminal-error.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyTerminalError, formatTerminalErrorNotice } from "../terminal-error.ts";
+
+describe("terminal error classification", () => {
+  it("turns a retried connection timeout into an actionable root-cause summary", () => {
+    const error = classifyTerminalError(new Error(
+      "Failed after 3 attempts. Last error: Cannot connect to API: Connect Timeout Error " +
+      "(attempted addresses: 172.19.67.251:443, 172.19.68.1:443, timeout: 10000ms)",
+    ), 123);
+
+    expect(error).toEqual({
+      kind: "network_timeout",
+      title: "网络连接超时",
+      message: "连接模型服务失败，已重试 3 次，单次连接等待 10 秒。请检查网络、VPN或模型服务状态后重试。",
+      occurredAt: 123,
+    });
+    expect(JSON.stringify(error)).not.toContain("172.19.67.251");
+  });
+
+  it("redacts credentials from an otherwise unknown error", () => {
+    const error = classifyTerminalError(
+      new Error("custom provider rejected api_key=secret-value Bearer eyJ.private sk-live-secret"),
+      456,
+    );
+
+    expect(error.kind).toBe("unknown");
+    expect(error.message).toContain("custom provider rejected");
+    expect(error.message).not.toContain("secret-value");
+    expect(error.message).not.toContain("eyJ.private");
+    expect(error.message).not.toContain("sk-live-secret");
+  });
+
+  it("marks an existing reply as potentially incomplete", () => {
+    const error = classifyTerminalError(new Error("HTTP 429 rate limit"), 789);
+    const notice = formatTerminalErrorNotice(error, "partial answer");
+
+    expect(notice).toContain("请求受到限流");
+    expect(notice).toContain("以下回复可能不完整");
+    expect(notice).toContain("partial answer");
+  });
+
+  it.each([
+    ["HTTP 401 unauthorized", "authentication", "模型服务鉴权失败"],
+    ["HTTP 429 too many requests", "rate_limit", "请求受到限流"],
+    ["HTTP 503 service unavailable", "provider", "模型服务暂时不可用"],
+    ["getaddrinfo ENOTFOUND api.example.test", "network", "无法连接模型服务"],
+  ] as const)("classifies %s as %s", (message, kind, title) => {
+    const error = classifyTerminalError(new Error(message), 999);
+
+    expect(error.kind).toBe(kind);
+    expect(error.title).toBe(title);
+  });
+});

package/src/orchestrator.ts

@@ -2246,7 +2246,7 @@ export async function handleCommand(
 
     try {
       logTrace(tid, "RESUME", { sessionId, tool: descriptionTool });
-      await resumeAndPrompt(
+      const resumeOutcome = await resumeAndPrompt(
         sessionId,
         promptText,
         platform,
@@ -2255,8 +2255,13 @@ export async function handleCommand(
         descriptionTool,
         tid,
       );
-      logTrace(tid, "DONE", { outcome: "resume_done", sessionId });
-      console.log(`[${ts()}] [RESUME] Session ${sessionId} done`);
+      if (resumeOutcome === "error") {
+        logTrace(tid, "DONE", { outcome: "resume_error", sessionId });
+        console.error(`[${ts()}] [RESUME] Session ${sessionId} ended with an Agent error`);
+      } else {
+        logTrace(tid, "DONE", { outcome: "resume_done", sessionId, sessionOutcome: resumeOutcome });
+        console.log(`[${ts()}] [RESUME] Session ${sessionId} done (${resumeOutcome})`);
+      }
     } catch (err) {
       logTrace(tid, "DONE", {
         outcome: "resume_fail",

package/src/session.ts

@@ -43,6 +43,12 @@ import { resourceMonitor, registerProcess, unregisterProcess } from "./adapters/
 import { buildImSkillsPromptCached, exportSkillSubDocs, clearImSkillsPromptCache } from "./im-skills.ts";
 import type { PlatformAdapter } from "./platform-adapter.ts";
 import { hasResponseStalled, observeResponseProgress } from "./response-stall.ts";
+import {
+  classifyTerminalError,
+  formatTerminalErrorNotice,
+  formatTerminalErrorReason,
+  type TerminalErrorInfo,
+} from "./terminal-error.ts";
 import {
   MAX_PROCESSED,
   clearFeishuMessageLedgerMemory,
@@ -305,13 +311,18 @@ function scheduleFinalResponseCloseGuard(
   runningPrompt.finalResponseCloseTimer = handle;
 }
 
-function formatTerminalHeader(status: "running" | "done" | "stopped" | "error" | "auto_ended"): {
+function formatTerminalHeader(
+  status: "running" | "done" | "stopped" | "error" | "auto_ended",
+  terminalError?: TerminalErrorInfo,
+): {
   title: string;
   template?: string;
 } {
   if (status === "auto_ended") return { title: "已自动结束 · 3分钟无新内容", template: "orange" };
   if (status === "stopped") return { title: "已停止", template: "red" };
-  if (status === "error") return { title: "异常结束", template: "red" };
+  if (status === "error") {
+    return { title: terminalError ? `异常结束 · ${terminalError.title}` : "异常结束", template: "red" };
+  }
   return { title: "完成" };
 }
 
@@ -337,11 +348,42 @@ function monitorsOutputProgress(kind: AgentActivityKind): boolean {
 function formatTerminalReply(
   status: "running" | "done" | "stopped" | "error" | "auto_ended",
   finalReply: string,
+  terminalError?: TerminalErrorInfo,
 ): string | null {
   if (status === "auto_ended") return formatAutoEndedReply(finalReply);
+  if (status === "error") {
+    const error = terminalError ?? {
+      kind: "unknown" as const,
+      title: "原因未记录",
+      message: "当前状态中没有可用的错误详情，请查看运行日志。",
+      occurredAt: Date.now(),
+    };
+    return formatTerminalErrorNotice(error, finalReply);
+  }
   return finalReply || null;
 }
 
+function formatTerminalCardContent(state: {
+  status: "running" | "done" | "stopped" | "error" | "auto_ended";
+  accumulatedContent: string;
+  finalReply: string;
+  terminalError?: TerminalErrorInfo;
+}): string {
+  const content = state.accumulatedContent + state.finalReply;
+  if (state.status !== "error") return content;
+
+  const error = state.terminalError ?? {
+    kind: "unknown" as const,
+    title: "原因未记录",
+    message: "当前状态中没有可用的错误详情，请查看运行日志。",
+    occurredAt: Date.now(),
+  };
+  const reason = formatTerminalErrorReason(error);
+  return content.trim()
+    ? `${content}\n\n${reason}\n以上内容可能不完整。`
+    : reason;
+}
+
 function isCardKitSequenceConflict(err: unknown): boolean {
   return err instanceof Error && err.message.includes("300317");
 }
@@ -1110,7 +1152,7 @@ export async function resumeAndPrompt(
   msgTimestamp: number,
   tool: string,
   traceId?: string,
-): Promise<void> {
+): Promise<SessionRunOutcome> {
   return runAgentSession(sessionId, userText, platform, chatId, msgTimestamp, tool, traceId);
 }
 
@@ -1126,6 +1168,8 @@ interface RunAgentSessionOptions {
   autoRecovery?: boolean;
 }
 
+export type SessionRunOutcome = "busy" | "done" | "stopped" | "error" | "auto_ended";
+
 export async function runAgentSession(
   sessionId: string,
   userText: string,
@@ -1135,7 +1179,7 @@ export async function runAgentSession(
   tool: string,
   traceId?: string,
   options: RunAgentSessionOptions = {},
-): Promise<void> {
+): Promise<SessionRunOutcome> {
   const tid = traceId ?? "";
 
   // runAgentSession 是飞书用户消息、队列消息与内部自动恢复共同使用的唯一
@@ -1162,7 +1206,7 @@ export async function runAgentSession(
       ? "当前正在生成回复中，请等待完成后再发送消息。也可以发送 /stop 结束，已完成的步骤不会丢失。"
       : "该会话正在生成回复中，请等待完成后再发送消息。也可以发送 /stop 结束，已完成的步骤不会丢失。";
     await platform.sendText(_chatId, busyMsg).catch(() => {});
-    return;
+    return "busy";
   }
 
   // 立即标记活跃，确保 /sessions、isSessionRunning 等查询在异步准备阶段就能看到运行状态。
@@ -1290,7 +1334,7 @@ export async function runAgentSession(
   // 再开始缓存问题对应的任务"。
   const prevState = await readStreamState(sessionId);
   if (prevState && prevState.status !== "running") {
-    const prevTerminalReply = formatTerminalReply(prevState.status, prevState.finalReply);
+    const prevTerminalReply = formatTerminalReply(prevState.status, prevState.finalReply, prevState.terminalError);
     const displayChatId = pickDisplayChat(sessionId);
     if (displayChatId) {
       const pp = platformForChat(displayChatId);
@@ -1309,8 +1353,8 @@ export async function runAgentSession(
           setSessionChatAvatar(pp, displayChatId, prevState.tool, "idle", sessionId).catch(() => {});
         } else {
           const nextSeq = display.sequence + 1;
-          const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(prevState.status);
-          const cardContent = truncateContent(prevState.accumulatedContent + prevState.finalReply) || " ";
+          const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(prevState.status, prevState.terminalError);
+          const cardContent = truncateContent(formatTerminalCardContent(prevState)) || " ";
           const doneCard = buildProgressCard(progressView({ text: cardContent, status: "done", showStop: false, headerTitle, headerTemplate }));
           await pp.cardUpdate(display.cardId, doneCard, nextSeq).catch(err => {
             console.error(`[${ts()}] [DISPLAY] prevState final cardUpdate failed: ${(err as Error).message}`);
@@ -1405,6 +1449,8 @@ export async function runAgentSession(
   const FILE_WRITE_INTERVAL_MS = 2000;
   const toolCallMap = new Map<string, { name: string; input: unknown }>();
   let streamErrored = false;
+  let streamTerminalError: TerminalErrorInfo | undefined;
+  let runOutcome: SessionRunOutcome = "error";
 
   const runningPrompt = activePrompts.get(sessionId);
   if (runningPrompt) {
@@ -1580,6 +1626,7 @@ export async function runAgentSession(
     }
   } catch (streamErr) {
     streamErrored = true;
+    streamTerminalError = classifyTerminalError(streamErr);
     console.error(`[${ts()}] [STREAM] Error in stream loop for ${sessionId}: ${(streamErr as Error).message}`);
   } finally {
     // 标记 prompt 结束
@@ -1629,6 +1676,23 @@ export async function runAgentSession(
               ? "stopped"
               : "done";
       const finalReply = pickFinalReply(state).trim();
+      const terminalError = streamTerminalError
+        ?? (wasAbnormalExit
+          ? {
+              kind: "process" as const,
+              title: "Agent 进程意外退出",
+              message: "Agent CLI 进程已退出。若回复不完整，请重新发送上一条指令。",
+              occurredAt: Date.now(),
+            }
+          : wasResourceStuck
+            ? {
+                kind: "resource" as const,
+                title: "Agent 进程失去响应",
+                message: "Agent 进程长时间没有 CPU 或内存变化，已被强制停止。若回复不完整，请重新发送上一条指令。",
+                occurredAt: Date.now(),
+              }
+            : undefined);
+      runOutcome = finalStatus;
 
     // stop-stuck-loop 接口可能在 fire-and-forget 中已写入带 final_reply 的
     // stream state，finally 不应覆盖它。同时保留 stuckAt 标记，防止
@@ -1659,6 +1723,7 @@ export async function runAgentSession(
       tool,
       ...(preserveStuckAt ? { stuckAt: preserveStuckAt } : {}),
       ...(autoEndedAt !== undefined ? { autoEndedAt } : {}),
+      ...(terminalError ? { terminalError } : {}),
     });
 
     // display loop 下一轮会读到最终状态并发送消息
@@ -1749,6 +1814,52 @@ export async function runAgentSession(
       if (activeErr) setSessionChatAvatar(platform, activeErr, tool, "idle", sessionId).catch(() => {});
       console.log(`[${ts()}] Session ${sessionId} process exited unexpectedly (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "process_missing", chunks: state.chunkCount });
+    } else if (streamErrored || wasResourceStuck) {
+      for (const cid of finalizationChatIds) {
+        const finfo = sessionInfoMap.get(cid);
+        await recordSessionRegistry({
+          chatId: cid,
+          sessionId,
+          tool,
+          turnCount: finfo?.turnCount ?? nextTurnCount,
+          lastContextTokens: finfo?.lastContextTokens ?? nextContextTokens,
+          startTime: finfo?.startTime ?? now,
+          running: false,
+        });
+      }
+      const activeErr = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
+      if (activeErr) {
+        const pp = platformForChat(activeErr) ?? platform;
+        const terminalState = await readStreamState(sessionId);
+        if (
+          terminalError
+          && !displayCards.has(activeErr)
+          && (!terminalState || !isFinalReplySentForTurn(terminalState))
+        ) {
+          await sendFinalReplyTextOnce(
+            pp,
+            activeErr,
+            sessionId,
+            nextTurnCount,
+            formatTerminalErrorNotice(terminalError, finalReplyToWrite),
+          );
+        }
+        setSessionChatAvatar(pp, activeErr, tool, "idle", sessionId).catch(() => {});
+      }
+      const errorOutcome = wasResourceStuck ? "resource_stuck" : "stream_error";
+      console.error(
+        `[${ts()}] Session ${sessionId} ended with ${errorOutcome}` +
+        `${terminalError ? ` (${terminalError.kind}: ${terminalError.title})` : ""} (content chunks: ${state.chunkCount})`,
+      );
+      if (tid) {
+        logTrace(tid, "SESSION_END", {
+          sessionId,
+          outcome: errorOutcome,
+          errorKind: terminalError?.kind,
+          errorTitle: terminalError?.title,
+          chunks: state.chunkCount,
+        });
+      }
     } else {
       for (const cid of finalizationChatIds) {
         const finfo = sessionInfoMap.get(cid);
@@ -1862,6 +1973,7 @@ export async function runAgentSession(
       clearSessionFinalizing(sessionId);
     }
   }
+  return runOutcome;
 }
 
 // ---------------------------------------------------------------------------
@@ -1941,9 +2053,11 @@ export function startUnifiedDisplayLoop(): void {
               const tail = "━━━ 回答结束 ━━━";
               const finalMsg = state.status === "auto_ended"
                 ? formatAutoEndedReply(remaining)
-                : remaining
-                  ? remaining + "\n" + tail
-                  : tail;
+                : state.status === "error"
+                  ? formatTerminalReply(state.status, remaining, state.terminalError) ?? tail
+                  : remaining
+                    ? remaining + "\n" + tail
+                    : tail;
               if (!isFinalReplySentForTurn(state)) {
                 await sendFinalReplyTextOnce(p, chatId, sessionId, state.turnCount, finalMsg);
               }
@@ -1965,8 +2079,8 @@ export function startUnifiedDisplayLoop(): void {
               let terminalCardUpdateAccepted = terminalCardAlreadyUpdated;
               if (!terminalCardAlreadyUpdated) {
                 const nextSeq = display.sequence + 1;
-                const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(state.status);
-                const cardContent = truncateContent(state.accumulatedContent + state.finalReply) || " ";
+                const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(state.status, state.terminalError);
+                const cardContent = truncateContent(formatTerminalCardContent(state)) || " ";
                 const doneCard = buildProgressCard(progressView({ text: cardContent, status: "done", showStop: false, headerTitle, headerTemplate }));
                 await p.cardUpdate(display.cardId, doneCard, nextSeq).then(() => {
                   display.sequence = nextSeq;
@@ -1993,8 +2107,16 @@ export function startUnifiedDisplayLoop(): void {
               }
 
               let terminalTextDelivered = true;
-              const terminalReply = formatTerminalReply(state.status, state.finalReply);
-              if (terminalReply) {
+              const terminalReply = formatTerminalReply(state.status, state.finalReply, state.terminalError);
+              const errorWasDeliveredByCard =
+                state.status === "error"
+                && !state.finalReply.trim()
+                && terminalCardUpdateAccepted;
+              if (errorWasDeliveredByCard) {
+                if (!isFinalReplySentForTurn(state)) {
+                  await markFinalReplySent(sessionId, state.turnCount);
+                }
+              } else if (terminalReply) {
                 if (!isFinalReplySentForTurn(state)) {
                   terminalTextDelivered = await sendFinalReplyTextOnce(p, chatId, sessionId, state.turnCount, terminalReply);
                 }

package/src/stream-state.ts

@@ -1,9 +1,10 @@
 import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
-import { USER_DATA_DIR, ts } from "./config.ts";
-import { createAgentActivityTracker } from "./agent-activity.ts";
-import type { AgentActivity } from "./agent-activity.ts";
+import { USER_DATA_DIR, ts } from "./config.ts";
+import { createAgentActivityTracker } from "./agent-activity.ts";
+import type { AgentActivity } from "./agent-activity.ts";
+import type { TerminalErrorInfo } from "./terminal-error.ts";
 
 // ---------------------------------------------------------------------------
 // stream-state.json — 每个 session 的流式输出持久化文件
@@ -13,14 +14,14 @@ export const STREAMS_DIR = join(USER_DATA_DIR, "state", "streams");
 
 export interface StreamState {
   sessionId: string;
-  status: "running" | "done" | "stopped" | "error" | "auto_ended";
+  status: "running" | "done" | "stopped" | "error" | "auto_ended";
   accumulatedContent: string;
   /** 本轮会话中 LLM 输出的全部文本内容（所有 text block 的累加）。
    *  命名含 "final" 但实为"全部累积文本"，并非仅"最终一段回复"。
    *  参见 session.ts 的 AccumulatorState 注释。 */
-  finalReply: string;
-  /** Current user-visible work phase for running progress cards. */
-  activity?: AgentActivity;
+  finalReply: string;
+  /** Current user-visible work phase for running progress cards. */
+  activity?: AgentActivity;
   /** The turn whose terminal text reply has already been delivered to IM. */
   finalReplySentTurn?: number;
   finalReplySentAt?: number;
@@ -32,10 +33,12 @@ export interface StreamState {
   tool: string;
   /** Set by stop-stuck-loop to prevent the session from being resumed.
    *  The orchestrator checks this before resuming and creates a new session instead. */
-  stuckAt?: number;
-  /** Set when the shared response watchdog ends a turn after three minutes without new characters. */
-  autoEndedAt?: number;
-}
+  stuckAt?: number;
+  /** Set when the shared response watchdog ends a turn after three minutes without new characters. */
+  autoEndedAt?: number;
+  /** 脱敏后的用户可见根因；完整原始异常只保留在运行日志中。 */
+  terminalError?: TerminalErrorInfo;
+}
 
 function getStreamStatePath(sessionId: string): string {
   return join(STREAMS_DIR, `${sessionId}.json`);
@@ -128,18 +131,18 @@ export async function markFinalReplySent(sessionId: string, turnCount: number, s
   await writeStreamState(state);
 }
 
-export function createEmptyStreamState(sessionId: string, cwd: string, tool: string, turnCount: number): StreamState {
-  const now = Date.now();
-  return {
+export function createEmptyStreamState(sessionId: string, cwd: string, tool: string, turnCount: number): StreamState {
+  const now = Date.now();
+  return {
     sessionId,
     status: "running",
-    accumulatedContent: "",
-    finalReply: "",
-    activity: createAgentActivityTracker(now).activity,
+    accumulatedContent: "",
+    finalReply: "",
+    activity: createAgentActivityTracker(now).activity,
     chunkCount: 0,
     turnCount,
     contextTokens: 0,
-    updatedAt: now,
+    updatedAt: now,
     cwd,
     tool,
   };

package/src/terminal-error.ts

@@ -0,0 +1,129 @@
+/** 用户可见的终态错误。这里只保存脱敏摘要；完整原始异常继续只写运行日志。 */
+export type TerminalErrorKind =
+  | "network_timeout"
+  | "network"
+  | "authentication"
+  | "rate_limit"
+  | "provider"
+  | "process"
+  | "resource"
+  | "unknown";
+
+export interface TerminalErrorInfo {
+  kind: TerminalErrorKind;
+  title: string;
+  message: string;
+  occurredAt: number;
+}
+
+const MAX_UNKNOWN_ERROR_LENGTH = 300;
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * 未分类错误仍应给出可诊断线索，但不能把常见凭据带进群聊或持久化状态。
+ * 已分类错误使用固定文案，不复述地址、请求体或 provider 原始响应。
+ */
+export function sanitizeTerminalErrorDetail(raw: string): string {
+  return raw
+    .replace(/\bBearer\s+[^\s,;]+/gi, "Bearer [已脱敏]")
+    .replace(/\b(api[_-]?key|access[_-]?token|token|secret)\s*[:=]\s*[^\s,;]+/gi, "$1=[已脱敏]")
+    .replace(/\bsk-[A-Za-z0-9._-]{6,}\b/g, "sk-[已脱敏]")
+    .replace(/([?&](?:api[_-]?key|access[_-]?token|token|secret)=)[^&\s]+/gi, "$1[已脱敏]")
+    .slice(0, MAX_UNKNOWN_ERROR_LENGTH);
+}
+
+function parsePositiveInt(message: string, pattern: RegExp): number | undefined {
+  const value = Number.parseInt(message.match(pattern)?.[1] ?? "", 10);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function formatSeconds(milliseconds: number): string {
+  if (milliseconds % 1000 === 0) return `${milliseconds / 1000} 秒`;
+  return `${milliseconds} 毫秒`;
+}
+
+export function classifyTerminalError(error: unknown, occurredAt = Date.now()): TerminalErrorInfo {
+  const raw = errorMessage(error);
+  const lower = raw.toLowerCase();
+  const attempts = parsePositiveInt(raw, /\bafter\s+(\d+)\s+attempts?\b/i);
+  const timeoutMs = parsePositiveInt(raw, /\btimeout\s*:\s*(\d+)\s*ms\b/i);
+
+  if (/\b429\b|rate[ _-]?limit|too many requests/.test(lower)) {
+    return {
+      kind: "rate_limit",
+      title: "请求受到限流",
+      message: "模型服务请求受到限流，请稍后重试。",
+      occurredAt,
+    };
+  }
+
+  if (/\b401\b|\b403\b|unauthori[sz]ed|forbidden|invalid api key|authentication/.test(lower)) {
+    return {
+      kind: "authentication",
+      title: "模型服务鉴权失败",
+      message: "模型服务拒绝了当前凭据，请检查 API Key、账号权限或凭据是否过期。",
+      occurredAt,
+    };
+  }
+
+  if (
+    /connect timeout|connection timed out|etimedout|und_err_connect_timeout/.test(lower)
+    || (lower.includes("cannot connect") && lower.includes("timeout"))
+  ) {
+    const retryText = attempts ? `，已重试 ${attempts} 次` : "";
+    const timeoutText = timeoutMs ? `，单次连接等待 ${formatSeconds(timeoutMs)}` : "";
+    return {
+      kind: "network_timeout",
+      title: "网络连接超时",
+      message: `连接模型服务失败${retryText}${timeoutText}。请检查网络、VPN或模型服务状态后重试。`,
+      occurredAt,
+    };
+  }
+
+  if (/econnrefused|econnreset|enotfound|eai_again|socket hang up|network error|cannot connect/.test(lower)) {
+    return {
+      kind: "network",
+      title: "无法连接模型服务",
+      message: "与模型服务的网络连接失败，请检查网络、VPN、DNS或服务状态后重试。",
+      occurredAt,
+    };
+  }
+
+  const httpStatus = raw.match(/\b(?:HTTP\s*)?(5\d\d)\b/i)?.[1];
+  if (httpStatus || /service unavailable|bad gateway|gateway timeout|provider error/.test(lower)) {
+    return {
+      kind: "provider",
+      title: "模型服务暂时不可用",
+      message: `模型服务返回异常${httpStatus ? `（HTTP ${httpStatus}）` : ""}，请稍后重试。`,
+      occurredAt,
+    };
+  }
+
+  const safeDetail = sanitizeTerminalErrorDetail(raw).trim() || "未提供错误详情";
+  return {
+    kind: "unknown",
+    title: "Agent 执行错误",
+    message: `发生未分类错误：${safeDetail}`,
+    occurredAt,
+  };
+}
+
+export function formatTerminalErrorReason(error: TerminalErrorInfo): string {
+  return `⚠️ 异常结束：${error.title}\n${error.message}`;
+}
+
+export function formatTerminalErrorNotice(error: TerminalErrorInfo, finalReply = ""): string {
+  const reason = formatTerminalErrorReason(error);
+  return finalReply.trim()
+    ? `${reason}\n\n以下回复可能不完整：\n\n${finalReply.trim()}`
+    : reason;
+}