Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

115 KB
Raw Blame
import { collectNativeToolMedia, type NativeToolMedia } from '@cindy/maker-shared/tool-process-media';
/**
 * Claude Code SDKMessage → maker-core 语义 AgentEvent 翻译器。
 *
 * 设计来源:从 desktop apps/desktop/src/main/agentManager.ts:processMessage 搬迁,
 * 去掉 desktop-only 字段(LiveSession 状态机、token 计数累积、stderr 等)。
 * 翻译后的事件数据形状 byte-for-byte 与老 cc-agent:stream-event payload 对齐,
 * 让 renderer 的 ccAgentChatStore.handleStreamEvent 可以无修改消费。
 *
 * 一阶段限制:
 * - usage 详细累加不做(只在 message_delta 时输出 raw token 数,renderer 自己用什么算什么)
 * - tool_progress 状态文案字典不接(直接打 'Running...' 占位)
 *
 * Stage 2 C2: agentMeta 提取已接通 (handleAssistant 用 extractAssistantMeta),
 * rewind / fork 反向找 prior assistant 锚点要靠这个; ctx.rt.lastAssistantMeta
 * 跨 stream_event 兜底 (老链路 agentManager.ts:2214 同款)。
 */

import type { AgentEvent, AgentTaskStatus, AgentTaskUsage, AgentTaskUpdateEventData } from '../../types/events.js';
import { normalizeWorkflowProgressEntries } from '@cindy/maker-shared/agent-task';
import {
  extractNonSecretErrorSignals,
  GATEWAY_PROXY_TOKEN_INVALID_REASON,
  isCindyGatewayProxyTokenInvalidError,
  redactSensitiveText,
} from '@cindy/maker-shared/error-redaction';
import {
  holdStandaloneStopTokenDelta,
  stripInternalWebCitations,
  type StandaloneStopTokenHold,
} from '@cindy/maker-shared/internal-citation';
import type { createAsyncQueue } from '../shared/async-queue.js';
import { stripTerminalControlSequences } from '../shared/terminal-output.js';
import { formatOverloadRetryMessage, parseOverloadError } from '../shared/overload-error.js';
import {
  CONTEXT_OVERFLOW_REASON,
  isContextOverflowErrorMessage,
} from '../shared/context-overflow-error.js';
import type { UsageTracker } from '../shared/usage-tracker.js';
import { isModelAccessDenied } from './model-access-error.js';
import { attachLiveGeneration, sampleGenerationDuration } from '../shared/live-generation-snapshot.js';
import {
  beginClaudeGeneration,
  beginClaudeGenerationAtRequestStart,
  finalizeClaudeGeneration,
  markClaudeGenerationUnreliable,
  newClaudeGenerationState,
  noteClaudeParentStreamedOutputIncomplete,
  noteClaudeSubagent,
  pauseClaudeGeneration,
  resetClaudeGenerationTiming,
  resumeClaudeGeneration,
  type ClaudeGenerationState,
} from './generation-timing.js';

// ── 共享 turn / runtime 状态 ─────────────────────────────────────────────────
//
// 跨 SDKMessage 维持:
//  - turnState.text / toolUses/apiCalls: 一个 turn 内 assistant text、tool/API 调用计数, 给 turn end 日志用
//  - thinkingBuf: thinking_delta 跨多个 stream_event 累积; assistant.thinking final 时关闭

export interface TurnState {
  text: string;
  toolUses: number;
  /** 本 turn 内真实 Claude API call 次数;message_start 触发时递增。 */
  apiCalls: number;
  /** 本 turn 是否已收到 compact_boundary;收到后 result usage 不应覆盖 compact 后 context。 */
  sawCompactBoundary: boolean;
  /**
   * 本 turn 主代理是否已向 UI 推过 text event(assistant text block 或流式 text_delta)。
   * handleResult 里 result.result 兜底补推的判据:整轮一个 text 都没推过时才补,
   * 避免与已推正文重复。空串不置位(见两处置位点)。
   */
  hasEmittedText: boolean;
  /**
   * 本 turn 主代理已推给 UI 的 text(assistant block + 流式 delta,按到达顺序拼接)。
   * 子代理事件仍照常推送,但不能参与主代理 result 的补发或 silent-stop 判定。
   * turn-end 时与 result.result 做前缀比对,只补 UI 缺失的尾部(末尾截断兜底),绝不重复推。
   * 这是修复 e7ea882b 盲区(末尾截断)的依据:hasEmittedText 是 per-turn 布尔,无法区分
   * "整轮全空"和"前面推过、最后一段被截断";uiEmittedText 让兜底能精确算出缺哪一段。
   */
  uiEmittedText: string;
  /**
   * SDK API retry / assistant error envelope 的暂存详情。两者都不是可靠的 turn
   * 终态: Claude Code 可能随后自动重试并返回成功 result。只有最终
   * result.is_error 才把它推成 terminal error;成功 result 直接丢弃,避免下游
   * 提前收口重试中的 turn。
   */
  pendingApiError: {
    message: string;
    sdkError: string;
    agentMeta?: Record<string, unknown>;
    errorStatus?: number | null;
    usageLimit?: boolean;
    /** Extracted before redaction, which can make an upstream JSON envelope unparsable. */
    modelAccessDenied?: boolean;
    retryAttempt?: number;
    maxRetries?: number;
  } | null;
  /**
   * 本 turn 是否由 maker 侧主动 interrupt(用户点停止 handle.abort() / upstream
   * idle watchdog, 都走 q.interrupt())。SDK 被 interrupt 后会 drain 出
   * ResultMessage(error_during_execution, is_error=true)走正常 result 路径——
   * 这不是上游失败, turn-end 的 is_error 兜底必须跳过, 否则:用户手动停止被
   * 误报成"执行失败"通知(本 PR 要消灭的那类误报); watchdog 场景则双发 error
   * banner(watchdog 自己已推过带 reason 的 terminal error)。置位点在 index.ts
   * 的 abort() 与 watchdog 超时回调, interrupt 之前打。
   */
  interruptRequested: boolean;
  /**
   * send 代际计数(index.ts 的 beginNewTurn 自增)。interrupt 置位时把当时代际
   * 快照进 interruptGeneration —— handleResult 收到被打断的 is_error result 时,
   * 若代际已前进(新 send 已接管), 该迟到 result 必须**整条丢弃**(不发 error 也
   * 不发 status Done/done):它的 done 会被 main 当作**当前** turn 的边界,提前
   * 清掉/完成新 turn(coordinator onTurnEvent done)。代际未变(常规用户停止)
   * 则保持既有收尾(静音 error + 完整 Done/done, 花费记账依赖 done)。
   */
  generation: number;
  /** interrupt 置位时的 generation 快照(见 generation 注释)。 */
  interruptGeneration: number;
  /**
   * 最近一条主代理 assistant API 消息是否带「实质内容」(非空 text 或任何非 thinking 块;
   * thinking / redacted_thinking 不算)。逐条 assistant 消息覆盖写,turn end
   * 时留下的即"最后一条 assistant 消息"的判定,是 silent-stop 观测的核心依据:
   * 上游偶发用一条空内容消息收尾整个 turn(空 thinking + end_turn,或 SSE 流被
   * 静默中断后 stop_reason 缺失;社区同型报告 anthropics/claude-code#50597 /
   * #38905),任务做到一半"看起来正常结束"。默认 true(fail-safe:本 turn 还没
   * 见过 assistant 消息时不参与判定)。
   */
  lastAssistantMsgHadSubstance: boolean;
  /**
   * The price variant captured when the current turn's next provider request
   * was accepted. The SDK may deliver message_start after a runtime Fast-mode
   * toggle, so usage translation must not read the mutable session setting for
   * that already-dispatched request.
   */
  nextRequestPriceVariant?: 'standard' | 'priority';
  /**
   * 本 turn 最近一条 assistant API message id。Vertex 路由用 `msg_vrtx_`
   * 前缀作为输出 token 延迟结算的确定性证据;result 本身不携带该 id,
   * 因此必须在 assistant 消息到达时按 turn 暂存,再随 done 交给 host。
   */
  lastAssistantRequestId?: string;
}

export interface RuntimeState {
  currentThinking: { blockId: string; startedAt: number; text: string } | null;
  /** tool_use.id → tool_use.name。用于在 tool_result echo 时区分命令输出和内容结果。 */
  toolUseIdToName: Map<string, string>;
  /**
   * 主(parent)流当前请求 streamed 出来的 tool_use id;message_start 清空,
   * message_delta 停表后清空。生成时钟只允许停在这批 id 上 —— toolUseIdToName
   * 是跨请求、跨 turn 的命名表,里面可能留着 echo 永远不会来的旧 id(ToolSearch
   * 等 SDK 内部工具、错误中断的 turn),按它扫全量停表会让 pendingToolIds 永不
   * 排空、时钟冻死,而 output 还在涨,live tok/s 无限膨胀。
   */
  mainRequestToolUseIds: Set<string>;
  /**
   * SDK child assistant 消息按 parent_tool_use_id 隔离的真实模型。
   * 并发 subagent 的完整消息与 stream_event 都会交错,不能用会话级元数据推断。
   */
  streamModelByParentToolUseId: Map<string, string>;
  /** Agent 工具回执里的权威模型,优先级高于流式事件里的 wire model。 */
  resolvedSubagentModelByParentToolUseId: Map<string, string>;
  /** 已经通过 agent_task_update 下发过的模型;与 stream map 分离,避免漏发或重复发。 */
  publishedSubagentModelByParentToolUseId: Map<string, string>;
  /** parent tool_use.id 对应的最近任务状态;晚到的模型观测不能把终态倒退成 running。 */
  subagentStatusByParentToolUseId: Map<string, AgentTaskStatus>;
  /** task_id 到启动它的 Agent tool_use.id 的别名映射。 */
  subagentParentToolUseIdByTaskId: Map<string, string>;
  /**
   * 已被 SDK 明确标记为 local_agent / remote_agent 的 task_id。
   * Claude 后续进度与终态帧可能省略 task_type / tool_use_id;一旦确认,
   * 该身份在本 RuntimeState 生命周期内保持单向锁存,避免持久记录停在 running。
   */
  confirmedSubagentTaskIds: Set<string>;
  /** 明确属于 local_bash / local_workflow 的 task_id;稀疏后续帧继续排除。 */
  excludedSubagentTaskIds: Set<string>;
  /**
   * 上一次主 agent SDK assistant 消息的 agentMeta (uuid / sdkSessionId / model / ...).
   * 主 agent 的 stream_event 累积时用它补齐 transcript 锚点;subagent stream
   * 则必须按 parent_tool_use_id 隔离,不能共享这份会话级状态。
   * 老链路 agentManager.ts:2214 (session.lastAssistantMeta) 同款。
   */
  lastAssistantMeta: Record<string, unknown> | null;
  /**
   * Claude Code QueryEngine 的 result.usage 是当前子进程 session 内累计值。
   * translator 在 handleResult 里按上一条 result 做 delta, 再把 per-turn usage 交给 UsageTracker。
   */
  lastResultUsageAggregate: ResultUsageAggregate | null;
  /**
   * 按 parent + content-block index 隔离的停止符清洗缓冲。text_delta 可能把
   * `<|eos|>` 拆开,必须先拼回该块的快照再清洗。`emitted` 只表示本块是否已
   * 发出可见正文,不能看整轮 `uiEmittedText`,也不能跨 text block 复用。
   */
  streamStopTokenByKey: Map<string, StandaloneStopTokenHold>;
  /** Current message_start.message.id for each parent stream, used before the full envelope arrives. */
  streamRequestIdByParent: Map<string, string>;
  /** Per-parent active provider request used to merge message_start + message_delta usage. */
  activeUsageSegmentByParent: Map<string, string>;
  /**
   * 主流当前 provider 请求:main message_start 打开;main message_stop、下一次
   * main message_start 或 result 收口。Claude Code 每个 content block 结束就先
   * yield 完整 assistant,携带 output usage 的 message_delta 在整条回复生成完才到,
   * 所以「本请求 streamed output 是否完整」只能在请求边界判定,不能在 assistant 到达时判定。
   */
  mainOpenRequest: { requestId?: string; sawAssistant: boolean } | null;
  /** Price variant frozen for the active request of each parent stream. */
  activeUsagePriceVariantByParent: Map<string, 'standard' | 'priority'>;
  /** Price variant captured for the next request before its message_start arrives. */
  pendingUsagePriceVariantByParent: Map<string, 'standard' | 'priority'>;
  /** Monotonic ids for user messages carrying tool_result blocks, used to keep one assistant batch together. */
  toolResultBatchSeq: number;
  usageSegmentSeq: number;
  generation: ClaudeGenerationState;
  /**
   * 被拒额度窗口(`rateLimitType`)→ 重置时刻(unix ms)。每条 `rate_limit_event`
   * 只描述一个窗口,只有同一窗口再报非 rejected 才移除,别的窗口的 allowed 不影响。
   * 会话级而非 turn 级:CLI 已知被拒后会本地短路后续请求,那些 turn 直接报限额
   * 错误、不再重发事件,仍要能带上同一个重置时刻。
   */
  rateLimitRejectedResetAtMs: Map<string, number>;
}

export function newRuntimeState(): RuntimeState {
  return {
    currentThinking: null,
    toolUseIdToName: new Map(),
    mainRequestToolUseIds: new Set(),
    streamModelByParentToolUseId: new Map(),
    resolvedSubagentModelByParentToolUseId: new Map(),
    publishedSubagentModelByParentToolUseId: new Map(),
    subagentStatusByParentToolUseId: new Map(),
    subagentParentToolUseIdByTaskId: new Map(),
    confirmedSubagentTaskIds: new Set(),
    excludedSubagentTaskIds: new Set(),
    lastAssistantMeta: null,
    lastResultUsageAggregate: null,
    streamStopTokenByKey: new Map(),
    streamRequestIdByParent: new Map(),
    activeUsageSegmentByParent: new Map(),
    mainOpenRequest: null,
    activeUsagePriceVariantByParent: new Map(),
    pendingUsagePriceVariantByParent: new Map(),
    toolResultBatchSeq: 0,
    usageSegmentSeq: 0,
    generation: newClaudeGenerationState(),
    rateLimitRejectedResetAtMs: new Map(),
  };
}

const CLAUDE_MAIN_USAGE_PARENT = '__main__';

function isMainUsageSegmentId(segmentId: string | undefined): boolean {
  return typeof segmentId === 'string' && segmentId.endsWith(`:${CLAUDE_MAIN_USAGE_PARENT}`);
}

/** Parent-agent streamed output only. Subagent segments stay in cumulative usage. */
function mainTurnOutputTokens(tracker: UsageTracker): number {
  let output = 0;
  for (const segment of tracker.getTurnUsageSegments()) {
    if (isMainUsageSegmentId(segment.id)) output += segment.outputTokens;
  }
  return output;
}

function mainActiveSegmentHasOutput(ctx: TranslateContext): boolean {
  const segmentId = ctx.rt.activeUsageSegmentByParent.get(CLAUDE_MAIN_USAGE_PARENT);
  if (!segmentId) return false;
  for (const segment of ctx.tracker.getTurnUsageSegments()) {
    if (segment.id === segmentId) return segment.outputTokens > 0;
  }
  return false;
}

/**
 * 在主流请求边界收口:本请求已产出 assistant 却没有 streamed output usage 时,
 * 父级分子残缺,子代理在场的 live tok/s 必须 fail closed。随后摘掉当前 usage 段,
 * 下一请求不得沿用本请求的 streamed output。
 */
function settleMainRequest(ctx: TranslateContext): void {
  const open = ctx.rt.mainOpenRequest;
  if (!open) return;
  if (open.sawAssistant && !mainActiveSegmentHasOutput(ctx)) {
    noteClaudeParentStreamedOutputIncomplete(ctx.rt.generation);
  }
  ctx.rt.activeUsageSegmentByParent.delete(CLAUDE_MAIN_USAGE_PARENT);
  ctx.rt.mainOpenRequest = null;
}

/** 主流完整 assistant 只登记到所属请求;它早于该请求的 message_delta,不能在此判完整性。 */
function observeMainAssistant(ctx: TranslateContext, requestId: string | undefined): void {
  const open = ctx.rt.mainOpenRequest;
  if (open && (!requestId || !open.requestId || open.requestId === requestId)) {
    open.sawAssistant = true;
    return;
  }
  // 没见过 message_start 的请求:不会再有可归属的 message_delta,分子必然残缺。
  settleMainRequest(ctx);
  noteClaudeParentStreamedOutputIncomplete(ctx.rt.generation);
}

function applySubagentLiveReliability(ctx: TranslateContext): void {
  if (!ctx.rt.generation.sawSubagent) return;
  // Live status cannot compare against result.usage yet. A parent request that
  // already closed without usage is unrecoverable. Parent output may still be
  // in flight when a child stream arrives first — do not fail closed on 0
  // streamed output here, or the later parent message_delta cannot restore tok/s.
  if (ctx.rt.generation.parentStreamedOutputIncomplete) {
    markClaudeGenerationUnreliable(ctx.rt.generation);
  }
}

function liveParentOutputTokens(
  ctx: TranslateContext,
  resultOutput?: number,
  streamedOutputMatchesResult = false,
): number {
  const mainOutput = mainTurnOutputTokens(ctx.tracker);
  if (ctx.rt.generation.sawSubagent) {
    // result.usage includes subagent output. Parent live tok/s is only
    // commensurate with the parent generation denominator when streamed
    // segments prove they cover every output token in the result aggregate.
    if (!streamedOutputMatchesResult) {
      markClaudeGenerationUnreliable(ctx.rt.generation);
    }
    return mainOutput;
  }
  if (typeof resultOutput === 'number' && Number.isFinite(resultOutput)) {
    // A first aggregate after resume may include historical output. Keep the
    // accounting total, but never divide it by this turn's generation time.
    if (!streamedOutputMatchesResult) markClaudeGenerationUnreliable(ctx.rt.generation);
    return Math.max(0, resultOutput);
  }
  return mainOutput;
}

function ccLiveStatus(
  ctx: TranslateContext,
  status: string,
  isRunning: boolean,
): { status: string; isRunning: boolean } & ReturnType<UsageTracker['snapshot']> {
  applySubagentLiveReliability(ctx);
  return {
    status,
    ...attachLiveGeneration(ctx.tracker.snapshot(), {
      tokenSpeed: ctx.rt.generation.tokenSpeed.snapshot(),
      outputTokens: mainTurnOutputTokens(ctx.tracker),
      durationMs: ctx.rt.generation.outputDurationMs,
      openStartedAt: ctx.rt.generation.startedAt,
      reliable: ctx.rt.generation.reliable,
    }),
    requestUsage: ctx.tracker.getRequestMetering(),
    isRunning,
  };
}

/**
 * 清掉一个 turn 的非 usage 累积状态(usage 由 UsageTracker.endTurn 内部 reset)。
 * turn 收尾共用:正常 Done/done 路径与 empty-response 终态 error 提前 return 路径。
 */
function resetTurnState(turn: TurnState): void {
  turn.text = '';
  turn.toolUses = 0;
  turn.apiCalls = 0;
  turn.sawCompactBoundary = false;
  turn.hasEmittedText = false;
  turn.uiEmittedText = '';
  turn.pendingApiError = null;
  turn.interruptRequested = false;
  turn.lastAssistantMsgHadSubstance = true;
  turn.lastAssistantRequestId = undefined;
  // generation / interruptGeneration 刻意不清: 代际跨 turn 单调递增(见字段注释)。
}

type ResultUsageAggregate = {
  inputTokens: number;
  outputTokens: number;
  cacheReadTokens?: number;
  cacheCreateTokens?: number;
};

function resultUsageToTurnDelta(
  previous: ResultUsageAggregate | null,
  current: ResultUsageAggregate,
): ResultUsageAggregate {
  if (!previous) return current;
  const aggregateReset =
    current.inputTokens < previous.inputTokens ||
    current.outputTokens < previous.outputTokens ||
    (
      current.cacheReadTokens !== undefined &&
      previous.cacheReadTokens !== undefined &&
      current.cacheReadTokens < previous.cacheReadTokens
    ) ||
    (
      current.cacheCreateTokens !== undefined &&
      previous.cacheCreateTokens !== undefined &&
      current.cacheCreateTokens < previous.cacheCreateTokens
    );
  if (aggregateReset) return current;
  return {
    inputTokens: Math.max(0, current.inputTokens - previous.inputTokens),
    outputTokens: Math.max(0, current.outputTokens - previous.outputTokens),
    cacheReadTokens: current.cacheReadTokens === undefined
      ? undefined
      : Math.max(0, current.cacheReadTokens - (previous.cacheReadTokens ?? 0)),
    cacheCreateTokens: current.cacheCreateTokens === undefined
      ? undefined
      : Math.max(0, current.cacheCreateTokens - (previous.cacheCreateTokens ?? 0)),
  };
}

function normalizeModelForContextWindow(model: string): string {
  return model.replace(/\[1m\]$/, '');
}

function modelIdsMatchForContextWindow(a: string, b: string): boolean {
  const left = normalizeModelForContextWindow(a);
  const right = normalizeModelForContextWindow(b);
  return left === right || left.startsWith(right) || right.startsWith(left);
}

/**
 * 从一条 SDK assistant message 抽 cc 元信息 (uuid / parent_tool_use_id / session_id +
 * 内层 message.{model, stop_reason, id, usage})。shape 与 desktop CcMeta 对齐 (camelCase)。
 * 老链路 agentManager.ts:ccMetaFromAssistant 同款; 缺字段一律不写入。
 */
export function extractAssistantMeta(rawMsg: unknown): Record<string, unknown> {
  const msg = rawMsg as {
    uuid?: string;
    parentUuid?: string;
    parent_uuid?: string;
    session_id?: string;
    parent_tool_use_id?: string | null;
    message?: {
      id?: string;
      model?: string;
      stop_reason?: string | null;
      usage?: {
        input_tokens?: number;
        output_tokens?: number;
        cache_read_input_tokens?: number;
        cache_creation_input_tokens?: number;
      };
    };
  };
  const meta: Record<string, unknown> = {};
  if (typeof msg.uuid === 'string') meta.uuid = msg.uuid;
  if (typeof msg.session_id === 'string') meta.sdkSessionId = msg.session_id;
  if (typeof msg.parent_tool_use_id === 'string' && msg.parent_tool_use_id) {
    meta.parentUuid = msg.parent_tool_use_id;
  }
  const transcriptParentUuid =
    (typeof msg.parentUuid === 'string' && msg.parentUuid)
      ? msg.parentUuid
      : (typeof msg.parent_uuid === 'string' && msg.parent_uuid)
          ? msg.parent_uuid
          : undefined;
  if (transcriptParentUuid) meta.transcriptParentUuid = transcriptParentUuid;
  const inner = msg.message;
  if (inner) {
    if (typeof inner.model === 'string') meta.model = inner.model;
    if (typeof inner.stop_reason === 'string') meta.stopReason = inner.stop_reason;
    if (typeof inner.id === 'string') meta.requestId = inner.id;
    if (inner.usage) {
      meta.usage = {
        inputTokens: inner.usage.input_tokens,
        outputTokens: inner.usage.output_tokens,
        cacheReadInputTokens: inner.usage.cache_read_input_tokens,
        cacheCreationInputTokens: inner.usage.cache_creation_input_tokens,
      };
    }
  }
  return meta;
}

// ── 工具:从 user echo 里抽 tool_result 全文 ──────────────────────────────────
// (复刻 agentManager.ts:88-114 extractToolResultFullText)

// Host 侧显式镜像 cc-code 的 SHELL_TOOL_NAMES;上游新增 shell 工具时必须同步维护。
// TaskOutput 读取的是任务/agent 输出,不等同于终端工具结果。
const TERMINAL_OUTPUT_TOOL_NAMES = new Set(['Bash', 'PowerShell']);

interface ToolResultPair {
  processMedia: NativeToolMedia[];
  toolUseId: string;
  fullText: string;
  isError: boolean;
}

function normalizeToolResultFullText(
  pair: ToolResultPair,
  rt: RuntimeState,
): ToolResultPair {
  const toolName = rt.toolUseIdToName.get(pair.toolUseId);
  if (!toolName || !TERMINAL_OUTPUT_TOOL_NAMES.has(toolName)) return pair;
  return {
    ...pair,
    fullText: stripTerminalControlSequences(pair.fullText),
    isError: pair.isError,
  };
}

function extractToolResultFullText(
  message: { content?: unknown } | undefined,
  rt: RuntimeState,
): ToolResultPair[] {
  if (!message?.content || typeof message.content === 'string') return [];
  if (!Array.isArray(message.content)) return [];
  const out: ToolResultPair[] = [];
  for (const block of message.content as unknown[]) {
    const pair = readToolResultFullText(block);
    if (pair) {
      const normalized = normalizeToolResultFullText(pair, rt);
      if (normalized.fullText.length > 0 || normalized.processMedia.length > 0) out.push(normalized);
    }
  }
  return out;
}

function readToolResultFullText(blockRaw: unknown): ToolResultPair | null {
  if (!blockRaw || typeof blockRaw !== 'object') return null;
  const b = blockRaw as { type?: unknown; tool_use_id?: unknown; content?: unknown; is_error?: unknown };
  if (b.type !== 'tool_result') return null;
  if (typeof b.tool_use_id !== 'string' || b.tool_use_id.length === 0) return null;
  const inner = b.content;
  let fullText = '';
  if (typeof inner === 'string') {
    fullText = inner;
  } else if (Array.isArray(inner)) {
    const parts: string[] = [];
    for (const sub of inner) {
      if (sub && typeof sub === 'object' && (sub as { type?: unknown }).type === 'text') {
        const t = (sub as { text?: unknown }).text;
        if (typeof t === 'string') parts.push(t);
      }
    }
    fullText = parts.join('\n');
  }
  return { toolUseId: b.tool_use_id, fullText, isError: b.is_error === true, processMedia: collectNativeToolMedia(inner) };
}

/**
 * 从 Agent 工具回执中提取任务身份、生命周期与权威模型。
 * Claude Code 会把最终解析后的模型放在 tool_use_result.resolvedModel;同步前台
 * Agent 直接返回 completed,异步 Agent 返回 async_launched。两者都比根据请求参数
 * 或流式子消息时序推断可靠,应直接投影成 AgentTaskUpdate。
 */
interface SubagentToolResult {
  taskId: string;
  parentToolUseId: string;
  prompt?: string;
  model?: string;
  status: 'running' | 'completed';
  usage?: AgentTaskUsage;
}

function readResultNumber(
  result: Record<string, unknown>,
  camelKey: string,
  snakeKey: string,
): number | undefined {
  const value = result[camelKey] ?? result[snakeKey];
  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
}

function extractSubagentToolResult(
  msg: {
    message?: { content?: unknown };
    tool_use_result?: unknown;
    toolUseResult?: unknown;
  },
): SubagentToolResult | null {
  const rawResult = msg.tool_use_result ?? msg.toolUseResult;
  if (!rawResult || typeof rawResult !== 'object' || Array.isArray(rawResult)) return null;
  const result = rawResult as Record<string, unknown>;
  const isAsync = result.isAsync === true || result.is_async === true;
  const status = result.status;
  const rawAgentId = result.agentId ?? result.agent_id;
  const agentId = typeof rawAgentId === 'string' && rawAgentId ? rawAgentId : undefined;
  const isAsyncLaunch = isAsync || status === 'async_launched';
  // completed 很常见,必须同时有 Agent 专属的 agentId 才能识别为同步子任务回执。
  const isCompletedAgent = status === 'completed' && Boolean(agentId);
  if (!isAsyncLaunch && !isCompletedAgent) return null;

  const model = typeof result.resolvedModel === 'string'
    ? result.resolvedModel
    : typeof result.resolved_model === 'string'
      ? result.resolved_model
      : undefined;
  const content = msg.message?.content;
  let toolResult: { toolUseId: string; fullText: string } | null = null;
  if (Array.isArray(content)) {
    for (const block of content) {
      toolResult = readToolResultFullText(block);
      if (toolResult) break;
    }
  }
  if (!toolResult) return null;

  const taskId = agentId ?? toolResult.toolUseId;
  const prompt = typeof result.prompt === 'string' && result.prompt
    ? result.prompt
    : undefined;
  const usage: AgentTaskUsage = {};
  const totalTokens = readResultNumber(result, 'totalTokens', 'total_tokens');
  const toolUses = readResultNumber(result, 'totalToolUseCount', 'total_tool_use_count');
  const durationMs = readResultNumber(result, 'totalDurationMs', 'total_duration_ms');
  if (totalTokens !== undefined) usage.totalTokens = totalTokens;
  if (toolUses !== undefined) usage.toolUses = toolUses;
  if (durationMs !== undefined) usage.durationMs = durationMs;
  return {
    taskId,
    parentToolUseId: toolResult.toolUseId,
    model,
    prompt,
    status: isCompletedAgent ? 'completed' : 'running',
    ...(Object.keys(usage).length > 0 ? { usage } : {}),
  };
}

// ── cache 命中率日志格式化 ───────────────────────────────────────────────────
// hitRate 按"百分比 + 1 位小数"输出, 没数据返 'n/a'。
// 配 read/create/uncached/apiCalls 一起打, 看 hitRate 时能立刻判断样本量够不够代表性。

function formatCacheBucket(b: {
  read: number;
  create: number;
  uncachedInput: number;
  apiCalls: number;
  hitRate: number | null;
}): {
  hitRate: string;
  read: number;
  create: number;
  uncached: number;
  apiCalls: number;
} {
  return {
    hitRate: b.hitRate === null ? 'n/a' : `${(b.hitRate * 100).toFixed(1)}%`,
    read: b.read,
    create: b.create,
    uncached: b.uncachedInput,
    apiCalls: b.apiCalls,
  };
}

// ── 主翻译器 ─────────────────────────────────────────────────────────────────

const TURN_END_LOGGER_KEY = 'SDK ◀ turn end (result)';
void TURN_END_LOGGER_KEY; // 只是给调用方对照参考

type EventQueue = ReturnType<typeof createAsyncQueue<AgentEvent>>;
interface TranslatorLog {
  debug(msg: string, ctx?: Record<string, unknown>): void;
  info(msg: string, ctx?: Record<string, unknown>): void;
  warn(msg: string, ctx?: Record<string, unknown>): void;
}

interface TranslateContext {
  rt: RuntimeState;
  turn: TurnState;
  log: TranslatorLog;
  /**
   * 当前 runtime 参数 getter —— turn start/end 日志读这三个,
   * setModel/setEffort/setPermissionMode 修改后能立刻反映到下一行日志,
   * 不会因为闭包捕获 startSession 时的初始值而打陈旧数据。
   */
  getModel: () => string;
  /** 当前 turn 的 provider 路由;null = 兼容旧会话的隐式默认来源。 */
  getProviderId?: () => string | null;
  /**
   * Maker capabilities 中当前模型的 contextWindow。
   * Claude Code SDK 对未知第三方模型会回 200K 默认值; maker 侧配置更准时用它覆盖。
   */
  getModelContextWindow?: () => number | undefined;
  getEffort: () => string;
  getPermissionMode: () => string;
  getFastMode?: () => boolean;
  /** SDK session_id 第一次出现时的回调, agent 用来回填 sdkSessionId */
  onSessionId: (sdkSessionId: string | undefined) => void;
  /**
   * 当前已知的 SDK session_id (agent 闭包持有)。
   * 仅诊断日志用, getter 形式确保读到的是最新值 (system init 那一步会回填)。
   */
  getSdkSessionId: () => string | undefined;
  /** Whether the current SDK query starts its cumulative modelUsage at zero. */
  modelUsageCumulativeStartsAtZero?: () => boolean;
  /**
   * 当前 session 的展示 title —— 由调用方 (register.ts) 每次 send 时透传进来,
   * 同样仅用于诊断日志, 不参与业务。允许 undefined / 跨 turn 变化。
   */
  getLogTitle: () => string | undefined;
  /**
   * Stage 2 B': SDK 原始 usage 通过 tracker 累加, 翻译器只在 push status 时
   * 走 tracker.snapshot() 取最终数值, 不再自己算 (避免再次出现 currentTurn 不累加 /
   * contextWindow 写死 0 这类与老 agentManager 不一致的 bug)。
   */
  tracker: UsageTracker;
  /**
   * turn 结束 (result 事件) 时回调, agent 用来清 turnInFlight 标记。
   * 缺省 = 不回调 (旧调用方零改动)。
   */
  onTurnEnd?: () => void;
  /**
   * upstream-response-idle watchdog / loop guard: assistant / stream_event 含 tool_use 时回调。
   * parentToolUseId 用于隔离并发 subagent;缺省表示顶层 agent。
   * inputStreaming 表示参数尚在流入,不能据此认定工具已执行并暂停上游计时。
   */
  onToolUseStart?: (
    toolUseId: string,
    toolName?: unknown,
    input?: unknown,
    parentToolUseId?: string,
    inputStreaming?: boolean,
  ) => void;
  /**
   * upstream-response-idle watchdog: user 含 tool_result 时出队, 配对 onToolUseStart。
   * 不要复用 extractToolResultFullText — 那里 fullText.length>0 过滤会漏空内容 result
   * (Bash 无 stdout / Write 成功 / MCP return null), 导致 pendingToolIds 永远漏减,
   * watchdog 整 turn 失效。isError 来自 SDK tool_result.is_error;只有明确失败的结果
   * 才能进入契约错误熔断。toolResultBatchId 标识同一 user tool-result 消息,使并行
   * 工具调用不会在模型看到错误前被当成多轮重试。parentToolUseId 与 tool_use 同源,
   * 用于隔离并发 subagent。
   */
  onToolResultDone?: (
    toolUseId: string,
    output: string,
    parentToolUseId?: string,
    isError?: boolean,
    toolResultBatchId?: string,
  ) => void;
  onSubagentTaskLaunched?: (task: {
    taskId: string;
    parentToolUseId: string;
    prompt: string;
    model?: string;
  }) => void;
  getSubagentTaskUsage?: (taskId: string) => AgentTaskUsage | undefined;
  /**
   * Maker Memory flush 观察器 — 翻译 status / message_delta event 时, push 完
   * eventQueue 后调一下 (传当前 contextTokens / contextWindow 让 controller 算 ratio)。
   * 缺省 = 不回调 (makerMemoryEnabled 关时 agent 不注入)。
   */
  onUsageUpdate?: (contextTokens: number, contextWindow: number) => void;
  /**
   * Maker Memory flush 观察器 — compact_boundary 事件后调, controller 重置 fired 标记。
   * 缺省 = 不回调。
   */
  onCompactBoundary?: () => void;
}

export function translateSdkMessage(
  rawMsg: unknown,
  queue: EventQueue,
  ctx: TranslateContext,
): void {
  const msg = rawMsg as {
    type?: string;
    subtype?: string;
    session_id?: string;
    parent_tool_use_id?: string | null;
    model?: string;
    message?: { content?: Array<Record<string, unknown>>; role?: string };
    event?: Record<string, unknown>;
    summary?: string;
    preceding_tool_use_ids?: string[];
    tool_name?: string;
    error?: string;
    stop_reason?: string;
    is_error?: boolean;
    duration_ms?: number;
    duration_api_ms?: number;
    num_turns?: number;
    total_cost_usd?: number;
    terminal_reason?: string;
    usage?: {
      input_tokens?: number;
      output_tokens?: number;
      cache_read_input_tokens?: number;
      cache_creation_input_tokens?: number;
    };
    /** SDK 在 result 里按 modelId 给出真实跑过的模型(支持 turn 内 setModel 切换累加) */
    modelUsage?: Record<string, { inputTokens?: number; outputTokens?: number; costUSD?: number }>;
    result?: string;
    [k: string]: unknown;
  };

  switch (msg.type) {
    case 'system': {
      handleSystem(msg, queue, ctx);
      return;
    }

    case 'assistant': {
      handleAssistant(msg, queue, ctx);
      return;
    }

    case 'user': {
      // streaming-input 模式下 SDK 不 echo 真实 user 输入, 只 echo tool_result 包装的 user message
      // 这里只关心后者: 抽 tool_result_full 给 renderer (老 agentManager.ts:2178-2207 同等逻辑)
      const parentToolUseId = typeof msg.parent_tool_use_id === 'string' && msg.parent_tool_use_id
        ? msg.parent_tool_use_id
        : undefined;
      const content = msg.message?.content;
      const hasToolResult = Array.isArray(content)
        && content.some((blockRaw) => readToolResultFullText(blockRaw) !== null);
      const toolResultBatchId = hasToolResult
        ? `tool-result-batch-${++ctx.rt.toolResultBatchSeq}`
        : undefined;
      const fullPairs = extractToolResultFullText(msg.message, ctx.rt);
      for (const pair of fullPairs) {
        queue.push({
          type: 'tool_result_full',
          data: { toolUseId: pair.toolUseId, fullText: pair.fullText, ...(pair.processMedia.length ? { processMedia: pair.processMedia } : {}) },
          source: 'claude-code',
          ...(parentToolUseId ? { agentMeta: { parentUuid: parentToolUseId } } : {}),
        });
      }
      const subagentResult = extractSubagentToolResult(msg);
      if (subagentResult) {
        const { taskId, parentToolUseId, model, prompt, status, usage } = subagentResult;
        const actualModel = model
          ?? ctx.rt.resolvedSubagentModelByParentToolUseId.get(parentToolUseId)
          ?? ctx.rt.streamModelByParentToolUseId.get(parentToolUseId);
        ctx.rt.subagentParentToolUseIdByTaskId.set(taskId, parentToolUseId);
        ctx.rt.confirmedSubagentTaskIds.add(taskId);
        ctx.rt.excludedSubagentTaskIds.delete(taskId);
        // 迟到的 async_launched 回执(status=running)不得把已有终态降级回 running:
        // 事件乱序时(task_notification: completed 先到)这会让 Renderer 永久转圈。
        // 状态机只允许 running → 终态,终态后到达的 launch 回执只补元数据、不改状态。
        const previousStatus = ctx.rt.subagentStatusByParentToolUseId.get(parentToolUseId);
        const isTerminal = previousStatus === 'completed'
          || previousStatus === 'failed'
          || previousStatus === 'stopped';
        const effectiveStatus = status === 'running' && isTerminal
          ? previousStatus!
          : status;
        ctx.rt.subagentStatusByParentToolUseId.set(parentToolUseId, effectiveStatus);
        if (model) {
          ctx.rt.resolvedSubagentModelByParentToolUseId.set(parentToolUseId, model);
        }
        if (actualModel) {
          ctx.rt.publishedSubagentModelByParentToolUseId.set(parentToolUseId, actualModel);
        }
        if (status === 'running' && prompt && !isTerminal) {
          ctx.onSubagentTaskLaunched?.({ taskId, parentToolUseId, prompt, model: actualModel });
        }
        queue.push({
          type: 'agent_task_update',
          data: {
            provider: 'claude-code',
            taskId,
            parentToolUseId,
            status: effectiveStatus,
            subagentObservation: {
              // A synchronous completed Agent result may be the first and only
              // lifecycle observation. It is authoritative to create the run,
              // while the completed status still keeps the record terminal.
              kind: 'spawn',
              logicalSubagentId: taskId,
              parentToolUseId,
            },
            ...(actualModel ? { model: actualModel } : {}),
            ...(usage ? { usage } : {}),
          },
          source: 'claude-code',
        });
      }
      // 单独遍历: 不能复用 extractToolResultFullText, 见 onToolResultDone JSDoc。
      const completedToolUseIds = new Set(fullPairs.map((pair) => pair.toolUseId));
      if (ctx.onToolResultDone) {
        if (Array.isArray(content)) {
          for (const blockRaw of content as unknown[]) {
            const rawPair = readToolResultFullText(blockRaw);
            const pair = rawPair ? normalizeToolResultFullText(rawPair, ctx.rt) : null;
            if (!pair) continue;
            completedToolUseIds.add(pair.toolUseId);
            ctx.onToolResultDone(
              pair.toolUseId,
              pair.fullText,
              parentToolUseId,
              pair.isError,
              toolResultBatchId,
            );
          }
        }
      } else if (Array.isArray(content)) {
        for (const blockRaw of content as unknown[]) {
          const pair = readToolResultFullText(blockRaw);
          if (pair) completedToolUseIds.add(pair.toolUseId);
        }
      }
      for (const toolUseId of completedToolUseIds) {
        if (!parentToolUseId) resumeClaudeGeneration(ctx.rt.generation, toolUseId);
        ctx.rt.toolUseIdToName.delete(toolUseId);
      }
      if (completedToolUseIds.size > 0) {
        // The SDK emits the tool-result echo immediately before it dispatches
        // the next provider request. Capture the mutable Fast setting here,
        // after tool execution has completed, rather than at the previous
        // message_delta (which can be much earlier than the next request).
        ctx.rt.pendingUsagePriceVariantByParent.set(
          parentToolUseId ?? CLAUDE_MAIN_USAGE_PARENT,
          ctx.getFastMode?.() ? 'priority' : 'standard',
        );
      }
      return;
    }

    case 'stream_event': {
      handleStreamEvent(msg, queue, ctx);
      return;
    }

    case 'tool_use_summary': {
      queue.push({
        type: 'tool_result',
        data: {
          summary: msg.summary,
          toolUseIds: msg.preceding_tool_use_ids,
        },
        source: 'claude-code',
      });
      return;
    }

    case 'tool_progress': {
      queue.push({
        type: 'status',
        data: {
          status: `${msg.tool_name ?? 'tool'} running...`,
          tokenUsage: 0,
          contextTokens: 0,
          contextWindow: 0,
          isRunning: true,
        },
        source: 'claude-code',
      });
      return;
    }

    case 'result': {
      handleResult(msg, queue, ctx);
      return;
    }

    case 'rate_limit_event': {
      // 订阅额度快照另由 index.ts 旁路转给 host;这里只记被拒窗口的重置时刻,
      // 供限额错误带给下游(目标模式据此到点自动续跑)。
      const info = (rawMsg as {
        rate_limit_info?: { status?: unknown; resetsAt?: unknown; rateLimitType?: unknown };
      }).rate_limit_info;
      if (typeof info?.status !== 'string') return;
      const windowKey = typeof info.rateLimitType === 'string' ? info.rateLimitType : '';
      const resetsAt = typeof info.resetsAt === 'number' && info.resetsAt > 0 ? info.resetsAt : null;
      if (info.status === 'rejected' && resetsAt != null) {
        // resetsAt 是 epoch 秒;误给毫秒时不再放大。
        const resetAtMs = resetsAt > 1e12 ? resetsAt : resetsAt * 1000;
        ctx.rt.rateLimitRejectedResetAtMs.set(windowKey, resetAtMs);
        ctx.log.info('SDK ▷ rate limit rejected', { rateLimitType: windowKey, resetAtMs });
      } else if (info.status !== 'rejected') {
        ctx.rt.rateLimitRejectedResetAtMs.delete(windowKey);
      }
      return;
    }

    case 'control_response': {
      // SDK 对每个 control request (setModel / applyFlagSettings / setPermissionMode / interrupt 等)
      // 都会回一条 control_response。这里只打日志做可见性 —— 排查"我点了切模型怎么没反应"很有用。
      // 不 push 任何 event 给上层 (renderer 不需要感知, IPC payload 也不必膨胀)。
      handleControlResponse(rawMsg, ctx);
      return;
    }

    default: {
      // 未识别 type: 走 logger.warn (诊断用), 不再 emit vendor-raw —— renderer
      // default case 直接丢, 走 IPC 也是浪费。Codex translator 同款做法。
      ctx.log.warn('SDK ▷ unhandled message type', {
        type: (rawMsg as { type?: unknown }).type,
        preview: JSON.stringify(rawMsg).slice(0, 200),
      });
      return;
    }
  }
}

// ── control_response ─────────────────────────────────────────────────────────

function handleControlResponse(rawMsg: unknown, ctx: TranslateContext): void {
  const msg = rawMsg as { response?: unknown };
  const resp = msg.response as
    | { subtype: 'success'; request_id?: string; response?: Record<string, unknown> }
    | { subtype: 'error'; request_id?: string; error?: string }
    | undefined;
  if (!resp || typeof resp !== 'object') {
    ctx.log.warn('SDK ◇ control_response: malformed', { raw: rawMsg });
    return;
  }
  if (resp.subtype === 'error') {
    ctx.log.warn('SDK ◇ control_response error', {
      requestId: resp.request_id,
      error: resp.error,
    });
    return;
  }
  // success: response payload 因 control 类型而异 (setModel 通常空, getMcpServerStatus 会带数据)
  ctx.log.debug('SDK ◇ control_response ok', {
    requestId: resp.request_id,
    response: resp.response,
  });
}

// ── system 子分支 ─────────────────────────────────────────────────────────────

function handleSystem(
  msg: {
    subtype?: string;
    uuid?: string;
    session_id?: string;
    model?: string;
    permissionMode?: string;
    status?: string;
    compact_metadata?: { trigger?: 'manual' | 'auto'; pre_tokens?: number; post_tokens?: number; duration_ms?: number };
    task_id?: string;
    tool_use_id?: string;
    description?: string;
    prompt?: string;
    task_type?: string;
    workflow_name?: string;
    output_file?: string;
    summary?: string;
    usage?: Record<string, number | undefined>;
    last_tool_name?: string;
    attempt?: number;
    max_retries?: number;
    retry_delay_ms?: number;
    error_status?: number | null;
    error?: string;
    // task_updated 专属:增量补丁(SDKTaskUpdatedMessage.patch)。只声明渲染需要的字段,
    // end_time / total_paused_ms / is_backgrounded 目前不进事件流。
    patch?: { status?: string; description?: string; error?: string };
  },
  queue: EventQueue,
  ctx: TranslateContext,
): void {
  if (msg.subtype === 'init' && typeof msg.session_id === 'string') {
    // model / permissionMode 优先用 SDK 在 init 里回执的真实值; effort SDK 不返回, 用 mutable 态。
    ctx.log.debug('SDK ▶ turn start (system init)', {
      sdkSessionId: msg.session_id,
      model: msg.model ?? ctx.getModel(),
      effort: ctx.getEffort(),
      permissionMode: msg.permissionMode ?? ctx.getPermissionMode(),
    });
    ctx.onSessionId(msg.session_id);
    return;
  }
  if (msg.subtype === 'status') {
    if (msg.status === 'compacting' || msg.status === 'thinking') {
      queue.push({
        type: 'status',
        data: {
          status: msg.status === 'compacting' ? 'Compacting...' : 'Thinking...',
          tokenUsage: 0,
          contextTokens: 0,
          contextWindow: 0,
          isRunning: true,
        },
        source: 'claude-code',
      });
    }
    return;
  }
  if (msg.subtype === 'api_retry') {
    // The backoff wait is not generation time; the retried request's first block resumes.
    ctx.rt.generation.tokenSpeed.pause();
    // SDKAPIRetryMessage 明确表示本次 API 失败仍在自动重试,不是 turn 终态。
    // 除日志外也暂存最后一次 retry 的错误详情,覆盖 SDK 没有额外发送
    // assistant.error envelope、最终 ResultMessage 又没有 result 文本的路径。
    // 已有 envelope 时保留其中的人话文案与 transcript metadata,只补 retry 元数据。
    const previous = ctx.turn.pendingApiError;
    const hasAssistantEnvelope = previous?.agentMeta !== undefined;
    const sdkError = redactSensitiveText(hasAssistantEnvelope ? previous.sdkError : (msg.error || 'unknown'));
    const statusLabel = msg.error_status == null ? 'connection error' : `HTTP ${msg.error_status}`;
    const retryLabel = typeof msg.attempt === 'number' && typeof msg.max_retries === 'number'
      ? `, retry ${msg.attempt}/${msg.max_retries}`
      : '';
    ctx.turn.pendingApiError = {
      message: hasAssistantEnvelope
        ? previous.message
        : `SDK API request failed: ${sdkError} (${statusLabel}${retryLabel})`,
      sdkError,
      ...(hasAssistantEnvelope ? { agentMeta: previous.agentMeta } : {}),
      modelAccessDenied: hasAssistantEnvelope
        ? previous.modelAccessDenied
        : isModelAccessDenied(msg.error ?? '', msg.error_status ?? undefined),
      errorStatus: msg.error_status,
      retryAttempt: msg.attempt,
      maxRetries: msg.max_retries,
    };
    ctx.log.info('SDK API request retrying', {
      attempt: msg.attempt,
      maxRetries: msg.max_retries,
      retryDelayMs: msg.retry_delay_ms,
      errorStatus: msg.error_status,
      sdkError: redactSensitiveText(msg.error ?? 'unknown'),
    });
    // SDK 正在自己退避重试 → 透出**非终止**进度,别让用户对着无提示的转圈干等
    // (PR #790 给 Codex `Reconnecting N/M` 做的是同一件事)。恢复后由后续正常
    // 事件按现有机制自动清除,不结束 turn、不落 error 行。
    //
    // **绝不在这里自己重投**:SDK 已带退避重试(529 overloaded / 429 / 连接错误
    // 都走它),客户端再叠一层会把一次上游过载放大成指数级请求,而失败请求照扣
    // 额度。Codex 那侧要自己重投只是因为 app-server 对容量拒绝根本不重试。
    //
    // 第 1 次不透出:单次抖动 SDK 一次重试就过,提示只会闪一下徒增噪音(与
    // codex translator 持续重试透出的防噪口径一致)。
    //
    // **只透出过载类**:这条 message 是内部英文 SDK 字符串,renderer 的 ErrorBanner
    // 只对过载与网络形态做本地化替换。若把 429、500 这类也透出来,各语言用户会直接
    // 看到裸英文,而它们在本改动之前是静默的——那是实打实的回归。其它重试类别保持
    // 原样静默,需要时另行补本地化再放开。
    //
    // 判据是 parseOverloadError 的**两种**形态都算(`overloaded`:529 /
    // overloaded_error;`capacity`:`at capacity`),不只 529:renderer 侧的镜像
    // (renderer/utils/overloadError.ts) 对两种形态都有本地化文案,所以放开 capacity
    // 不会产生裸英文;反过来只认 529 会把一条措辞为 `at capacity` 的过载错误静默掉,
    // 用户看到的是"什么都没发生"。
    const overloadRetry =
      typeof msg.attempt === 'number' &&
      typeof msg.max_retries === 'number' &&
      msg.attempt >= 2 &&
      parseOverloadError(`${sdkError} ${statusLabel}`, msg.error_status ?? undefined) !== null;
    if (overloadRetry) {
      queue.push({
        type: 'error',
        data: {
          // 进度用 `(auto-retry N/M)` 后缀编码,与 Codex 侧同一套跨 agent 协议,
          // renderer 只需一份解析。原始状态留在正文里供分类与折叠查看。
          message: formatOverloadRetryMessage(
            `SDK API request failed: ${sdkError} (${statusLabel})`,
            msg.attempt as number,
            msg.max_retries as number,
          ),
          isTerminal: false,
          willRetry: true,
          ...(msg.error_status != null ? { errorStatus: msg.error_status } : {}),
        },
        source: 'claude-code',
      });
    }
    return;
  }
  if (msg.subtype === 'compact_boundary') {
    const meta = msg.compact_metadata ?? {};
    ctx.log.info('SDK ◾ compact_boundary', meta);
    // compact 后 context 缩小 — 更新 tracker 使后续 snapshot().contextTokens 反映真实值
    const postTokens = meta.post_tokens ?? 0;
    ctx.tracker.setContextTokensAfterCompact(postTokens);
    ctx.turn.sawCompactBoundary = true;
    queue.push({
      type: 'compact_boundary',
      data: {
        ...(typeof msg.uuid === 'string' && msg.uuid ? { boundaryId: msg.uuid } : {}),
        trigger: meta.trigger ?? 'auto',
        preTokens: meta.pre_tokens ?? 0,
        postTokens,
        durationMs: meta.duration_ms ?? 0,
      },
      source: 'claude-code',
    });
    ctx.onCompactBoundary?.();
    return;
  }
  if (
    msg.subtype === 'task_started' ||
    msg.subtype === 'task_progress' ||
    msg.subtype === 'task_notification'
  ) {
    const update = toClaudeTaskUpdate(msg, ctx.rt, ctx.getSubagentTaskUsage);
    if (update) {
      queue.push({
        type: 'agent_task_update',
        data: update,
        source: 'claude-code',
      });
    }
    return;
  }
  // task_updated 是 tasks-panel 用的增量补丁(status / description / error),
  // 与上面三个事件共用 agent_task_update 通道 —— 下游 makerChatStore 按 taskId 做
  // 字段级 merge,故这里只需带上补丁里变化的字段。
  if (msg.subtype === 'task_updated') {
    const update = toClaudeTaskUpdatedPatch(msg, ctx.rt);
    if (update) {
      queue.push({
        type: 'agent_task_update',
        data: update,
        source: 'claude-code',
      });
    }
    return;
  }
}

function toClaudeTaskUsage(
  usage: Record<string, number | undefined> | undefined,
): AgentTaskUsage | undefined {
  if (!usage) return undefined;
  const out: AgentTaskUsage = {};
  if (typeof usage.total_tokens === 'number') out.totalTokens = usage.total_tokens;
  if (typeof usage.tool_uses === 'number') out.toolUses = usage.tool_uses;
  if (typeof usage.duration_ms === 'number') out.durationMs = usage.duration_ms;
  return Object.keys(out).length > 0 ? out : undefined;
}

function toClaudeTaskUpdate(msg: {
  subtype?: string;
  task_id?: string;
  tool_use_id?: string;
  description?: string;
  prompt?: string;
  task_type?: string;
  workflow_name?: string;
  status?: string;
  output_file?: string;
  summary?: string;
  usage?: Record<string, number | undefined>;
  last_tool_name?: string;
  // SDK .d.ts 未声明、运行时存在的字段;无契约,必须经 normalize 收窄后才能下发。
  workflow_progress?: unknown;
}, rt: RuntimeState, getSubagentTaskUsage?: (taskId: string) => AgentTaskUsage | undefined): AgentTaskUpdateEventData | null {
  if (!msg.task_id) return null;
  const parentToolUseId = msg.tool_use_id
    ?? rt.subagentParentToolUseIdByTaskId.get(msg.task_id);
  if (parentToolUseId) {
    rt.subagentParentToolUseIdByTaskId.set(msg.task_id, parentToolUseId);
  }
  let status: AgentTaskStatus = 'running';
  if (msg.subtype === 'task_notification') {
    status = msg.status === 'failed' || msg.status === 'stopped' ? msg.status : 'completed';
  }
  if (parentToolUseId) {
    // 事件乱序防线(与 user 消息回执分支同一条不变量):终态后的 task_started /
    // task_progress(恒 running)不得把内部终态登记降级回运行中。注意只挡 Map
    // 回写、不改事件投影——迟到的 running 帧仍按 running 下发,由下游
    // terminalBackgroundTaskIds 等按 taskId 的终态闩统一丢弃,两道闸口径一致。
    const previousStatus = rt.subagentStatusByParentToolUseId.get(parentToolUseId);
    const wouldDowngrade = status === 'running'
      && (previousStatus === 'completed' || previousStatus === 'failed' || previousStatus === 'stopped');
    if (!wouldDowngrade) {
      rt.subagentStatusByParentToolUseId.set(parentToolUseId, status);
    }
  }
  const sdkUsage = toClaudeTaskUsage(msg.usage);
  const hostUsage = msg.subtype === 'task_notification'
    ? getSubagentTaskUsage?.(msg.task_id)
    : undefined;
  // SDK 有非零统计时继续信任 SDK;只有明确为 0 / 缺失时才用 host 观测值修正。
  const usage = hostUsage && (sdkUsage?.totalTokens ?? 0) === 0
    ? { ...sdkUsage, totalTokens: hostUsage.totalTokens }
    : sdkUsage;
  const model = parentToolUseId
    ? rt.resolvedSubagentModelByParentToolUseId.get(parentToolUseId)
      ?? rt.streamModelByParentToolUseId.get(parentToolUseId)
    : undefined;
  if (parentToolUseId && model) {
    rt.publishedSubagentModelByParentToolUseId.set(parentToolUseId, model);
  }
  // CLI 对纯心跳帧节流省略该字段;收窄失败/缺失都不下发(undefined = 下游沿用上一帧)。
  const workflowProgress = normalizeWorkflowProgressEntries(msg.workflow_progress);
  const taskType = msg.task_type;
  const explicitlySubagent = taskType === 'local_agent' || taskType === 'remote_agent';
  const explicitlyExcluded = taskType === 'local_bash' || taskType === 'local_workflow';
  if (explicitlySubagent) {
    rt.confirmedSubagentTaskIds.add(msg.task_id);
    rt.excludedSubagentTaskIds.delete(msg.task_id);
  } else if (explicitlyExcluded && !rt.confirmedSubagentTaskIds.has(msg.task_id)) {
    rt.excludedSubagentTaskIds.add(msg.task_id);
  }
  const isExcludedTask =
    !rt.confirmedSubagentTaskIds.has(msg.task_id) &&
    (explicitlyExcluded || rt.excludedSubagentTaskIds.has(msg.task_id));
  const isKnownSubagent =
    !isExcludedTask &&
    (Boolean(parentToolUseId) || explicitlySubagent || rt.confirmedSubagentTaskIds.has(msg.task_id));
  const subagentObservation = !isExcludedTask && isKnownSubagent
    ? {
        kind:
          msg.subtype === 'task_started'
            ? 'spawn' as const
            : msg.subtype === 'task_notification'
              ? 'terminal' as const
              : 'progress' as const,
        logicalSubagentId: msg.task_id,
        ...(parentToolUseId ? { parentToolUseId } : {}),
      }
    : undefined;
  return {
    provider: 'claude-code',
    taskId: msg.task_id,
    ...(parentToolUseId ? { parentToolUseId } : {}),
    status,
    ...(msg.description ? { title: msg.description } : {}),
    ...(msg.prompt ? { description: msg.prompt } : {}),
    ...(msg.summary ? { summary: msg.summary } : {}),
    ...(msg.output_file ? { outputFile: msg.output_file } : {}),
    ...(msg.task_type ? { taskType: msg.task_type } : {}),
    ...(msg.workflow_name ? { workflowName: msg.workflow_name } : {}),
    ...(msg.last_tool_name ? { lastToolName: msg.last_tool_name } : {}),
    ...(usage ? { usage } : {}),
    ...(model ? { model } : {}),
    ...(workflowProgress ? { workflowProgress } : {}),
    ...(subagentObservation ? { subagentObservation } : {}),
  };
}

/**
 * SDKTaskUpdatedMessage(subtype: 'task_updated')→ AgentTaskUpdateEventData。
 *
 * task_updated 与 task_started/progress/notification 结构不同:它只带 task_id + patch
 * (无 tool_use_id / usage / workflow_name),是任务状态变化的增量补丁。下游 store 按
 * taskId 做字段级 merge,所以这里只回填补丁里真正变化的字段;缺失字段留给 merge 保留旧值。
 *
 * 关键:内部 AgentTaskStatus 恒为必填,而 patch.status 是可选的。若补丁里既无 status
 * 又无 error(纯 description / backgrounded 变更),直接返回 null 不下发 —— 否则会被迫
 * emit 一个 'running',把已到终态(completed/failed/stopped)的任务错误重置回运行中。
 */
function toClaudeTaskUpdatedPatch(msg: {
  task_id?: string;
  patch?: { status?: string; description?: string; error?: string };
}, rt: RuntimeState): AgentTaskUpdateEventData | null {
  if (!msg.task_id || !msg.patch) return null;
  const { status: rawStatus, description, error } = msg.patch;
  const hasStatus = typeof rawStatus === 'string' && rawStatus.length > 0;
  const hasError = typeof error === 'string' && error.length > 0;
  if (!hasStatus && !hasError) return null;
  const status = mapTaskUpdatedStatus(rawStatus, hasError);
  const parentToolUseId = rt.subagentParentToolUseIdByTaskId.get(msg.task_id);
  const isExcludedTask =
    !rt.confirmedSubagentTaskIds.has(msg.task_id) &&
    rt.excludedSubagentTaskIds.has(msg.task_id);
  const isKnownSubagent =
    !isExcludedTask &&
    (Boolean(parentToolUseId) || rt.confirmedSubagentTaskIds.has(msg.task_id));
  if (isKnownSubagent && parentToolUseId) {
    rt.subagentStatusByParentToolUseId.set(parentToolUseId, status);
  }
  return {
    provider: 'claude-code',
    taskId: msg.task_id,
    ...(parentToolUseId ? { parentToolUseId } : {}),
    status,
    ...(isKnownSubagent
      ? {
          subagentObservation: {
            kind: status === 'running' ? 'progress' : 'terminal',
            logicalSubagentId: msg.task_id,
            ...(parentToolUseId ? { parentToolUseId } : {}),
          },
        }
      : {}),
    ...(description ? { title: description } : {}),
    ...(hasError ? { summary: error } : {}),
  };
}

/**
 * patch.status(pending/running/completed/failed/killed)→ 内部 AgentTaskStatus。
 * killed → stopped;pending → running;无法识别的 status 但带 error → failed。
 */
function mapTaskUpdatedStatus(status: string | undefined, hasError: boolean): AgentTaskStatus {
  switch (status) {
    case 'completed':
      return 'completed';
    case 'failed':
      return 'failed';
    case 'killed':
      return 'stopped';
    case 'running':
    case 'pending':
      return 'running';
    default:
      return hasError ? 'failed' : 'running';
  }
}

// ── assistant 子分支 ─────────────────────────────────────────────────────────

/**
 * 只有不可见的 thinking 块不算 assistant 的实质产出。未知/新增块按有实质内容
 * 保守处理,避免 SDK 增加 server tool / control block 后被误判成 silent stop。
 */
function assistantBlockHasSubstance(block: Record<string, unknown>): boolean {
  if (block.type === 'text') {
    // Silent-stop 看上游有没有交出 text block,不看展示层清洗后还剩什么。
    // 整条只剩 `<|eos|>` 仍算正常收口;泄漏只在可见文本 / 落库路径隐藏。
    return typeof block.text === 'string' && block.text.length > 0;
  }
  if (block.type === 'thinking' || block.type === 'redacted_thinking') {
    return false;
  }
  return true;
}

/** Both envelope and streaming text use the root-only result fallback ledger. */
function recordRootEmittedText(ctx: TranslateContext, text: string, parentToolUseId?: string): void {
  if (parentToolUseId || text.length === 0) return;
  ctx.turn.hasEmittedText = true;
  ctx.turn.uiEmittedText += text;
}

function handleAssistant(
  msg: {
    message?: { content?: Array<Record<string, unknown>> };
    error?: string;
    parent_tool_use_id?: string | null;
  },
  queue: EventQueue,
  ctx: TranslateContext,
): void {
  // agent-meta: 抽 SDK uuid / parent_tool_use_id / sdkSessionId / model / ...
  // 给本 turn 内所有 push 用;正常消息才缓存到 ctx.rt.lastAssistantMeta 给 stream_event 兜底
  // (mid-turn text_delta / message_delta 没有自己的 uuid, 落库时取最近一条 assistant
  // 的 meta 作为 fallback, 让 messages.agent_meta 行能被 fork/rewind 反查到)。
  const assistantMeta = extractAssistantMeta(msg);
  if (
    typeof assistantMeta.requestId === 'string' &&
    assistantMeta.requestId.startsWith('msg_vrtx_')
  ) {
    ctx.turn.lastAssistantRequestId = assistantMeta.requestId;
  }

  // SDK API-error envelope: msg.error 是 SDKAssistantMessageError tag
  // (invalid_request / authentication_failed / rate_limit / server_error /
  // billing_error / max_output_tokens / unknown), message.content 是 cc-code
  // 在 services/api/errors.ts 已经写好的人话解释 (PROMPT_TOO_LONG_ERROR_MESSAGE,
  // "Run /rewind to recover.", CREDIT_BALANCE_TOO_LOW_ERROR_MESSAGE 等)。
  // SDK 内部用 isApiErrorMessage 标识这条不是真 turn, 但跨 SDK JSON 边界这个
  // flag 没透出, 只剩 msg.error。这里早走两件事:
  //  1) 暂存人话错误详情,等最终 ResultMessage 决定是否报错。envelope 后 SDK
  //     仍可能自动重试成功,此时提前推 terminal error 会让 desktop / Slack 先
  //     收口当前 turn,后续成功结果无法修正;
  //  2) **不**把 content 里的 text 当普通 assistant text 推到 chat —— 旧实现
  //     会推, 导致同一条人话既出现在聊天气泡又出现在 banner, 而且作为普通
  //     assistant message 落库, 后续 fork/rewind 把它一起带走, 旧 session 的
  //     错误 envelope 就这样污染到新 session 了。
  if (msg.error) {
    const errorText = (msg.message?.content ?? [])
      .map((b) => {
        const blk = b as { type?: string; text?: string };
        return blk.type === 'text' && typeof blk.text === 'string' ? blk.text : '';
      })
      .filter(Boolean)
      .join('\n')
      .trim();
    const errorMessage = errorText || `SDK error: ${msg.error}`;
    const errorSignals = extractNonSecretErrorSignals(errorMessage);
    ctx.turn.pendingApiError = {
      ...ctx.turn.pendingApiError,
      message: redactSensitiveText(errorMessage),
      sdkError: redactSensitiveText(msg.error),
      agentMeta: assistantMeta,
      modelAccessDenied: isModelAccessDenied(errorMessage, errorSignals.errorStatus),
      ...(errorSignals.errorStatus !== undefined
        ? { errorStatus: errorSignals.errorStatus }
        : {}),
      ...(errorSignals.usageLimit ? { usageLimit: true } : {}),
    };
    return;
  }

  // 一条正常 assistant 消息证明先前 API-error envelope 已恢复;避免同一 turn
  // 后续另一次失败误用旧 envelope 的错误详情。错误 envelope 也不能成为
  // lastAssistantMeta,避免恢复后的 fallback text 错绑到错误消息的 transcript 锚点。
  ctx.turn.pendingApiError = null;
  const parentToolUseId = typeof msg.parent_tool_use_id === 'string' && msg.parent_tool_use_id
    ? msg.parent_tool_use_id
    : undefined;
  // Child envelopes interleave with the root stream; they are never its
  // transcript fallback (including when the next root wrapper omits parent).
  if (!parentToolUseId) ctx.rt.lastAssistantMeta = assistantMeta;
  const parentStreamKey = parentToolUseId ?? CLAUDE_MAIN_USAGE_PARENT;
  const assistantRequestId = typeof assistantMeta.requestId === 'string'
    ? assistantMeta.requestId
    : undefined;
  if (
    assistantRequestId &&
    ctx.rt.streamRequestIdByParent.get(parentStreamKey) === assistantRequestId
  ) {
    ctx.rt.streamRequestIdByParent.delete(parentStreamKey);
  }
  // 子代理完整 assistant 没有 message_delta 时,result.usage 仍含其子输出,
  // 而父级 Agent 工具区间已从分母排除。记 sawSubagent,live tok/s 只用父级
  // streamed output,不再把整轮计时打成不可靠。
  if (parentToolUseId) observeClaudeSubagentStream(ctx, parentToolUseId);
  else observeMainAssistant(ctx, assistantRequestId);
  // 完整 child assistant 是实际执行模型的正式观测来源。SDK 不保证 child 的
  // partial message_start 一定向外暴露,所以不能只靠 handleStreamEvent 填模型;
  // 同时保持 main 新增的 loop guard 按 parent scope 读取同一张 stream model 表。
  // resolvedModel 若已由启动回执给出仍保持更高优先级;这里把观测提升成 parent-linked
  // task update,让实时卡片与后续 task_notification 都能沿用同一个 actual model。
  const assistantModel = typeof assistantMeta.model === 'string' && assistantMeta.model
    ? assistantMeta.model
    : undefined;
  if (parentToolUseId && assistantModel) {
    ctx.rt.streamModelByParentToolUseId.set(parentToolUseId, assistantModel);
    const actualModel = ctx.rt.resolvedSubagentModelByParentToolUseId.get(parentToolUseId)
      ?? assistantModel;
    const publishedModel = ctx.rt.publishedSubagentModelByParentToolUseId.get(parentToolUseId);
    if (publishedModel !== actualModel) {
      let taskId: string | undefined;
      for (const [candidateTaskId, candidateParentId] of ctx.rt.subagentParentToolUseIdByTaskId) {
        if (candidateParentId !== parentToolUseId) continue;
        taskId = candidateTaskId;
        break;
      }
      if (!taskId) {
        // child assistant 可能早于稳定 taskId 到达。只保留模型观测,等后续生命周期
        // 事件用真实 taskId 发布,避免按 parentToolUseId 造出无法收口的第二条任务。
      } else {
        const status = ctx.rt.subagentStatusByParentToolUseId.get(parentToolUseId) ?? 'running';
        ctx.rt.publishedSubagentModelByParentToolUseId.set(parentToolUseId, actualModel);
        queue.push({
          type: 'agent_task_update',
          data: {
            provider: 'claude-code',
            taskId,
            parentToolUseId,
            status,
            model: actualModel,
            subagentObservation: {
              kind: status === 'running' ? 'progress' : 'terminal',
              logicalSubagentId: taskId,
              parentToolUseId,
            },
          },
          source: 'claude-code',
        });
      }
    }
  }

  const content = msg.message?.content ?? [];
  // silent-stop 观测素材: 本条消息是否带实质内容(非空 text / 非 thinking 块)。
  // 未知块 fail-safe 为有内容,避免 SDK 新 block 被误续跑。
  // 逐条覆盖写, turn end 时留下的就是最后一条 assistant 消息的判定(见 TurnState 字段注释)。
  if (!parentToolUseId) {
    ctx.turn.lastAssistantMsgHadSubstance = content.some(assistantBlockHasSubstance);
  }
  for (const blockRaw of content) {
    const block = blockRaw as { type?: string; text?: string; name?: string; id?: string; input?: unknown; thinking?: string; signature?: string };
    if (block.type === 'text' && typeof block.text === 'string') {
      const prefix = `${parentStreamKey}:`;
      for (const key of ctx.rt.streamStopTokenByKey.keys()) {
        if (key === parentStreamKey || key.startsWith(prefix)) {
          ctx.rt.streamStopTokenByKey.delete(key);
        }
      }
      const visibleText = stripInternalWebCitations(block.text);
      if (!parentToolUseId) ctx.turn.text += visibleText;
      if (visibleText.length > 0) {
        recordRootEmittedText(ctx, visibleText, parentToolUseId);
        queue.push({
          type: 'text',
          data: { text: visibleText, isFinal: true },
          source: 'claude-code',
          agentMeta: assistantMeta,
        });
      }
    } else if (block.type === 'tool_use') {
      ctx.turn.toolUses += 1;
      // ctx.log.info('SDK ▷ tool_use', {
      //   toolName: block.name,
      //   toolUseId: block.id,
      //   turnToolUses: ctx.turn.toolUses,
      // });
      const toolUseId = rememberClaudeToolUseId(ctx, block.id, block.name);
      if (toolUseId) {
        // 完整 assistant 消息已带工具参数,即使没有 stream_event 也可在此停表。
        if (!parentToolUseId) pauseClaudeGenerationForToolUse(ctx, toolUseId);
        ctx.onToolUseStart?.(toolUseId, block.name, block.input, parentToolUseId);
      }
      queue.push({
        type: 'tool_use',
        data: {
          toolUseId: block.id,
          toolName: block.name,
          input: block.input,
        },
        source: 'claude-code',
        agentMeta: assistantMeta,
      });
    } else if (block.type === 'thinking' && typeof block.thinking === 'string') {
      const cur = ctx.rt.currentThinking;
      const blockId = cur?.blockId ?? `thinking-${block.signature?.slice(0, 12) ?? Date.now()}`;
      const durationMs = cur ? Date.now() - cur.startedAt : 0;
      queue.push({
        type: 'thinking',
        data: { stage: 'final', blockId, text: block.thinking, durationMs },
        source: 'claude-code',
        agentMeta: assistantMeta,
      });
      ctx.rt.currentThinking = null;
    } else if (block.type === 'redacted_thinking') {
      const blockId = `redacted-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
      queue.push({
        type: 'thinking',
        data: { stage: 'redacted', blockId },
        source: 'claude-code',
        agentMeta: assistantMeta,
      });
    }
  }
}

function rememberClaudeToolUseId(
  ctx: TranslateContext,
  toolUseId: unknown,
  toolName: unknown,
): string | null {
  if (typeof toolUseId !== 'string' || toolUseId.length === 0) return null;
  const existingName = ctx.rt.toolUseIdToName.get(toolUseId);
  ctx.rt.toolUseIdToName.set(
    toolUseId,
    typeof toolName === 'string' && toolName.length > 0
      ? toolName
      : (existingName ?? ''),
  );
  return toolUseId;
}

function pauseClaudeGenerationForToolUse(
  ctx: TranslateContext,
  toolUseId: unknown,
): void {
  if (typeof toolUseId !== 'string' || toolUseId.length === 0) return;
  pauseClaudeGeneration(ctx.rt.generation, toolUseId);
}

/** 只停本次主流请求 streamed 出来的 tool_use;见 mainRequestToolUseIds 字段注释。 */
function pauseClaudeGenerationForCurrentRequestTools(ctx: TranslateContext): void {
  for (const toolUseId of ctx.rt.mainRequestToolUseIds) {
    pauseClaudeGenerationForToolUse(ctx, toolUseId);
  }
  ctx.rt.mainRequestToolUseIds.clear();
}

/**
 * 子代理事件到达时:父级生成时钟必须已经因对应 Agent 工具停表。
 * 若 child 先于父级 tool_use / message_delta,用 parent_tool_use_id 作为既有
 * pause 边界关掉父级开区间,避免分母吞进子代理时间、分子却只有父级 output。
 * 没有开区间且 pending 为空时不 pause:result/reset 后的后台 child、以及
 * 本 turn 尚未 begin 的 child,都不得钉死旧 parent_tool_use_id,否则下一轮
 * parent message_start 无法 begin。已 resume 的 pause id 由
 * pauseClaudeGeneration 忽略,不会再次 close 当前开区间。
 */
function observeClaudeSubagentStream(
  ctx: TranslateContext,
  parentToolUseId: string,
): void {
  noteClaudeSubagent(ctx.rt.generation);
  if (ctx.rt.generation.pendingToolIds.has(parentToolUseId)) return;
  if (
    ctx.rt.generation.startedAt === null &&
    ctx.rt.generation.pendingToolIds.size === 0
  ) {
    return;
  }
  pauseClaudeGeneration(ctx.rt.generation, parentToolUseId);
}

// ── stream_event 子分支(content_block_delta / message_delta / message_start) ──

/** Main-thread live tok/s, mirroring pi-token-speed's message_update handlers. */
function observeClaudeTokenSpeed(
  event: {
    type?: string;
    index?: number;
    delta?: Record<string, unknown>;
    content_block?: { type?: string; name?: string };
  },
  queue: EventQueue,
  ctx: TranslateContext,
): void {
  const speed = ctx.rt.generation.tokenSpeed;
  const tools = ctx.rt.generation.tokenSpeedToolByIndex;
  const index = typeof event.index === 'number' ? event.index : 0;
  switch (event.type) {
    case 'message_start':
      tools.clear();
      return;
    case 'content_block_start':
      if (event.content_block?.type === 'tool_use') tools.set(index, event.content_block.name ?? '');
      speed.start();
      return;
    case 'content_block_delta': {
      const delta = event.delta;
      const text = delta?.type === 'input_json_delta'
        ? (tools.has(index) ? delta.partial_json : undefined)
        : delta?.text ?? delta?.thinking;
      if (typeof text === 'string' && speed.recordDelta(text)) {
        queue.push({ type: 'status', data: ccLiveStatus(ctx, 'Generating...', true), source: 'claude-code' });
      }
      return;
    }
    case 'content_block_stop':
      if (tools.has(index)) speed.pause();
      return;
  }
}

function handleStreamEvent(
  msg: {
    event?: Record<string, unknown>;
    parent_tool_use_id?: string | null;
  },
  queue: EventQueue,
  ctx: TranslateContext,
): void {
  const event = msg.event as {
    type?: string;
    index?: number;
    delta?: Record<string, unknown>;
    usage?: Record<string, number>;
    message?: { id?: string; model?: string; usage?: Record<string, number> };
    content_block?: { type?: string; id?: string; name?: string; input?: unknown };
  } | undefined;
  if (!event) return;

  const parentToolUseId = typeof msg.parent_tool_use_id === 'string' && msg.parent_tool_use_id
    ? msg.parent_tool_use_id
    : undefined;

  if (!parentToolUseId) observeClaudeTokenSpeed(event, queue, ctx);

  // 流式开头先登记工具身份;完整 assistant 消息才表示参数已交付。
  if (event.type === 'content_block_start') {
    const cb = event.content_block;
    if (cb && cb.type === 'text') {
      const blockIndex = typeof event.index === 'number' ? event.index : 0;
      ctx.rt.streamStopTokenByKey.delete(`${parentToolUseId ?? CLAUDE_MAIN_USAGE_PARENT}:${blockIndex}`);
    }
    if (cb && cb.type === 'tool_use') {
      const toolUseId = rememberClaudeToolUseId(ctx, cb.id, cb.name);
      if (toolUseId) {
        // loop-guard 仍要立刻拿到 tool id;上游 watchdog 等完整 assistant
        // tool_use 或 canUseTool 才停表。生成计时要等 message_delta 或完整
        // assistant tool_use: content_block_start
        // 早于参数 input_json_delta,这里停表会把参数生成时间从分母抠掉,
        // 而后续 message_delta 仍把这些 token 加进 outputTokens。
        if (!parentToolUseId) ctx.rt.mainRequestToolUseIds.add(toolUseId);
        ctx.onToolUseStart?.(toolUseId, cb.name, cb.input, parentToolUseId, true);
      }
    }
  }

  // SDKPartialAssistantMessage 自带 parent_tool_use_id;并发 subagent 会在同一 Query
  // 事件流中交错,必须按 parent 隔离模型,不能使用会话级 lastAssistantMeta 串联。
  // 老 SDK / 单测若没有 wrapper 元数据,才保留旧兜底行为。
  const parentStreamKey = parentToolUseId ?? CLAUDE_MAIN_USAGE_PARENT;
  const blockIndex = typeof event.index === 'number' ? event.index : 0;
  const streamKey = `${parentStreamKey}:${blockIndex}`;
  const eventModel = event.message?.model;
  if (typeof eventModel === 'string' && eventModel) {
    ctx.rt.streamModelByParentToolUseId.set(parentStreamKey, eventModel);
  }
  const eventRequestId = event.message?.id;
  if (typeof eventRequestId === 'string' && eventRequestId) {
    ctx.rt.streamRequestIdByParent.set(parentStreamKey, eventRequestId);
  }
  const streamModel = typeof eventModel === 'string' && eventModel
    ? eventModel
    : ctx.rt.streamModelByParentToolUseId.get(parentStreamKey);
  const streamRequestId = typeof eventRequestId === 'string' && eventRequestId
    ? eventRequestId
    : ctx.rt.streamRequestIdByParent.get(parentStreamKey);
  const fallbackMeta: Record<string, unknown> | undefined = parentToolUseId
    ? {
        parentUuid: parentToolUseId,
        ...(streamModel ? { model: streamModel } : {}),
        ...(streamRequestId ? { requestId: streamRequestId } : {}),
      }
    : ctx.rt.lastAssistantMeta
      ? {
          ...ctx.rt.lastAssistantMeta,
          ...(streamModel ? { model: streamModel } : {}),
          ...(streamRequestId ? { requestId: streamRequestId } : {}),
        }
      : streamModel || streamRequestId
        ? {
            ...(streamModel ? { model: streamModel } : {}),
            ...(streamRequestId ? { requestId: streamRequestId } : {}),
          }
        : undefined;

  if (event.type === 'content_block_delta') {
    const delta = event.delta as { type?: string; text?: string; thinking?: string } | undefined;
    if (!delta) return;
    if (delta.type === 'text_delta' && typeof delta.text === 'string') {
      const buffer = ctx.rt.streamStopTokenByKey.get(streamKey)
        ?? { pending: '', emitted: false };
      const visibleDelta = holdStandaloneStopTokenDelta(buffer, delta.text);
      ctx.rt.streamStopTokenByKey.set(streamKey, buffer);
      if (visibleDelta && visibleDelta.length > 0) {
        recordRootEmittedText(ctx, visibleDelta, parentToolUseId);
        queue.push({
          type: 'text',
          data: { text: visibleDelta, isFinal: false },
          source: 'claude-code',
          agentMeta: fallbackMeta,
        });
      }
    } else if (delta.type === 'thinking_delta' && typeof delta.thinking === 'string') {
      // 第一次见 thinking_delta 时 lazy-init 一个 buffer (老链路 agentManager.ts:2322-2335)
      if (!ctx.rt.currentThinking) {
        const blockId = `thinking-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
        ctx.rt.currentThinking = { blockId, startedAt: Date.now(), text: '' };
        queue.push({
          type: 'thinking',
          data: { stage: 'start', blockId, startedAt: ctx.rt.currentThinking.startedAt },
          source: 'claude-code',
          agentMeta: fallbackMeta,
        });
      }
      ctx.rt.currentThinking.text += delta.thinking;
      queue.push({
        type: 'thinking',
        data: {
          stage: 'delta',
          blockId: ctx.rt.currentThinking.blockId,
          text: delta.thinking,
        },
        source: 'claude-code',
        agentMeta: fallbackMeta,
      });
    }
    return;
  }

  if (event.type === 'message_delta') {
    // message_delta 是整条 assistant 消息(含工具参数 token)生成完毕后的
    // 第一个事件。在此停表,才能排除工具执行/审批等待,又不把参数生成
    // 区间从 tok/s 分母里抠掉。只有主流自己的 message_delta 才停主时钟:
    // 子代理 delta 到达时父级可能正在并行生成(后台 Agent),不许提前切断。
    if (!parentToolUseId) pauseClaudeGenerationForCurrentRequestTools(ctx);
    const usage = event.usage;
    if (usage) {
      const dIn = usage.input_tokens ?? 0;
      const dOut = usage.output_tokens ?? 0;
      const dCacheRead = usage.cache_read_input_tokens ?? 0;
      const dCacheCreate = usage.cache_creation_input_tokens ?? 0;
      // 累加进 tracker (跨多个 message_delta 会一直涨 —— 对标老 agentManager.ts:2362-2365
      // 的 session.currentTurn{Input,Output,CacheRead,CacheCreate}Tokens += dX)
      const segmentId =
        ctx.rt.activeUsageSegmentByParent.get(parentStreamKey) ??
        `claude:${++ctx.rt.usageSegmentSeq}:${parentStreamKey}`;
      ctx.rt.activeUsageSegmentByParent.set(parentStreamKey, segmentId);
      const priceVariant =
        ctx.rt.activeUsagePriceVariantByParent.get(parentStreamKey) ??
        ctx.rt.pendingUsagePriceVariantByParent.get(parentStreamKey) ??
        ctx.turn.nextRequestPriceVariant ??
        (ctx.getFastMode?.() ? 'priority' : 'standard');
      const hasCompleteUsageSnapshot = [
        'input_tokens',
        'output_tokens',
        'cache_read_input_tokens',
        'cache_creation_input_tokens',
      ].every((field) => Object.prototype.hasOwnProperty.call(usage, field));
      const previousOutput = ctx.tracker.getTurnUsage().output;
      ctx.tracker.upsertApiCallUsage(segmentId, {
        id: segmentId,
        model: streamModel ?? ctx.getModel(),
        priceVariant,
        inputTokens: dIn,
        outputTokens: dOut,
        cacheReadTokens: dCacheRead,
        cacheCreateTokens: dCacheCreate,
        complete: hasCompleteUsageSnapshot,
      });
      if (parentToolUseId) noteClaudeSubagent(ctx.rt.generation);
      else if (ctx.tracker.getTurnUsage().output > previousOutput) {
        // Upserts retain the largest output count. Input-only, duplicate, and
        // older usage must not advance the paired denominator on their own.
        ctx.rt.generation.outputDurationMs = sampleGenerationDuration(
          ctx.rt.generation.durationMs,
          ctx.rt.generation.startedAt,
        );
      }
      // 每次 API 回合的 token 增量打一行 —— 一个 turn 可能多个 message_delta(工具循环),
      // 让人看日志能直观看到 token 是怎么涨上去的, 而不是只在 turn end 看到一个总数。
      ctx.log.debug('SDK ▷ token usage (message_delta)', {
        sdkSessionId: ctx.getSdkSessionId(),
        title: ctx.getLogTitle(),
        delta: { in: dIn, out: dOut, cacheRead: dCacheRead, cacheCreate: dCacheCreate },
        cumulative: ctx.tracker.snapshot(),
      });
      // 数值全部走 tracker.snapshot() —— 单一可信源, 不再自己拼
      const snap = ctx.tracker.snapshot();
      queue.push({
        type: 'status',
        data: ccLiveStatus(ctx, 'Generating...', true),
        source: 'claude-code',
      });
      // Maker Memory flush 观察 (A 轻版: 只打日志). 缺省没注册时 no-op。
      ctx.onUsageUpdate?.(snap.contextTokens, snap.contextWindow);
    }
    return;
  }

  if (event.type === 'message_stop') {
    if (!parentToolUseId) settleMainRequest(ctx);
    return;
  }

  if (event.type === 'message_start') {
    // 新 API call 开始, 清掉残留 thinking buffer。
    // message_start 内 message.model 是这一 API call 真实用的模型,
    // setModel 切换后这里会先反映出来 —— 打日志方便排查"为什么这一轮跑了别的模型"。
    ctx.rt.currentThinking = null;
    ctx.log.debug('SDK ▷ API call start (message_start)', {
      model: event.message?.model ?? ctx.getModel(),
    });
    ctx.turn.apiCalls += 1;
    // 上一请求缺 message_stop(中断、重试)时,在新请求开段前补收口。
    if (!parentToolUseId) settleMainRequest(ctx);
    const segmentId = `claude:${++ctx.rt.usageSegmentSeq}:${parentStreamKey}`;
    ctx.rt.activeUsageSegmentByParent.set(parentStreamKey, segmentId);
    if (!parentToolUseId) {
      ctx.rt.mainOpenRequest = {
        ...(typeof eventRequestId === 'string' && eventRequestId ? { requestId: eventRequestId } : {}),
        sawAssistant: false,
      };
    }
    const priceVariant =
      ctx.rt.pendingUsagePriceVariantByParent.get(parentStreamKey) ??
      ctx.turn.nextRequestPriceVariant ??
      (ctx.getFastMode?.() ? 'priority' : 'standard');
    ctx.rt.pendingUsagePriceVariantByParent.delete(parentStreamKey);
    ctx.rt.activeUsagePriceVariantByParent.set(parentStreamKey, priceVariant);

    // 第三方 proxy(如 litellm)或官方端点通常在 message_start 给出 input_tokens
    const usage = event.message?.usage as Record<string, number> | undefined;
    if (usage) {
      const dIn = usage.input_tokens ?? 0;
      const dCacheRead = usage.cache_read_input_tokens ?? 0;
      const dCacheCreate = usage.cache_creation_input_tokens ?? 0;
      if (dIn > 0 || dCacheRead > 0 || dCacheCreate > 0) {
        ctx.tracker.upsertApiCallUsage(segmentId, {
          id: segmentId,
          model: event.message?.model ?? streamModel ?? ctx.getModel(),
          priceVariant,
          inputTokens: dIn,
          outputTokens: 0,
          cacheReadTokens: dCacheRead,
          cacheCreateTokens: dCacheCreate,
          complete: false,
        });
      }
    }

    // 不清 tracker —— message_start 在 turn 中可能出现多次(工具循环每次 API call 都会触发),
    // 老链路 agentManager.ts:2400-2407 这里也是带 currentTurn 累计, 不重置。
    // 子代理 stream 不占用父级生成时钟。若对应 Agent 工具尚未停表,在此用
    // parent_tool_use_id 补上既有 pause 边界,避免分母吞进子代理时间。
    if (parentToolUseId) observeClaudeSubagentStream(ctx, parentToolUseId);
    else {
      // 新主流请求边界: 上一请求残留的 tool id 已过期(失败重试的请求不会再有
      // message_delta);还挂着的 pending 视作已在 SDK 内部收口(echo 不会来了),
      // 由 beginClaudeGenerationAtRequestStart 结清并重启时钟。
      ctx.rt.mainRequestToolUseIds.clear();
      beginClaudeGenerationAtRequestStart(ctx.rt.generation);
    }
    queue.push({
      type: 'status',
      data: ccLiveStatus(ctx, 'Generating...', true),
      source: 'claude-code',
    });
    return;
  }
}

// ── result 子分支(turn end) ─────────────────────────────────────────────────

function handleResult(
  msg: {
    stop_reason?: string;
    is_error?: boolean;
    duration_ms?: number;
    duration_api_ms?: number;
    num_turns?: number;
    total_cost_usd?: number;
    terminal_reason?: string;
    usage?: {
      input_tokens?: number;
      output_tokens?: number;
      cache_read_input_tokens?: number;
      cache_creation_input_tokens?: number;
    };
    modelUsage?: Record<string, { inputTokens?: number; outputTokens?: number; costUSD?: number; contextWindow?: number }>;
    result?: string;
  },
  queue: EventQueue,
  ctx: TranslateContext,
): void {
  // 被打断 turn 的迟到 result, 且其后新 send 已接管(代际前进): 整条丢弃。
  // 不能走任何收尾 —— usage endTurn 会关错新 turn 的桶, status Done/done 会被
  // main 当作当前 turn 边界提前终结新 turn(见 TurnState.generation)。标记随
  // 消费清除;被打断 turn 的 usage 尾巴随之丢失(可接受: 打断路径自身已推过
  // 带 reason 的 terminal error, 记账以新 turn 为准)。
  if (
    msg.is_error &&
    ctx.turn.interruptRequested &&
    ctx.turn.generation !== ctx.turn.interruptGeneration
  ) {
    ctx.turn.interruptRequested = false;
    ctx.log.debug('dropping stale interrupted result (superseded by a newer send)', {
      generation: ctx.turn.generation,
      interruptGeneration: ctx.turn.interruptGeneration,
    });
    return;
  }
  const finalText = (typeof msg.result === 'string' && msg.result.length > 0)
    ? msg.result
    : ctx.turn.text;
  // 顶层 model 表示当前 runtime model; modelUsage 是累计分桶, 只作为诊断字段。
  const currentModel = ctx.getModel();
  const modelsUsed = msg.modelUsage ? Object.keys(msg.modelUsage) : [];

  // contextWindow: 优先取当前 model 的 modelUsage[model].contextWindow,
  // 否则按 model prefix 匹配, 再否则取 modelUsage 里最大的非零 contextWindow。
  // 完全对标 agentManager.ts:2600-2616 三段 fallback。
  // 0 表示"SDK 未给", renderer 端有 model prefix → 200K/1M 兜底。
  let contextWindow = 0;
  let contextWindowSource:
    | 'sdk:modelUsage:exact'
    | 'sdk:modelUsage:prefix'
    | 'sdk:modelUsage:max'
    | 'fallback:model-capability-config' = 'fallback:model-capability-config';
  let contextWindowFallbackReason = msg.modelUsage
    ? 'modelUsage.contextWindow missing'
    : 'modelUsage missing';
  if (msg.modelUsage) {
    const exact = msg.modelUsage[currentModel];
    if (exact?.contextWindow) {
      contextWindow = exact.contextWindow;
      contextWindowSource = 'sdk:modelUsage:exact';
      contextWindowFallbackReason = '';
    } else {
      const prefixEntry = Object.entries(msg.modelUsage).find(([k]) =>
        modelIdsMatchForContextWindow(currentModel, k),
      );
      if (prefixEntry?.[1]?.contextWindow) {
        contextWindow = prefixEntry[1].contextWindow;
        contextWindowSource = 'sdk:modelUsage:prefix';
        contextWindowFallbackReason = '';
      } else {
        for (const mu of Object.values(msg.modelUsage)) {
          const candidateWindow = mu.contextWindow ?? 0;
          if (candidateWindow > contextWindow) {
            contextWindow = candidateWindow;
            contextWindowSource = 'sdk:modelUsage:max';
            contextWindowFallbackReason = '';
          }
        }
      }
    }
  }
  // 窗口口径: catalog(host 按 agent 声明的 capabilities.availableModels[].contextWindow,
  // 经 ctx.getModelContextWindow 透传)是权威值, 但**只在以下两种情形**覆盖 SDK 上报值:
  //  (a) SDK 的窗口确实属于**当前模型**(modelUsage 里有 key 去 [1m] 后与当前模型完全相等
  //      且带正窗口)—— 这是折扣模型被 [1m] 误报 1M 的主场景, 用 catalog 锁回真实窗口
  //      (如 codex/gpt-5.5 cc=272k), 让 auto-compact / memory-flush 按真实窗口触发。
  //  (b) SDK 没给窗口或只给了 unknown-model 默认小窗口(≤200K)—— 升级到 catalog。
  // **不覆盖** SDK 给了某个**别的模型**的非默认窗口(>200K)的情形: 典型是 turn 运行中途切了
  // 模型(mutableModel 立即变, 但 msg.modelUsage 仍是产出本 result 的旧模型), 此时 SDK 窗口
  // 才是这一轮真实模型的窗口, 用 catalog(新模型)覆盖会把快照记错。
  // 关键: 判"属于当前模型"必须用**归一后严格相等**, 不能用 modelIdsMatchForContextWindow 的
  // startsWith 松匹配 —— 否则 `gpt-5.4-mini`(272k)会被当成当前 `gpt-5.4`(1M)的匹配, 切模型后
  // 把 mini 的 result 窗口错记成 1M(Codex P2)。[1m] 后缀差异由 normalize 去掉后仍相等。
  const configuredContextWindow = ctx.getModelContextWindow?.();
  const normalizedCurrentModel = normalizeModelForContextWindow(currentModel);
  const sdkWindowIsForCurrentModel =
    !!msg.modelUsage &&
    Object.entries(msg.modelUsage).some(
      ([k, mu]) =>
        normalizeModelForContextWindow(k) === normalizedCurrentModel && (mu?.contextWindow ?? 0) > 0,
    );
  const sdkWindowUnknownOrDefault = contextWindow <= 200_000; // 0=未给; ≤200K=unknown-model 默认
  if (
    typeof configuredContextWindow === 'number' &&
    configuredContextWindow > 0 &&
    configuredContextWindow !== contextWindow &&
    (sdkWindowIsForCurrentModel || sdkWindowUnknownOrDefault)
  ) {
    contextWindowFallbackReason =
      contextWindow > 0
        ? `configured contextWindow ${configuredContextWindow} overrides SDK modelUsage ${contextWindow}`
        : '';
    contextWindow = configuredContextWindow;
    contextWindowSource = 'fallback:model-capability-config';
  }
  ctx.tracker.setContextWindow(contextWindow);

  const resultUsage = msg.usage
    ? resultUsageToTurnDelta(ctx.rt.lastResultUsageAggregate, {
        inputTokens: msg.usage.input_tokens ?? 0,
        outputTokens: msg.usage.output_tokens ?? 0,
        cacheReadTokens: msg.usage.cache_read_input_tokens,
        cacheCreateTokens: msg.usage.cache_creation_input_tokens,
      })
    : undefined;
  // 记下覆盖前的真实 aggregate 基线: 空响应轮(result.usage 报 0)要在下方 empty-response
  // 守卫里**还原**它。否则基线被这 0 覆盖后, 下一个真实 turn 会拿 SDK 的累计 result.usage
  // 去减 0, 把整段历史 token 全算到那一轮、虚高单轮 usage/context 账务(Codex P2)。
  const aggregateBeforeThisResult = ctx.rt.lastResultUsageAggregate;
  if (msg.usage) {
    ctx.rt.lastResultUsageAggregate = {
      inputTokens: msg.usage.input_tokens ?? 0,
      outputTokens: msg.usage.output_tokens ?? 0,
      cacheReadTokens: msg.usage.cache_read_input_tokens,
      cacheCreateTokens: msg.usage.cache_creation_input_tokens,
    };
  }

  if (resultUsage) {
    ctx.tracker.ingestTurnAggregateCacheStats({
      inputTokens: resultUsage.inputTokens,
      cacheReadTokens: resultUsage.cacheReadTokens,
      cacheCreateTokens: resultUsage.cacheCreateTokens,
    });
  }

  // 空响应判定(提前到 endTurn 之前算): 本轮发起过 API call 但 0 产出(无 UI 文本 /
  // 无 result 兜底文本 / 无 tool 调用)且本轮 usage 增量全 0 —— 典型是模型网关(尤其折扣
  // 网关)在大上下文 / 高负载下短路返回 HTTP 200 + 空 SSE 流(input_tokens=0)。提前算的原因:
  //  (a) 让下面的 endTurn 在空响应轮**不要** replaceLastApi(守卫加 !isEmptyResponseTurn),
  //      否则会用本轮 0 增量覆盖 tracker.lastApi、把 contextTokens 清成 0 —— auto-compact /
  //      memory-flush / UI 环看不到真实 context, 用户重试会反复撞同一超限空响应而非先压缩。
  //      保留上一轮真实 lastApi 才能让护栏在空响应后仍按真实占用决策。
  //  (b) 收口处复用同一判定 surface terminal error。
  // 守卫: !is_error(is_error 另有 envelope/WARN, 不重复)、!sawCompactBoundary(compact-only
  //   空轮合法)、apiCalls>0(排除 "result 无 API call" 的合法退化, 见对应单测)。
  // usage 判 0 用 per-turn delta(resultUsage), **不能**用 msg.usage —— 后者是子进程 session
  // 累计值, 长会话本轮空响应时仍带历史非零 input_tokens 会漏判(正是长会话"假死"场景)。
  // result.usage 缺失(resultUsage=undefined)时**回退到 tracker 的本轮累计**, 而不是当成全 0:
  // 有些 provider 不在 result 报 usage, 但已通过 message_start / message_delta 上报并被
  // ingestApiCallUsage 累进 currentTurn。若此时当成全 0, "消耗了 token 但 result 没带 usage"
  // 的正常轮会被误判成空响应 terminal error(Codex P2)。tracker.getTurnUsage() 在 endTurn
  // 之前读到的正是本轮 streamed 累计;真正的空网关响应该累计也为 0, 不影响判定。
  const emitted = ctx.turn.uiEmittedText;
  const full = !msg.is_error && typeof msg.result === 'string'
    ? stripInternalWebCitations(msg.result)
    : '';
  let turnUsageDeltaAllZero: boolean;
  if (resultUsage) {
    turnUsageDeltaAllZero =
      resultUsage.inputTokens === 0 &&
      resultUsage.outputTokens === 0 &&
      (resultUsage.cacheReadTokens ?? 0) === 0 &&
      (resultUsage.cacheCreateTokens ?? 0) === 0;
  } else {
    const trackerTurn = ctx.tracker.getTurnUsage();
    turnUsageDeltaAllZero =
      trackerTurn.input === 0 &&
      trackerTurn.output === 0 &&
      trackerTurn.cacheRead === 0 &&
      trackerTurn.cacheCreate === 0;
  }
  const isEmptyResponseTurn =
    !msg.is_error &&
    !ctx.turn.sawCompactBoundary &&
    emitted.length === 0 &&
    full.length === 0 &&
    ctx.turn.toolUses === 0 &&
    ctx.turn.apiCalls > 0 &&
    turnUsageDeltaAllZero;

  // 上下文超限终态判定(提前到 endTurn 之前算, #1429): 超限请求被上游 400 整体拒绝,
  // 不返回 usage —— tracker.lastApi 停在上一次成功值(会话重启后首轮就失败则是 0),
  // 圆环显示低占用甚至 0%, auto-compact 的 ratio 永远到不了阈值, 会话进入
  // "超限 → 无 usage → 不压缩 → 重试再超限"的自锁。提前算的原因(与 isEmptyResponseTurn
  // 的提前同构):
  //  (a) 在 endTurn 前 markContextOverflow() 把 tracker 锁到窗口满载, endSnapshot 的
  //      contextTokens 如实反映"已超限"(status Done / done 事件跟随);
  //  (b) 下方 ctx.onUsageUpdate 用该 endSnapshot 把 ratio=1.0 喂给 auto-compact /
  //      memory-flush, turn end 即触发一次静默 /compact。best-effort: 压缩请求自身
  //      发送全量历史, 真超限时可能同样失败; 失败轮不产生 compact_boundary,
  //      AutoCompactController.fired 保持置位, 不会循环重压;
  //  (c) endTurn 的 replaceLastApi 守卫加 !isContextOverflowTurn: 失败轮的 usage delta
  //      通常为 0, 放任覆盖会把 (a) 刚锁上的满载值又冲回 0;
  //  (d) is_error 分支给 error 事件带 CONTEXT_OVERFLOW_REASON, renderer 按稳定 key
  //      隐藏必败的 Retry 并给出压缩 / 新开会话入口。
  // 判定文本 = result 原文 + pendingApiError.message(信息可能只在其一; pattern 只认
  // 错误措辞形态, 与 provider 无关)。interruptRequested 排除与下方 is_error 分支一致。
  const isContextOverflowTurn =
    Boolean(msg.is_error) &&
    !ctx.turn.interruptRequested &&
    isContextOverflowErrorMessage(
      `${typeof msg.result === 'string' ? msg.result : ''}\n${ctx.turn.pendingApiError?.message ?? ''}`,
    );
  if (isContextOverflowTurn) ctx.tracker.markContextOverflow();

  // turn 桶快照 — endTurn 会清掉 turn 桶, 必须在调用之前先取出来给后面日志用
  const preTurnEndCacheStats = ctx.tracker.getCacheStats();
  const turnUsageSegments = ctx.tracker.getTurnUsageSegments();
  const segmentTotals = turnUsageSegments.reduce<{
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens: number;
    cacheCreateTokens: number;
  }>(
    (sum, segment) => ({
      inputTokens: sum.inputTokens + segment.inputTokens,
      outputTokens: sum.outputTokens + segment.outputTokens,
      cacheReadTokens: sum.cacheReadTokens + (segment.cacheReadTokens ?? 0),
      cacheCreateTokens: sum.cacheCreateTokens + (segment.cacheCreateTokens ?? 0),
    }),
    { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0 },
  );
  const segmentsMatchResult = resultUsage
    ? segmentTotals.inputTokens === resultUsage.inputTokens &&
      segmentTotals.outputTokens === resultUsage.outputTokens &&
      segmentTotals.cacheReadTokens === (resultUsage.cacheReadTokens ?? 0) &&
      segmentTotals.cacheCreateTokens === (resultUsage.cacheCreateTokens ?? 0)
    : false;
  // Only declare request segments complete when an independent turn delta
  // proves that they cover every token bucket. A matching request count is not
  // enough: some providers report cache usage only in the terminal aggregate.
  // On the first result after resume that aggregate may still include history,
  // so a mismatch must fail closed to token-only accounting rather than price
  // an incomplete set of requests.
  const usageSegmentsComplete = segmentsMatchResult;
  const finalTextForLogs = msg.is_error ? redactSensitiveText(finalText) : finalText;

  // turn end usage 锁定: Claude Code result.usage 是 session aggregate,
  // 这里先转成 turn delta; tracker.endTurn 内部覆盖 currentTurn 然后返回 snapshot 再 reset。
  settleMainRequest(ctx);
  finalizeClaudeGeneration(ctx.rt.generation);
  const liveTurnOutput = liveParentOutputTokens(
    ctx,
    resultUsage?.outputTokens,
    resultUsage != null && segmentTotals.outputTokens === resultUsage.outputTokens,
  );
  const liveGeneration = ctx.rt.generation;
  // Snap to this turn's streamed main-thread usage: the result aggregate can be
  // a session total turned into a wrong delta, and a bad snap is worse than the estimate.
  liveGeneration.tokenSpeed.stop(mainTurnOutputTokens(ctx.tracker));
  const endSnapshot = ctx.tracker.endTurn(
    resultUsage
      ? {
          inputTokens: resultUsage.inputTokens,
          outputTokens: resultUsage.outputTokens,
          cacheReadTokens: resultUsage.cacheReadTokens,
          cacheCreateTokens: resultUsage.cacheCreateTokens,
          costUsd: msg.total_cost_usd,
          // 空响应轮不 replaceLastApi: 否则用本轮 0 增量覆盖 lastApi, 丢掉上一轮真实 context。
          // 超限轮同理: markContextOverflow 刚锁上的满载值不能被失败轮的 0 增量冲掉。
          replaceLastApi:
            ctx.turn.apiCalls === 1 &&
            !ctx.turn.sawCompactBoundary &&
            !isEmptyResponseTurn &&
            !isContextOverflowTurn,
        }
      : undefined,
  );

  // Maker Memory flush / auto-compact 观察 — turn end 时用 endTurn 后的最终
  // contextTokens/contextWindow 算 ratio,否则 result-only cache tokens 会晚一轮触发。
  ctx.onUsageUpdate?.(endSnapshot.contextTokens, endSnapshot.contextWindow);

  // per-model cost 分桶 (覆盖语义, msg.modelUsage[model].costUSD 是子进程内累计)。
  // 不入 snapshot, 不影响 UI, 仅供日志与未来按模型展示。
  if (msg.modelUsage) {
    const modelCosts: Record<string, number> = {};
    for (const [model, mu] of Object.entries(msg.modelUsage)) {
      if (typeof mu.costUSD === 'number') modelCosts[model] = mu.costUSD;
    }
    ctx.tracker.ingestModelCosts(modelCosts);
  }

  // cache 命中率 — 同时打 turn / session 两个粒度, 排查第三方 proxy 透传问题用
  // (走 tracker.getCacheStats() 拿; 注意要在 endTurn() 之前调用, 否则 turn 桶已被清零)
  // 但本函数中 endTurn 已经在上面执行了, 这里读到的 turn 桶必然是空 —— 所以改成
  // 在 endTurn 之前先快照一份 turnCacheStats 出来, 这里只读 session。
  // ↑ 见下方 endTurn 调用前的 preTurnEndCacheStats。
  ctx.log.debug('SDK ◀ turn end (result)', {
    model: currentModel,
    modelsUsed: modelsUsed.length > 0 ? modelsUsed : undefined,
    effort: ctx.getEffort(),
    permissionMode: ctx.getPermissionMode(),
    stopReason: msg.stop_reason,
    terminalReason: msg.terminal_reason,
    isError: msg.is_error,
    durationMs: msg.duration_ms,
    durationApiMs: msg.duration_api_ms,
    numTurns: msg.num_turns,
    apiCalls: ctx.turn.apiCalls,
    costUsd: msg.total_cost_usd,
    inputTokens: msg.usage?.input_tokens,
    outputTokens: msg.usage?.output_tokens,
    cacheReadTokens: msg.usage?.cache_read_input_tokens,
    contextWindow,
    contextWindowSource,
    contextWindowFallbackReason: contextWindowFallbackReason || undefined,
    costByModel: ctx.tracker.getCostByModel(),
    cacheStats: {
      turn: formatCacheBucket(preTurnEndCacheStats.turn),
      session: formatCacheBucket(ctx.tracker.getCacheStats().session),
    },
    toolUses: ctx.turn.toolUses,
    output: finalTextForLogs || '<empty>',
  });
  // turn 以 error 结束时上面只有 DEBUG 落盘 — debug 关 (release 默认 info) 时用户
  // 上报的 maker.log 里会完全看不到这次失败 (API 限流 / 上游 5xx /
  // error_during_execution / context 超限等)。补一条 WARN 保证 info 级可见。
  if (msg.is_error) {
    ctx.log.warn('SDK ◀ turn ended with error', {
      stopReason: msg.stop_reason,
      terminalReason: msg.terminal_reason,
      durationMs: msg.duration_ms,
      output: finalTextForLogs || '<empty>',
    });
  }
  // 流式截断兜底(后缀 diff 版)—— 覆盖两种截断:
  //   ① 整轮全空:上游 SSE 首包后 stall,一个 text event 都没推过(uiEmittedText 空)。
  //   ② 末尾截断:前面 call 推过旁白(uiEmittedText 非空),但最后一次 call 的最终回复被截断,
  //      只在 result.result 里、没推过 UI —— e7ea882b 的 !hasEmittedText 守卫覆盖不到这种。
  // result.result 是 SDK 兜出的本 turn 完整 assistant 文本;uiEmittedText 是我们实际推给 UI 的部分。
  // 二者做前缀比对,只补 UI 缺的那段(fallbackTail),绝不重复 —— renderer 的 DUP-SKIP 只能挡
  // "完全相同",挡不住"整段 result 与已推旁白部分重叠",所以必须在这里精确切尾,不能整段补。
  //  - full(emitted 空)     : 补整段(= e7ea882b 原行为)
  //  - tail(full 以 emitted 为前缀且更长): 只补尾部 —— 修复盲区②
  //  - complete(full===emitted)          : 已完整,不补(绝大多数正常 turn 走这)
  //  - mismatch(前缀对不上)              : 保守不补,退化成现状(宁可漏补也不错乱/重复)
  // is_error 时整段不补:error envelope 文本走单独 error event/banner,补了会与 banner 重复。
  // 刻意不带 agentMeta:补推文本是"孤儿正文",lastAssistantMeta 当锚点会污染 fork/rewind。
  // emitted / full 已在上方(空响应判定处)算好, 这里复用。
  let fallbackTail = '';
  if (full.length > 0) {
    if (emitted.length === 0) {
      fallbackTail = full;
    } else if (full.startsWith(emitted)) {
      fallbackTail = full.slice(emitted.length);
    }
  }
  if (fallbackTail.length > 0) {
    queue.push({
      type: 'text',
      // fallbackTail 是「UI 尚未收到的追加段」,不是整条 assistant 全文。
      // 按 delta 发出才能在已有气泡中正确追加,随后的 done 负责收口。
      data: { text: fallbackTail, isFinal: false },
      source: 'claude-code',
    });
  }
  // silent-stop 判定: turn 内干过活(有 tool 调用),或整轮没有任何用户可见正文,且最后
  // 一条 assistant 消息没有实质内容(典型: 只有 thinking 块),result 也没兜出可补的
  // 文本 —— 上游把 turn 静默收了尾,用户侧表现为"干着干着停了、看起来像正常结束"。已知
  // 上游形态: 模型偶发 thinking-only 空响应(anthropics/claude-code#50597,
  // stop_reason=end_turn)与 SSE 流被静默中断后 SDK 按正常结束处理(#38905, 此形态
  // stop_reason 常缺失)。与 isEmptyResponseTurn(整轮 0 产出 + usage 全 0)互斥:
  // 零 tool 但零可见正文也必须命中:第一次自动补发「继续」后,上游可能再次只返回
  // thinking;旧的 toolUses > 0 守卫会把第二次当正常完成。已有可见正文的零 tool turn
  // 则不扩张判定。沿用 turn 收尾同款排除项: is_error(另有 error 收尾)、
  // interruptRequested(用户停止/watchdog)、sawCompactBoundary(compact 轮合法空)。
  // 命中后事件流仍走正常 Done/done 收尾(记账/收口零变更), 只在 done.data 附加
  // silentStop 标记交给 host 的自动续跑守卫决策; WARN 日志保留作 dev 排查。
  const isSilentStopTurn =
    !msg.is_error &&
    !ctx.turn.interruptRequested &&
    !ctx.turn.sawCompactBoundary &&
    !isEmptyResponseTurn &&
    (ctx.turn.toolUses > 0 || ctx.turn.uiEmittedText.length === 0) &&
    !ctx.turn.lastAssistantMsgHadSubstance &&
    fallbackTail.length === 0;
  if (isSilentStopTurn) {
    ctx.log.warn('SDK ◀ turn ended by silent stop (last assistant message had no content)', {
      model: currentModel,
      stopReason: msg.stop_reason ?? null,
      terminalReason: msg.terminal_reason,
      apiCalls: ctx.turn.apiCalls,
      toolUses: ctx.turn.toolUses,
      turnTextLen: ctx.turn.uiEmittedText.length,
      resultTextLen: full.length,
    });
  }
  // 空响应兜底: isEmptyResponseTurn 已在上方(endTurn 之前)算好并解释。命中即"本轮发起过
  // API call 但 0 产出且 usage 增量全 0", 典型是模型网关短路返回空 SSE。此前这种 turn 会
  // 静默走 Done, 用户侧表现为"发了消息啥也没发生 / 会话假死"。这里显式 surface 成 error。
  if (isEmptyResponseTurn) {
    ctx.log.warn('SDK ◀ turn produced empty response (0 content, usage all zero)', {
      model: currentModel,
      apiCalls: ctx.turn.apiCalls,
      stopReason: msg.stop_reason,
      terminalReason: msg.terminal_reason,
    });
    // 终态收尾: 只发一条 isTerminal error 就结束本 turn, **不再**发 status Done / done。
    // 这个零用量异常无需 done 记账。若在 terminal error 之后再发 done, 同一 turn
    // 会被下游双重收尾:
    //   - session.ts: done / 终止型 error 都会清 currentTurnOrigin, 先来的 terminal error
    //     清掉后, 后随 done 拿不到 origin → IM/orca 按 origin 收口的卡片永不 finalize。
    //   - register.ts: done→onTurnEnd 与 terminal error→onTurnAbort 同 turn 都触发。
    // 这里复用尾部的 resetTurnState + onTurnEnd 清理后 return。
    queue.push({
      type: 'error',
      data: {
        message:
          '模型返回了空响应(本轮未产出任何文本、未调用工具,且用量为 0)。多见于模型网关在大上下文 / 高负载下短路返回空流,请重试。',
        isTerminal: true,
        reason: 'empty-response',
      },
      source: 'claude-code',
    });
    // 还原 aggregate 基线: 本轮空响应的 result.usage(0)不能成为下一轮 delta 的基线,
    // 否则下一真实 turn 会从 0 起算、把整段历史 token 全算到那一轮(Codex P2)。
    ctx.rt.lastResultUsageAggregate = aggregateBeforeThisResult;
    resetTurnState(ctx.turn);
    ctx.rt.mainRequestToolUseIds.clear();
    resetClaudeGenerationTiming(ctx.rt.generation);
    ctx.onTurnEnd?.();
    return;
  }
  // is_error result 才是 API-error envelope 的权威终态。此前 envelope 会立即推
  // terminal error,即使 SDK 随后自动重试成功也会让下游提前收口;现在成功 result
  // 会在 resetTurnState 中丢弃 pendingApiError,失败 result 则在这里一次性报错。
  // 无 API-error envelope 的 is_error 也继续走同一兜底,避免 renderer 的 state.error
  // 不置位 →
  // running→stopped 的通知链路把这次失败当正常完成(桌面/飞书通知"已完成")。
  // 这里补一条 terminal error, 然后**继续**走下方 status Done + done 收尾——与
  // API-error envelope 场景的既有失败序列(error → status Done → done)完全同构,
  // 也与 codex 的 failed 序列(error → done)一致。不能砍掉 done: main 的花费记账
  // (register.ts 'done' && source='claude-code' 分支, daily/session/per-message
  // 四个 sink)只从 done 的 result payload(usage / modelUsage / total_cost_usd)
  // 读数, is_error turn 有真实消耗, 砍 done 会丢整轮账(Codex review P2)。
  // empty-response 轮不同: usage 全 0 无账可丢, 保持其"只发 error"的收尾不变。
  // interruptRequested(用户 stop / watchdog 主动 interrupt)也跳过: SDK 被 interrupt
  // 后 drain 出的 error_during_execution result 不是上游失败, 补 error 会把"用户点
  // 停止"误报成"执行失败"、并让 watchdog 场景双发 banner(见 TurnState 字段注释)。
  let modelAccessMessage: string | undefined;
  if (msg.is_error && !ctx.turn.interruptRequested) {
    const pendingApiError = ctx.turn.pendingApiError;
    const rawResult = typeof msg.result === 'string' ? msg.result.trim() : '';
    const resultSignals = extractNonSecretErrorSignals(rawResult);
    const errDetail = redactSensitiveText(rawResult);
    const errorStatus = resultSignals.errorStatus ?? pendingApiError?.errorStatus;
    const usageLimit = pendingApiError?.usageLimit === true || resultSignals.usageLimit;
    // 多个窗口同时被拒时取最晚的重置,早醒只会再撞一次限额。已过点也照带:
    // 下游按零延迟立即续跑,丢掉反而只能等手动恢复。但过点的只用一次——到点后
    // 仍被本地短路拒绝时不会有新事件,反复带同一个过期时刻会让下游无限立即重试。
    const rejectedResets = [...ctx.rt.rateLimitRejectedResetAtMs.values()];
    const usageReset = rejectedResets.length > 0
      ? { usageResetAt: Math.max(...rejectedResets) }
      : {};
    const nowMs = Date.now();
    for (const [windowKey, resetAtMs] of ctx.rt.rateLimitRejectedResetAtMs) {
      if (resetAtMs <= nowMs) ctx.rt.rateLimitRejectedResetAtMs.delete(windowKey);
    }
    const errorMessage = pendingApiError?.agentMeta
      ? pendingApiError.message
      : errDetail || pendingApiError?.message;
    const modelAccessDenied = pendingApiError?.modelAccessDenied === true
      || isModelAccessDenied(rawResult, errorStatus ?? undefined);
    // Keep the terminal/usage event order, but omit the SDK's misleading
    // authentication advice and the upstream model list from terminal events.
    const modelAccessError = modelAccessDenied ? {
      reason: 'user_model_access_denied',
      sdkError: 'user_model_access_denied',
      errorStatus: 403,
      message: 'The upstream account cannot access this model. Select another model or check its access with the provider.',
    } : {};
    modelAccessMessage = modelAccessError.message;
    // 上下文超限带稳定 reason key(判定在上方 endTurn 前已算好): renderer 靠它
    // 隐藏必败的 Retry(原样重发必然再撞同一个 4xx)并给出压缩 / 新开会话入口;
    // 文案匹配仅作历史持久化错误行的兜底(overload reason 同款分层)。
    const classifiedReason = isContextOverflowTurn
      ? { reason: CONTEXT_OVERFLOW_REASON }
      : isCindyGatewayProxyTokenInvalidError({
            providerId: ctx.getProviderId?.() ?? null,
            message: [errorMessage, errDetail, pendingApiError?.message].filter(Boolean).join('\n'),
          })
        ? { reason: GATEWAY_PROXY_TOKEN_INVALID_REASON }
        : {};
    queue.push({
      type: 'error',
      data: pendingApiError
        ? {
            message: errorMessage,
            sdkError: pendingApiError.sdkError,
            isTerminal: true,
            ...classifiedReason,
            ...(errorStatus !== undefined ? { errorStatus } : {}),
            ...(usageLimit ? { usageLimit: true } : {}),
            ...usageReset,
            ...(pendingApiError.retryAttempt !== undefined
              ? { retryAttempt: pendingApiError.retryAttempt }
              : {}),
            ...(pendingApiError.maxRetries !== undefined
              ? { maxRetries: pendingApiError.maxRetries }
              : {}),
            ...modelAccessError,
          }
        : errDetail
        ? {
            message: errDetail,
            isTerminal: true,
            ...classifiedReason,
            ...(errorStatus !== undefined ? { errorStatus } : {}),
            ...(usageLimit ? { usageLimit: true } : {}),
            ...usageReset,
            ...modelAccessError,
          }
        // reason 是稳定 key, renderer 按它走 i18n(规则 18); message 仅作非
        // renderer 消费方(IM/orca)的兜底文案。
        : { message: '任务执行失败(模型未返回错误详情)。', isTerminal: true, reason: 'turn-failed' },
      source: 'claude-code',
      // ResultMessage terminates the whole query. A child API envelope can
      // explain its failure, but must not turn this terminal event into a child
      // event or attach the child's transcript anchor to the root error.
      ...(pendingApiError?.agentMeta && !pendingApiError.agentMeta.parentUuid
        ? { agentMeta: pendingApiError.agentMeta }
        : {}),
    });
  }
  // turn end status: isRunning=false + status='Done'; 数值全部走 endSnapshot
  queue.push({
    type: 'status',
    data: {
      status: 'Done',
      ...attachLiveGeneration(endSnapshot, {
        tokenSpeed: liveGeneration.tokenSpeed.snapshot(),
        outputTokens: liveTurnOutput,
        durationMs: liveGeneration.outputDurationMs,
        openStartedAt: null,
        reliable: liveGeneration.reliable,
      }),
      isRunning: false,
    },
    source: 'claude-code',
  });
  // silentStop 标记随 done 透传给 host: main 的自动续跑守卫据此决策(补发「继续」或
  // surface 耗尽提示)。data 为 unknown 形状、既有消费方(记账 / IM / orca)均按需
  // typeof 读字段, 加字段零影响; 不命中时 done 与现状逐字节一致。
  const safeResult =
    typeof msg.result === 'string'
      ? {
          ...msg,
          result: msg.is_error
            ? modelAccessMessage ?? redactSensitiveText(msg.result)
            : stripInternalWebCitations(msg.result),
        }
      : msg;
  const resultWithUsageSegments = {
    ...safeResult,
    requestUsage: ctx.tracker.getRequestMetering(),
    usageSegments: turnUsageSegments,
    usageSegmentsComplete,
    modelUsageCumulativeStartsAtZero: ctx.modelUsageCumulativeStartsAtZero?.() === true,
  };
  const resultWithAssistantMessageId = ctx.turn.lastAssistantRequestId
    ? { ...resultWithUsageSegments, assistant_message_id: ctx.turn.lastAssistantRequestId }
    : resultWithUsageSegments;
  queue.push({
    type: 'done',
    data:
      isSilentStopTurn
        ? { ...resultWithAssistantMessageId, silentStop: true }
        : resultWithAssistantMessageId,
    source: 'claude-code',
  });
  // reset turn 累积 (tracker 内部已经在 endTurn 里 reset 了 currentTurn,这里只清非 usage 状态)
  resetTurnState(ctx.turn);
  ctx.rt.activeUsageSegmentByParent.clear();
  ctx.rt.mainRequestToolUseIds.clear();
  resetClaudeGenerationTiming(ctx.rt.generation);
  // turn 结束钩子 — agent 用来清 turnInFlight 标记 (rewind preview/commit 前置守卫读它)
  ctx.onTurnEnd?.();
}