Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { nativeToolMediaFields, type NativeToolMedia } from '@cindy/maker-shared/tool-process-media';
/**
* Codex app-server v2 Notification → maker-core 语义 AgentEvent 翻译器。
*
* **完全重写** (路线 A): 输入从 SDK ThreadEvent 换成 app-server v2 Notification 系列;
* 输出 AgentEvent shape 与 claude-code/translator.ts **保持完全一致**, renderer 零改动。
*
* 协议真值 (只读):
* - codex-rs/app-server-protocol/src/protocol/v2.rs ThreadItem 枚举 (line 6082)
* #[serde(tag = "type", rename_all = "camelCase")] → 字段是 camelCase, 变体 tag 是 camelCase
* (e.g. "agentMessage" 不是 "agent_message")
* - 与上一版 SDK ThreadEvent 的差异 (重要):
* 1. Reasoning 不再是单个 text, 而是 summary: string[] + content: string[]
* 2. CommandExecution 加了 cwd / commandActions / processId / durationMs
* (cwd / commandActions 透传进 tool_use input; processId / durationMs 暂不用)
* 3. **没有 todo_list item** — Codex v2 协议级删除, 用 Plan { id, text } 兜底
* 4. WebSearch 多了 action: WebSearchAction (Search/OpenPage/FindInPage)
*
* 不在本文件做的事 (与上一版一致, 由 index.ts 处理):
* - thread/started → sessionId emit (index.ts 持 sdkSessionId 闭包)
* - thread/tokenUsage/updated → ingest usage (index.ts 持 tracker)
* - turn/completed → status + done event (index.ts 持 tracker snapshot)
* - turn-start status 文案 / userName → index.ts 在 send() 入口 push
*/
import {
extractNonSecretErrorSignals,
redactSensitiveText,
} from '@cindy/maker-shared/error-redaction';
import {
stableInternalWebCitationBoundary,
stableStandaloneModelStopTokenBoundary,
stripInternalWebCitations,
} from '@cindy/maker-shared/internal-citation';
import { UsageTokenSpeedMeter } from '../shared/token-speed.js';
import type { AgentEvent, AgentTaskStatus, AgentTaskUpdateEventData, GeneratedImageEventData } from '../../types/events.js';
import { normalizeAccountRateLimitSnapshot } from '../../types/account-rate-limits.js';
import type { AsyncQueue } from '../shared/async-queue.js';
import { stripTerminalControlSequences } from '../shared/terminal-output.js';
import { parseReconnectAttemptMessage } from '../shared/network-error.js';
import {
UPSTREAM_OVERLOAD_REASON,
formatOverloadRetryMessage,
parseOverloadError,
} from '../shared/overload-error.js';
import {
CONTEXT_OVERFLOW_REASON,
isContextOverflowErrorMessage,
} from '../shared/context-overflow-error.js';
import { isRemoteCompactEncryptedContentError } from '../shared/remote-compact-encrypted-error.js';
import { commandExecutionDisplayInput, type CommandExecutionDisplayInput } from './command-display.js';
import { annotateSandboxInitFailure } from './sandbox-init-failure.js';
import { codexErrorInfoTag } from './app-server/protocol.js';
import {
formatTerminalRateLimitRetryMessage,
TERMINAL_RATE_LIMIT_RETRY_REASON,
} from './terminal-rate-limit-retry.js';
import type {
ItemCompletedNotification,
ItemStartedNotification,
ItemUpdatedNotification,
AgentMessageDeltaNotification,
TurnPlanUpdatedNotification,
ErrorNotification,
ReasoningSummaryTextDeltaNotification,
ReasoningSummaryPartAddedNotification,
ReasoningTextDeltaNotification,
AccountRateLimitsUpdatedNotification,
} from './app-server/protocol.js';
// ── 共享 runtime 状态 ────────────────────────────────────────────────────────
//
// 跨多个 Notification 维持的累积态。语义和上一版一致,
// 但因为 reasoning text 现在是数组 join 出来的, reasoningTextLen 跟踪 join 后总长。
export interface CodexRuntimeState {
/** Text since the last completed tool belongs to the current sampling request. */
samplingSegments: Map<string, { threadId: string; turnId: string; attempt: number; itemIds: Set<string> }>;
/** item.id → reasoning 第一次 emit 'start' 的时间 (Date.now ms)。 */
reasoningStartedAt: Map<string, number>;
/** item.id → reasoning 已 emit 文本字符长度 (上次 join 后总长)。 */
reasoningTextLen: Map<string, number>;
/** item.id → agentMessage 已 emit 文本字符长度(citation 归一化后的空间,见 handleAgentMessage)。 */
itemTextLen: Map<string, number>;
/** Live tok/s from accepted usage and its paired generation time. */
tokenSpeed: UsageTokenSpeedMeter;
/** Current model-active interval start; null while tools/approvals own the turn. */
generationStartedAt: number | null;
/** Tool/approval boundaries currently owning the turn. Generation resumes after all finish. */
generationPendingToolIds: Set<string>;
/** Sum of model-active intervals for the current turn, including TTFT and thinking. */
generationDurationMs: number;
/** Model time sampled with the latest accepted output usage. */
generationOutputDurationMs: number;
/** Native-turn output for speed, independent of the billing ledger lifecycle. */
generationOutputTokens: number;
generationTurnId: string | null;
/** False when a tool boundary is incomplete/out of order; unreliable TPS is omitted. */
generationTimingReliable: boolean;
/** Event-loop heartbeat while the model owns the turn; detects suspend/blocking gaps. */
generationHeartbeatAt: number | null;
generationHeartbeatTimer: ReturnType<typeof setInterval> | null;
/** item.id → 已接受且可安全追加到 UI 的原始全文。 */
itemRawText: Map<string, string>;
/** item.id → 专用 agentMessage delta 已对齐到的原始全文游标(可由快照补齐漏帧)。 */
itemDeltaText: Map<string, string>;
/** item.id → item/started 或 item/updated 最新原始全文快照。 */
itemSnapshotText: Map<string, string>;
itemMessagePhase: Map<string, 'commentary' | 'final_answer'>;
/** 已经 emit 过 tool_use 的 item.id (避免 started + 第一次 updated 重复)。 */
emittedToolUse: Set<string>;
/** 尚未 emit 的 Web Search 候选输入,供跨 started/updated/completed 快照补全。 */
pendingWebSearchInput: Map<string, WebSearchInput>;
/** 已 emit 的 Web Search 输入,用于判断 completed 是否带来权威参数更新。 */
emittedWebSearchInput: Map<string, WebSearchInput>;
/**
* Auth retry-loop dedupe key (`<threadId>|<turnId>`)。daemon 撞 401 时
* willRetry=true 通知会按 retry 频率 (~每秒) 持续发, 不 dedupe 会让
* 下游 (makerChatStore case 'error' 走 refreshApiKeyFromServer / 结构化
* error log / 频繁 banner surface) 全跟着触发风暴。turnStarted 时清,
* 让下一个 turn 重新 emit 第一条 auth error。
*/
lastAuthErrorKey: string | null;
/**
* 网络类 retry-loop 透出状态 (`<threadId>|<turnId>` → 已见次数)。daemon 撞
* 502/连接失败等网络错误时 willRetry=true 默认被吞(瞬时抖动不该打扰用户),
* 但网络长时间不通时 daemon 卡在 retry-loop、turn 无限转圈,用户毫无感知。
* 同 turn 第 2 次网络类 willRetry 错误时透出**一条**非终止提示(之后同 turn
* 不再发,防风暴;恢复后 renderer recoverableError 机制随正常事件自动清)。
* turnStarted 时与 lastAuthErrorKey 一起清。
*/
networkRetryNotice: { key: string; count: number; emitted: boolean } | null;
}
export function newCodexRuntimeState(): CodexRuntimeState {
return {
samplingSegments: new Map(),
reasoningStartedAt: new Map(),
reasoningTextLen: new Map(),
itemTextLen: new Map(),
tokenSpeed: new UsageTokenSpeedMeter(),
generationStartedAt: null,
generationPendingToolIds: new Set(),
generationDurationMs: 0,
generationOutputDurationMs: 0,
generationOutputTokens: 0,
generationTurnId: null,
generationTimingReliable: true,
generationHeartbeatAt: null,
generationHeartbeatTimer: null,
itemRawText: new Map(),
itemDeltaText: new Map(),
itemSnapshotText: new Map(),
itemMessagePhase: new Map(),
emittedToolUse: new Set(),
pendingWebSearchInput: new Map(),
emittedWebSearchInput: new Map(),
lastAuthErrorKey: null,
networkRetryNotice: null,
};
}
const CODEX_GENERATION_HEARTBEAT_MS = 5_000;
const CODEX_GENERATION_SUSPEND_GAP_MS = 30_000;
function stopCodexGenerationHeartbeat(rt: CodexRuntimeState): void {
if (rt.generationHeartbeatTimer !== null) clearInterval(rt.generationHeartbeatTimer);
rt.generationHeartbeatTimer = null;
rt.generationHeartbeatAt = null;
}
function sampleCodexGenerationHeartbeat(rt: CodexRuntimeState, now = Date.now()): void {
const previous = rt.generationHeartbeatAt;
if (
previous !== null &&
now - previous > CODEX_GENERATION_HEARTBEAT_MS + CODEX_GENERATION_SUSPEND_GAP_MS
) {
rt.generationTimingReliable = false;
rt.tokenSpeed.invalidate();
}
rt.generationHeartbeatAt = now;
}
function startCodexGenerationHeartbeat(rt: CodexRuntimeState): void {
stopCodexGenerationHeartbeat(rt);
rt.generationHeartbeatAt = Date.now();
const timer = setInterval(() => {
sampleCodexGenerationHeartbeat(rt);
}, CODEX_GENERATION_HEARTBEAT_MS);
timer.unref?.();
rt.generationHeartbeatTimer = timer;
}
/** Reset per-turn model-generation timing; turn wall-clock is tracked separately by the host. */
export function resetCodexGenerationTiming(rt: CodexRuntimeState, preserveSpeed = false): void {
stopCodexGenerationHeartbeat(rt);
if (preserveSpeed) rt.tokenSpeed.startSegment();
else rt.tokenSpeed.reset();
rt.generationStartedAt = null;
rt.generationPendingToolIds.clear();
rt.generationDurationMs = 0;
rt.generationOutputDurationMs = 0;
rt.generationOutputTokens = 0;
rt.generationTurnId = null;
rt.generationTimingReliable = true;
}
function closeCodexGenerationInterval(rt: CodexRuntimeState, endedAt: number): void {
const startedAt = rt.generationStartedAt;
rt.generationStartedAt = null;
sampleCodexGenerationHeartbeat(rt);
stopCodexGenerationHeartbeat(rt);
if (startedAt === null) return;
if (endedAt < startedAt) {
rt.generationTimingReliable = false;
rt.tokenSpeed.invalidate();
return;
}
rt.generationDurationMs += endedAt - startedAt;
}
export function beginCodexGenerationTurn(
rt: CodexRuntimeState,
turnId: string,
startedAt = Date.now(),
): void {
if (rt.generationTurnId !== turnId) {
resetCodexGenerationTiming(rt, true);
rt.generationTurnId = turnId;
}
if (rt.generationStartedAt === null && rt.generationPendingToolIds.size === 0) {
rt.generationStartedAt = startedAt;
startCodexGenerationHeartbeat(rt);
}
}
export function finalizeCodexGenerationTurn(
rt: CodexRuntimeState,
turnId: string,
completedAt = Date.now(),
): void {
if (rt.generationTurnId !== turnId) return;
if (rt.generationPendingToolIds.size > 0) {
rt.generationTimingReliable = false;
rt.generationStartedAt = null;
stopCodexGenerationHeartbeat(rt);
return;
}
closeCodexGenerationInterval(rt, completedAt);
}
export function codexGenerationDurationMs(rt: CodexRuntimeState): number | undefined {
return rt.generationTimingReliable && rt.generationDurationMs > 0
? rt.generationDurationMs
: undefined;
}
export function pauseCodexGeneration(
rt: CodexRuntimeState,
turnId: string,
pauseId: string,
pausedAt = Date.now(),
): void {
if (rt.generationTurnId !== turnId) {
beginCodexGenerationTurn(rt, turnId, pausedAt);
// Keep the interaction pair consistent, but omit TPS because the missing
// turn-start boundary means TTFT/thinking before this pause is unknown.
rt.generationTimingReliable = false;
}
if (!pauseId) {
rt.generationTimingReliable = false;
return;
}
if (rt.generationPendingToolIds.has(pauseId)) return;
if (rt.generationPendingToolIds.size === 0) closeCodexGenerationInterval(rt, pausedAt);
rt.generationPendingToolIds.add(pauseId);
}
export function resumeCodexGeneration(
rt: CodexRuntimeState,
turnId: string,
pauseId: string,
resumedAt = Date.now(),
): void {
if (rt.generationTurnId !== turnId || !rt.generationPendingToolIds.delete(pauseId)) {
rt.generationTimingReliable = false;
return;
}
if (rt.generationPendingToolIds.size === 0) rt.generationStartedAt = resumedAt;
if (rt.generationPendingToolIds.size === 0) startCodexGenerationHeartbeat(rt);
}
const CODEX_GENERATION_PAUSE_ITEM_TYPES: ReadonlySet<string> = new Set([
'commandExecution',
'mcpToolCall',
'dynamicToolCall',
'collabAgentToolCall',
'webSearch',
'imageGeneration',
'imageView',
'contextCompaction',
]);
// App-server v2 reports fileChange only after the patch is complete. With no
// matching start event it is an output notification, not a pairable timing
// boundary; handleFileChange still publishes its tool events below.
// contextCompaction may likewise arrive completion-only. Keeping it in the
// paired pause set makes that shape fail closed, while still excluding the
// compaction interval if a future app-server supplies both boundaries.
function noteCodexGenerationBoundary(
rt: CodexRuntimeState,
phase: ItemPhase,
item: { id?: unknown; type?: unknown },
notification: { turnId?: unknown },
): void {
const turnId = notification.turnId;
if (typeof turnId !== 'string') return;
// App-server timestamps may originate on a remote SSH host whose wall clock
// differs from the desktop. Keep every generation boundary in the local
// receipt-time domain so interval subtraction never mixes remote clocks.
// A separate event-loop heartbeat fails closed on suspend-sized local jumps.
const receivedAt = Date.now();
if (rt.generationTurnId !== turnId) {
beginCodexGenerationTurn(rt, turnId, receivedAt);
// The authoritative local turn-start boundary was not observed. Starting
// at this item receipt would drop TTFT/thinking, so keep the state usable
// for pause pairing but fail closed for TPS.
rt.generationTimingReliable = false;
}
if (
typeof item.type !== 'string' ||
!CODEX_GENERATION_PAUSE_ITEM_TYPES.has(item.type)
) {
return;
}
if (typeof item.id !== 'string' || item.id.length === 0) {
rt.generationTimingReliable = false;
return;
}
const pauseId = `item:${item.id}`;
if (phase === 'started') {
// The model finished emitting this call; its execution is not generation time.
pauseCodexGeneration(rt, turnId, pauseId, receivedAt);
return;
}
if (phase !== 'completed') return;
resumeCodexGeneration(rt, turnId, pauseId, receivedAt);
}
// ── 上下文 ────────────────────────────────────────────────────────────────────
interface TranslatorLog {
info(msg: string, ctx?: Record<string, unknown>): void;
warn(msg: string, ctx?: Record<string, unknown>): void;
debug(msg: string, ctx?: Record<string, unknown>): void;
}
export interface CodexTranslateContext {
rt: CodexRuntimeState;
log: TranslatorLog;
/** A failed sample cannot remain the adapter's successful final-text fallback. */
onSamplingAttemptFailed?: () => void;
/**
* Maker Memory flush 观察器 — codex contextCompaction completed 时调,
* controller 重置 fired 阈值 (compact 后 context 又有空间, 可重新触发)。
* 缺省 = 不回调 (makerMemoryEnabled 关时 agent 不注入)。
*/
onCompactBoundary?: () => void;
/**
* 服务过载错误的重投接管钩子 (由 agent 层注入)。
*
* 返回进度 = agent 层已排好退避重投, 这条错误必须透成**非终止**状态并带上
* 进度; 否则 UI 会先收口成失败再重投, 用户看到一次假失败闪烁。返回 null =
* 没有重投预算或不满足重投条件, 按原路径当终止错误报。
*
* 分工原因: 能否重投只有 agent 层知道 (要看本 turn 有没有产出、预算还剩多少、
* 会话是否已关), 而错误脱敏与 error 事件构造在 translator。缺省 = 不接管。
*/
tryTakeOverOverload?: () => { attempt: number; maxAttempts: number } | null;
/**
* daemon 已耗尽内部 retry budget 的终态 429 接管钩子。agent 层负责严格分类、
* turn 归属、产出守卫与预算;translator 只编码独立 reason / 进度契约。
*/
tryTakeOverTerminalRateLimit?: () => {
attempt: number;
maxAttempts: number;
} | null;
}
// ── 主入口: 三个 item.* notification 的统一分发 ────────────────────────────────
type ItemPhase = 'started' | 'updated' | 'completed';
// Host-executed tool results prove the preceding response was accepted. Built-in
// search/image items can complete inside the still-open SSE response and do not.
const SAMPLING_ACCEPTED_TOOL_TYPES = new Set([
'commandExecution', 'mcpToolCall', 'dynamicToolCall', 'collabAgentToolCall', 'fileChange',
]);
function isSamplingStreamFailure(error: ClassifiedCodexError): boolean {
return error.errorInfoTag === 'responseStreamDisconnected' ||
error.errorInfoTag === 'responseTooManyFailedAttempts' ||
/stream disconnected|retrying sampling request|stream ended before.*response\.completed/i.test(error.message);
}
function samplingSegment(rt: CodexRuntimeState, threadId: string, turnId: string) {
const key = JSON.stringify([threadId, turnId]);
let segment = rt.samplingSegments.get(key);
if (!segment) {
segment = { threadId, turnId, attempt: 1, itemIds: new Set<string>() };
rt.samplingSegments.set(key, segment);
}
return segment;
}
/** Exact identities, never prose similarity or final_answer-only filtering (#6351). */
function failSamplingSegment(rt: CodexRuntimeState, threadId: string, turnId: string) {
const segment = rt.samplingSegments.get(JSON.stringify([threadId, turnId]));
if (!segment) return undefined;
const agentMessageIds = [...segment.itemIds];
segment.itemIds.clear();
const attempt = segment.attempt++;
return agentMessageIds.length ? { threadId, turnId, attempt, agentMessageIds } : undefined;
}
/** A stopped retry remains auditable; a successful turn never marks its last reply failed. */
export function finishCodexSamplingTurn(
rt: CodexRuntimeState, threadId: string, turnId: string, status: string,
error?: Parameters<typeof classifyCodexError>[0],
) {
const key = JSON.stringify([threadId, turnId]);
const segment = rt.samplingSegments.get(key);
const failure = status !== 'completed' && segment &&
(segment.attempt > 1 || (error && isSamplingStreamFailure(classifyCodexError(error))))
? failSamplingSegment(rt, threadId, turnId) : undefined;
rt.samplingSegments.delete(key);
return failure;
}
export function translateItemNotification(
phase: ItemPhase,
notification:
| ItemStartedNotification['params']
| ItemUpdatedNotification['params']
| ItemCompletedNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const item = notification.item;
if (!item || typeof item !== 'object') {
ctx.log.warn('item notification missing item field', { phase });
return;
}
const itemType = (item as { type?: unknown }).type;
if (typeof itemType !== 'string') {
ctx.log.warn('item missing type field', { phase, itemKeys: Object.keys(item) });
return;
}
if (itemType === 'agentMessage') {
samplingSegment(ctx.rt, notification.threadId, notification.turnId).itemIds.add(item.id);
} else if (phase === 'completed' &&
SAMPLING_ACCEPTED_TOOL_TYPES.has(itemType)) {
// Tool results prove earlier generation was accepted. Its commentary and
// side effects must not be invalidated by a later sampling request failing.
ctx.rt.samplingSegments.delete(JSON.stringify([notification.threadId, notification.turnId]));
}
noteCodexGenerationBoundary(
ctx.rt,
phase,
item as { id?: unknown; type?: unknown },
notification as { turnId?: unknown },
);
switch (itemType) {
case 'agentMessage':
handleAgentMessage(phase, item as unknown as AgentMessageItem, queue, ctx);
return;
case 'reasoning':
handleReasoning(phase, item as unknown as ReasoningItem, queue, ctx);
return;
case 'commandExecution':
handleCommandExecution(phase, item as unknown as CommandExecutionItem, queue, ctx);
return;
case 'mcpToolCall':
handleMcpToolCall(phase, item as unknown as McpToolCallItem, queue, ctx);
return;
case 'dynamicToolCall':
handleDynamicToolCall(phase, item as unknown as DynamicToolCallItem, queue, ctx);
return;
case 'collabAgentToolCall':
handleCollabAgentToolCall(phase, item as unknown as CollabAgentToolCallItem, queue, ctx);
return;
case 'webSearch':
handleWebSearch(phase, item as unknown as WebSearchItem, queue, ctx);
return;
case 'fileChange':
handleFileChange(phase, item as unknown as FileChangeItem, queue, ctx);
return;
case 'plan':
handlePlan(phase, item as unknown as PlanItem, queue, ctx);
return;
case 'imageView':
handleImageView(phase, item as unknown as ImageViewItem, queue);
return;
case 'imageGeneration':
handleImageGeneration(phase, item as unknown as ImageGenerationItem, queue, notification);
return;
case 'contextCompaction':
handleContextCompaction(phase, item as unknown as ContextCompactionItem, queue, ctx);
return;
case 'subAgentActivity':
handleSubAgentActivity(phase, item as unknown as SubAgentActivityItem, queue, ctx);
return;
// 以下 v2 item 类型故意不消费 (无 UI 对应概念, 不是 bug):
// userMessage: SDK echo 用户输入, claude-code translator 也只挑 tool_result 包装的
// hookPrompt: codex 用户配置 hook 注入的 prompt, UI 不展示
// enteredReviewMode / exitedReviewMode: codex review 子模式开关, maker 端无 review 概念
case 'userMessage':
case 'hookPrompt':
case 'enteredReviewMode':
case 'exitedReviewMode':
return;
default:
ctx.log.warn('unhandled item type', { phase, itemType });
return;
}
}
/**
* auth 缺失 (401/Unauthorized/Missing bearer) 判定 — daemon 怎么 retry 也不可能
* 自愈, 必须用户介入。收紧 pattern: 避开非 HTTP-auth 错误误伤 (eg. 工具执行报错
* "Unauthorized file system access" 含 Unauthorized 字面但不是 401)。要求带
* \b401\b 边界, 或 Missing bearer 精确短语 (OpenAI 401 message 标准措辞)。
*
* 从 translateErrorNotification 抽出成 export — codex/index.ts 的 retry 升级
* 逻辑要排除这一类 (auth 缺失走自己「同步登录态」的等待式 UX, 不应被升级成
* 终态 backend-unreachable)。
*/
export function isAuthMissingErrorMessage(message: string, errorStatus?: number): boolean {
return errorStatus === 401 || /\b401\b|Missing bearer/i.test(message);
}
/**
* auth 相关错误 (缺失 OR 无效) 的更宽判定 — translator 会把
* authentication_error / authentication_failed / invalid_api_key /
* api key not valid 这些 marker 同样推断成 errorStatus=401 走 auth UX
* (translateErrorNotification 的 hasAuthErrorMarker)。retry-loop 升级判定
* 必须排除同一集合, 否则这些真 auth 错误会被升级成「后端不可达」终态,
* 抢走 auth 修复路径并误导排查方向 (review: PR #715 五轮审核 P1)。
*
* 与 isAuthMissingErrorMessage 的分工: Missing 版只认「没给凭证」
* (401 / Missing bearer), 用于触发「同步登录态」等待式 UX; Related 版
* 额外认「凭证无效」类 marker, 只用于「不要按网络不可达处理」的排除判断。
*/
export function isAuthRelatedErrorMessage(message: string, errorStatus?: number): boolean {
if (isAuthMissingErrorMessage(message, errorStatus)) return true;
return /\bauthentication_(?:error|failed)\b|\binvalid[\s_-]*api[\s_-]*key\b|\bapi key not valid\b/i
.test(message);
}
export interface ClassifiedCodexError {
message: string;
errorStatus?: number;
errorInfoTag?: string;
usageLimit: boolean;
isCapacityError: boolean;
reason?: string;
data: Record<string, unknown> & { message: string };
}
/**
* ErrorNotification 与 turn/completed.turn.error 共用的结构化分类。
* 默认只消费 Codex wire schema 的 message + codexErrorInfo;stderr 不参与判定。
* 唯一例外:远端 compact 密文 400 会把 `additionalDetails` 拼进 classify 文本,
* 因为用户形态经常是 message=`Error running remote compact task`、code 在 details 里。
*/
export function classifyCodexError(error: {
message?: string;
additionalDetails?: unknown;
codexErrorInfo?: import('./app-server/protocol.js').CodexErrorInfo | null;
} | null | undefined): ClassifiedCodexError {
const rawMessage = error?.message ?? 'codex error';
const hasMissingBearer = /\bMissing bearer\b/i.test(rawMessage);
const hasAuthErrorMarker =
/\bauthentication_(?:error|failed)\b|\binvalid[\s_-]*api[\s_-]*key\b|\bapi key not valid\b/i.test(
rawMessage,
);
const message = redactSensitiveText(rawMessage);
const signals = extractNonSecretErrorSignals(rawMessage);
const errorStatus =
signals.errorStatus ?? (hasMissingBearer || hasAuthErrorMarker ? 401 : undefined);
const errorInfoTag = codexErrorInfoTag(error?.codexErrorInfo);
const isCapacityError =
parseOverloadError(message, signals.errorStatus, errorInfoTag)?.kind === 'capacity';
const additionalDetails =
typeof error?.additionalDetails === 'string' ? error.additionalDetails : '';
const compactClassifyText = additionalDetails ? `${message}\n${additionalDetails}` : message;
const reason = isCapacityError
? UPSTREAM_OVERLOAD_REASON
: errorInfoTag === 'contextWindowExceeded' ||
isContextOverflowErrorMessage(message) ||
isRemoteCompactEncryptedContentError(compactClassifyText)
? CONTEXT_OVERFLOW_REASON
: undefined;
return {
message,
...(errorStatus !== undefined ? { errorStatus } : {}),
...(errorInfoTag !== undefined ? { errorInfoTag } : {}),
usageLimit: signals.usageLimit,
isCapacityError,
...(reason ? { reason } : {}),
data: {
message,
...(errorStatus !== undefined ? { errorStatus } : {}),
...(signals.usageLimit ? { usageLimit: true } : {}),
...(errorInfoTag !== undefined ? { codexErrorInfo: errorInfoTag } : {}),
...(reason ? { reason } : {}),
},
};
}
/** error notification (顶层非 item.*) → AgentEvent error。 */
export function translateErrorNotification(
params: ErrorNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const classified = classifyCodexError(params.error);
const safeMessage = classified.message;
const errorStatus = classified.errorStatus;
const isCapacityError = classified.isCapacityError;
const safeErrorData = classified.data;
const segment = ctx.rt.samplingSegments.get(JSON.stringify([params.threadId, params.turnId]));
const streamFailed = isSamplingStreamFailure(classified) || (!params.willRetry && (segment?.attempt ?? 1) > 1);
const assistantAttemptFailure = streamFailed
? failSamplingSegment(ctx.rt, params.threadId, params.turnId) : undefined;
if (assistantAttemptFailure) {
Object.assign(safeErrorData, { assistantAttemptFailure });
ctx.onSamplingAttemptFailed?.();
}
// willRetry=true 的暂时错误 (transient API blip / 5xx blip), server 自己会重试 — 默认
// 不 emit error event 给 UI,否则会把瞬时错误暴露成用户可见失败。**但** auth 缺失
// (401/Unauthorized/Missing bearer) 是 daemon 怎么 retry 也不可能自愈的 —— 必须
// 用户介入 (同步 auth 把 auth.json 推到远端 + 重启 daemon) 才能恢复。这种情况下
// 不 emit 用户就看不到任何错误,turn 在 daemon retry-loop 里永远 hang。让 error
// 透出来并标记 isTerminal=false → renderer 端 ErrorBanner 的 401 识别会触发 →
// 显示「同步登录态」button;main 端 active-turn keepalive 继续保持,等待 daemon
// retry 或用户修复登录态后的后续事件。
const isAuthMissing = isAuthMissingErrorMessage(safeMessage, errorStatus);
if (params.willRetry && !isAuthMissing) {
ctx.log.warn('codex error (will retry)', { message: safeMessage, threadId: params.threadId, turnId: params.turnId });
// Codex 自带明确的有限重连进度时,每档都透出,让 UI 从 1/5 持续更新到 5/5。
// 这是非终止状态:turn 仍由 app-server 继续,不结束也不另起一次不安全的请求重放。
if (assistantAttemptFailure || parseReconnectAttemptMessage(safeMessage)) {
queue.push({
type: 'error',
data: { ...safeErrorData, isTerminal: false, willRetry: true },
source: 'codex',
});
return;
}
// 持续重试的错误 = daemon 卡在 retry-loop 里 turn 无限转圈。同 turn 第 2 次时
// 透出**一条**非终止提示 (isTerminal:false, renderer 走 recoverableError →
// "正在自动重试…" banner, 恢复后随正常事件自动清; 不结束 turn、不落 error 行)。
// 第 1 次不透出: 单次抖动 daemon 一次重试就过, 提示只会闪一下徒增噪音。
//
// 不限定 networkish pattern (issue #677): 远端后端不可达的典型文案
// ("unexpected status 403 Forbidden" / "failed to connect to websocket:
// Network unreachable") 不命中 networkish, 但同样是「daemon 在空转」的信号,
// 用户必须看得到。终局收口由 codex/index.ts 的 TurnRetryTracker 升级负责。
const key = `${params.threadId ?? ''}|${params.turnId ?? ''}`;
const notice = ctx.rt.networkRetryNotice;
const count = notice?.key === key ? notice.count + 1 : 1;
const emitted = notice?.key === key ? notice.emitted : false;
ctx.rt.networkRetryNotice = { key, count, emitted };
if (count >= 2 && !emitted) {
ctx.rt.networkRetryNotice = { key, count, emitted: true };
queue.push({
type: 'error',
data: { ...safeErrorData, isTerminal: false, willRetry: true },
source: 'codex',
});
}
return;
}
// willRetry=true 且 auth 缺失: daemon 401 retry-loop 会按重试频率 (~每秒) 持续发,
// 不 dedupe 会让下游 (makerChatStore case 'error' 走 refreshApiKeyFromServer +
// 结构化 error log + banner surface) 全跟着触发风暴。按 threadId+turnId 做 per-turn
// dedupe: 同 turn 内同样的 auth retry 只 emit 第一条; turnStarted 时 rt.lastAuthErrorKey
// reset, 下一个 turn 可以再 emit 一次。willRetry=false 不 dedupe (本来就是一次性升级)。
if (params.willRetry && isAuthMissing) {
const key = `${params.threadId ?? ''}|${params.turnId ?? ''}`;
if (ctx.rt.lastAuthErrorKey === key) {
ctx.log.debug('codex auth retry-loop dropped (already surfaced this turn)', { message: safeMessage, threadId: params.threadId, turnId: params.turnId });
return;
}
ctx.rt.lastAuthErrorKey = key;
}
// 服务过载 (`Selected model is at capacity`): OpenAI 侧不重试就把 turn 判死,
// 由 agent 层接管退避重投。接管成功时透成非终止状态并带进度后缀, renderer
// 显示"模型繁忙, 正在重试 (N/M)"; 预算耗尽或条件不满足 (本 turn 已有产出)
// 时 tryTakeOverOverload 返回 null, 落回下面的终止错误路径。
// 过载分类在函数入口已完成,避免同一判据在两处漂移。
const overloadReason = isCapacityError ? { reason: UPSTREAM_OVERLOAD_REASON } : {};
// 上下文超限同样带稳定 reason key(#1429): 原样重试必然再撞同一个 4xx, renderer 靠
// 它隐藏 Retry 并给出压缩 / 新开会话入口。结构化 contextWindowExceeded 优先,
// 文案匹配仅兼容旧版 app-server;与 capacity 互斥时 overload 优先 —— 它还驱动
// 退避重投接管,语义更具体。
const contextOverflowReason =
!isCapacityError && classified.reason === CONTEXT_OVERFLOW_REASON
? { reason: CONTEXT_OVERFLOW_REASON }
: {};
if (!params.willRetry && isCapacityError) {
const progress = ctx.tryTakeOverOverload?.();
if (progress) {
queue.push({
type: 'error',
data: {
...safeErrorData,
...overloadReason,
message: formatOverloadRetryMessage(safeMessage, progress.attempt, progress.maxAttempts),
isTerminal: false,
willRetry: true,
},
source: 'codex',
});
return;
}
}
if (!params.willRetry && !isCapacityError) {
const progress = ctx.tryTakeOverTerminalRateLimit?.();
if (progress) {
queue.push({
type: 'error',
data: {
...safeErrorData,
reason: TERMINAL_RATE_LIMIT_RETRY_REASON,
message: formatTerminalRateLimitRetryMessage(
safeMessage,
progress.attempt,
progress.maxAttempts,
),
isTerminal: false,
willRetry: true,
},
source: 'codex',
});
return;
}
}
ctx.log.warn('codex turn error', { message: safeMessage, willRetry: params.willRetry, isAuthMissing, threadId: params.threadId, turnId: params.turnId });
queue.push({
type: 'error',
data: {
...safeErrorData,
...overloadReason,
...contextOverflowReason,
isTerminal: !params.willRetry,
willRetry: params.willRetry,
},
source: 'codex',
});
if (!params.willRetry) {
ctx.rt.samplingSegments.delete(JSON.stringify([params.threadId, params.turnId]));
}
}
export function translatePlanUpdatedNotification(
params: TurnPlanUpdatedNotification['params'],
queue: AsyncQueue<AgentEvent>,
): void {
queue.push({
type: 'tool_use',
data: {
toolUseId: `plan:${params.turnId}`,
toolName: 'update_plan',
runtimeActivity: 'snapshot',
input: {
...(params.explanation ? { explanation: params.explanation } : {}),
plan: params.plan,
},
},
source: 'codex',
});
}
interface RolloutUpdatePlanFunctionCall {
type: 'function_call';
name: 'update_plan';
call_id?: string;
arguments?: string;
internal_chat_message_metadata_passthrough?: {
turn_id?: string;
};
}
function asRecord(value: unknown): Record<string, unknown> | null {
return value && typeof value === 'object' && !Array.isArray(value)
? value as Record<string, unknown>
: null;
}
function parseRolloutUpdatePlanFunctionCall(entry: unknown): RolloutUpdatePlanFunctionCall | null {
const record = asRecord(entry);
if (!record) return null;
const payload = asRecord(record.payload);
const item = payload?.type === 'function_call' ? payload : record;
if (item.type !== 'function_call' || item.name !== 'update_plan') return null;
return item as unknown as RolloutUpdatePlanFunctionCall;
}
/**
* Codex app-server currently writes `update_plan` to rollout as a response
* function_call even when no `turn/plan/updated` notification is emitted.
* This narrow fallback translates only that exact rollout item shape.
*/
export function translateRolloutUpdatePlanFunctionCall(
entry: unknown,
queue: AsyncQueue<AgentEvent>,
fallbackTurnId?: string,
opts?: { requireTurnId?: boolean },
): { callId: string | null; turnId: string | null } | null {
const parsed = extractRolloutUpdatePlanFunctionCallEvent(entry, fallbackTurnId, opts);
if (!parsed) return null;
queue.push(parsed.event);
return { callId: parsed.callId, turnId: parsed.turnId };
}
export function extractRolloutUpdatePlanFunctionCallEvent(
entry: unknown,
fallbackTurnId?: string,
opts?: { requireTurnId?: boolean },
): { event: AgentEvent; callId: string | null; turnId: string | null } | null {
const item = parseRolloutUpdatePlanFunctionCall(entry);
if (!item) return null;
const turnId = item.internal_chat_message_metadata_passthrough?.turn_id ?? fallbackTurnId ?? null;
if (opts?.requireTurnId && !turnId) return null;
let input: Record<string, unknown>;
try {
const parsed = item.arguments ? JSON.parse(item.arguments) as unknown : {};
input = asRecord(parsed) ?? { text: String(item.arguments ?? '') };
} catch {
input = { text: String(item.arguments ?? '') };
}
return {
event: {
type: 'tool_use',
data: {
toolUseId: turnId ? `plan:${turnId}` : `plan-call:${item.call_id ?? 'unknown'}`,
toolName: 'update_plan',
runtimeActivity: 'snapshot',
input,
},
source: 'codex',
},
callId: item.call_id ?? null,
turnId,
};
}
// ── ThreadItem 局部类型 (字段最小集, 对齐 v2.rs) ────────────────────────────
interface AgentMessageItem {
type: 'agentMessage';
id: string;
text: string;
phase?: 'commentary' | 'final_answer';
}
interface ReasoningItem {
type: 'reasoning';
id: string;
/** v2: summary 是数组 (每条独立段落), 对外 join 成单一文本流。 */
summary?: string[];
/** v2: content 是数组 (内部 reasoning, 通常 OpenAI 不返还原文)。 */
content?: string[];
}
type CommandExecutionStatus = 'inProgress' | 'completed' | 'failed' | 'declined';
interface CommandExecutionItem {
type: 'commandExecution';
id: string;
command: string;
cwd?: string;
status: CommandExecutionStatus;
/**
* codex 侧 parse_command 的确定性解析产物(read / listFiles / search /
* unknown,管道命令拆多项)。原样透传进 tool_use input,供 maker-shared
* `describeToolUse` 生成人话意图(issue #450);本层不消费不加工。
*/
commandActions?: unknown[];
aggregatedOutput?: string | null;
exitCode?: number | null;
durationMs?: number | null;
}
function commandExecutionInput(item: CommandExecutionItem): CommandExecutionDisplayInput {
const input = commandExecutionDisplayInput(item.command, item.cwd);
// 引用透传,零拷贝零加工 —— 热路径上不增加任何处理成本(规则 10)。
if (Array.isArray(item.commandActions) && item.commandActions.length > 0) {
input.commandActions = item.commandActions;
}
return input;
}
type McpToolCallStatus = 'inProgress' | 'completed' | 'failed';
interface McpToolCallResult {
content?: unknown[];
structuredContent?: unknown;
_meta?: unknown;
}
interface McpToolCallItem {
type: 'mcpToolCall';
id: string;
server: string;
tool: string;
status: McpToolCallStatus;
arguments?: unknown;
result?: McpToolCallResult | null;
error?: { message?: string; [k: string]: unknown } | null;
}
type WebSearchAction =
| { type: 'search'; query?: string | null; queries?: string[] | null }
| { type: 'open_page' | 'openPage'; url?: string | null }
| { type: 'find_in_page' | 'findInPage'; url?: string | null; pattern?: string | null }
| { type: string; [k: string]: unknown };
interface WebSearchItem {
type: 'webSearch';
id: string;
query: string;
action?: WebSearchAction | null;
}
interface WebSearchInput {
query: string;
action?: WebSearchAction;
}
type PatchApplyStatus = 'inProgress' | 'completed' | 'failed' | 'declined';
type PatchChangeKind = { type: 'add' } | { type: 'delete' } | { type: 'update'; [k: string]: unknown } | { type: string; [k: string]: unknown };
interface FileUpdateChange {
path: string;
kind: PatchChangeKind;
diff: string;
}
interface FileChangeItem {
type: 'fileChange';
id: string;
changes: FileUpdateChange[];
status: PatchApplyStatus;
}
// v2.rs ThreadItem::Plan { id, text } — EXPERIMENTAL "proposed plan item content"。
// 单条 step 文本, codex 不一定按 started/updated/completed 全发。started/updated 先把
// 当前计划推给 UI,completed 再补 full/result 让历史详情有最终文本。
interface PlanItem {
type: 'plan';
id: string;
text: string;
}
// v2.rs ThreadItem::DynamicToolCall — codex 自己 router 的"动态注册工具"
// namespace + tool 拼出 toolName; arguments 透传; completed 给 contentItems 拼 fullText。
type DynamicToolCallStatus = 'inProgress' | 'completed' | 'failed';
type DynamicToolCallContentItem =
| { type: 'inputText'; text: string }
| { type: 'inputImage'; imageUrl: string }
| { type: string; [k: string]: unknown };
interface DynamicToolCallItem {
type: 'dynamicToolCall';
id: string;
namespace?: string | null;
tool: string;
arguments?: unknown;
status: DynamicToolCallStatus;
contentItems?: DynamicToolCallContentItem[] | null;
success?: boolean | null;
durationMs?: number | null;
}
// v2.rs ThreadItem::CollabAgentToolCall — codex 多 agent 协作 (spawn/sendInput/resume/wait/close)
// tool enum 用 toolName 后缀; receiverThreadIds + agentsStates 进 input/result 透传给 UI 排查用。
type CollabAgentTool = 'spawnAgent' | 'sendInput' | 'resumeAgent' | 'wait' | 'closeAgent';
type CollabAgentToolCallStatus = 'inProgress' | 'completed' | 'failed';
interface CollabAgentToolCallItem {
type: 'collabAgentToolCall';
id: string;
tool: CollabAgentTool;
status: CollabAgentToolCallStatus;
senderThreadId: string;
receiverThreadIds: string[];
prompt?: string | null;
model?: string | null;
reasoningEffort?: string | null;
agentsStates: Record<string, unknown>;
}
// v2.rs ThreadItem::ImageView { id, path } — 模型读图 (本地绝对路径)。
interface ImageViewItem {
type: 'imageView';
id: string;
path: string;
}
// result may contain bare Base64 even when savedPath is also present (Codex 0.159.2).
interface ImageGenerationItem {
type: 'imageGeneration';
id: string;
status: string;
revisedPrompt?: string | null;
result: string;
savedPath?: string | null;
}
// v2.rs ThreadItem::ContextCompaction { id } — codex auto-compact 边界 (协议没给 token / duration)。
interface ContextCompactionItem {
type: 'contextCompaction';
id: string;
}
// ── agentMessage → text {isFinal} ───────────────────────────────────────────
// 专用 item/agentMessage/delta 出增量(isFinal=false),item.started / item.updated 的全文
// 快照作为兼容兜底并负责补齐漏帧,item.completed 出 final 全文校准。
/**
* Codex 正文里的内部文件引用标记 `:codex-file-citation{path="..." ...}`——对用户
* 是不可读的内部语法,归一化成行内代码的文件路径。没有 path 属性的畸形标记整个
* 剥掉,不把内部语法漏给用户。
*/
// 属性区 = 「非引号非花括号字符 或 双引号串」的序列:双引号串内允许出现 { } ,
// 且支持反斜杠转义(\" 表示文件名里的引号)——路径含花括号 / 引号都不会让标记
// 匹配失败而把内部语法漏给用户。
const CODEX_FILE_CITATION_RE = /:codex-file-citation\{((?:[^"{}]|"(?:[^"\\]|\\.)*")*)\}/g;
const CODEX_FILE_CITATION_OPEN = ':codex-file-citation{';
/**
* 路径包成 Markdown 行内代码:围栏取「比路径内最长反引号连跑多一个」的反引号数,
* 路径以反引号开头/结尾时按 CommonMark 规则两侧补空格——路径自身含反引号也不会
* 把 code span 撑破。
*/
function inlineCodePath(path: string): string {
const longestRun = path.match(/`+/g)?.reduce((max, run) => Math.max(max, run.length), 0) ?? 0;
const fence = '`'.repeat(longestRun + 1);
// 补空格垫的两种情形:路径以反引号开头/结尾(隔开围栏),或首尾都是空格且非全空格
// (CommonMark 渲染器对这种 code span 会各剥一个空格,不垫会把真实路径的首尾空白
// 剥掉指向别的文件;单侧空格渲染器不剥,不垫)。
const symmetricSpace = path.startsWith(' ') && path.endsWith(' ') && path.trim().length > 0;
const pad = path.startsWith('`') || path.endsWith('`') || symmetricSpace ? ' ' : '';
return `${fence}${pad}${path}${pad}${fence}`;
}
export function normalizeCodexFileCitations(text: string): string {
if (!text.includes(CODEX_FILE_CITATION_OPEN)) return text;
return text.replace(CODEX_FILE_CITATION_RE, (_all, attrs: string) => {
const path = extractCitationPath(attrs);
return path ? inlineCodePath(path) : '';
});
}
/**
* 属性区取 path 值并解码。
* - 属性名要求完整边界(串首或空白后的 `path=`):`display_path=` 这类「以 path 结尾」
* 的别名不当作 path,也不遮蔽其后真正的 path 属性(review 反馈)。
* - 只解 \" 与 \\ 两种转义——Windows 原生路径(C:\Users\...)里的反斜杠不是转义
* 前缀,全量 \\(.) 反转义会把路径毁成 C:Users...(review 反馈)。
* - UNC 前缀:开头**恰好两个**反斜杠视为原生 UNC 本体整体保留(\\server\share);
* 更长的开头连跑(如转义形态 \\\\server)与其余位置按转义对解码,转义 UNC 解出
* 恰好两个分隔符(review 反馈)。
* - 取出后不做 trim——文件名首尾空白是路径的一部分,悄悄改写会指向另一个文件。
*/
function extractCitationPath(attrs: string): string | undefined {
const raw = /(?:^|\s)path="((?:[^"\\]|\\.)*)"/.exec(attrs)?.[1];
if (raw === undefined) return undefined;
const nativeUnc = raw.startsWith('\\\\') && raw[2] !== '\\';
const head = nativeUnc ? '\\\\' : '';
const tail = (nativeUnc ? raw.slice(2) : raw).replace(/\\([\\"])/g, '$1');
return head + tail;
}
// 闭合扫描的两种「未找到」:UNFINISHED = 扫描到文本末尾仍未闭合(可能是尚未写完、
// 会被后续 update 补全的截断尾巴);POISONED = 属性区出现裸 `{`,正则永不匹配,该
// 标记已确定畸形且追加文本也不会改变这一判定。
const CITATION_UNFINISHED = -1;
const CITATION_POISONED = -2;
/**
* 属性区闭合 `}` 的位置(与 CODEX_FILE_CITATION_RE 同一口径:双引号串内的花括号
* 不算边界);找不到时区分 CITATION_UNFINISHED 与 CITATION_POISONED。
*/
function findCitationClose(text: string, attrsStart: number): number {
let inQuote = false;
for (let i = attrsStart; i < text.length; i += 1) {
const ch = text[i];
if (inQuote && ch === '\\') {
i += 1; // 引号串内的转义对(如 \")整体跳过,与正则同口径。
} else if (ch === '"') {
inQuote = !inQuote;
} else if (!inQuote && ch === '}') {
return i;
} else if (!inQuote && ch === '{') {
return CITATION_POISONED;
}
}
return CITATION_UNFINISHED;
}
/**
* 从左到右结构化扫描,返回第一个「扫描到文本末尾仍未闭合」的标记开头;没有 → -1。
* 完整标记整体跳过——路径引号串里出现的 OPEN 字面量属于已消费标记的内部,不会被
* 误认成新的开头(review 反馈:文件名本身含 `:codex-file-citation{` 时,按最后一个
* 裸字面量定位会带着错误的引号状态把完整标记判成未完成)。裸 `{` 的畸形标记(正则
* 永不匹配、追加文本也救不回来)原样透出:只跳过开头字面量继续扫,不吞它后面的正文。
*/
function findUnfinishedCitationOpen(text: string): number {
let from = 0;
for (;;) {
const open = text.indexOf(CODEX_FILE_CITATION_OPEN, from);
if (open === -1) return -1;
const close = findCitationClose(text, open + CODEX_FILE_CITATION_OPEN.length);
if (close === CITATION_UNFINISHED) return open;
from = close === CITATION_POISONED ? open + CODEX_FILE_CITATION_OPEN.length : close + 1;
}
}
/**
* 流式安全边界:全量文本尾部可能是一个尚未写完的 citation 标记(标记会被后续
* update 补全),归一化后的文本对这段尾巴不是 append-only。返回可安全发出的原文
* 前缀长度,未写完的尾巴按住等下一轮;completed 时全量补发,不丢内容。
*/
/**
* final 文本统一口径(流式 completed 与历史 rollout 导入共用):先剥「扫描到文本
* 末尾仍未闭合」的确定截断残尾(它之后没有正文可吞),再做 citation 归一化。
* 契约:只做 raw→final 的**单次**转换(两个调用点都满足)。无标记文本原样返回,
* 但展示形不承诺严格幂等——路径本身解码出完整标记字面量的极端文件名,二次处理
* 会把生成的 code span 内容再替换;去重指纹因此不复用展示形,走独立的不动点
* 规范形(见 localDb worker 的 canonicalizeCodexCitations)。
*/
export function finalizeCodexCitationText(text: string): string {
const fileOpenAt = findUnfinishedCitationOpen(text);
const fileStableEnd = fileOpenAt === -1 ? text.length : fileOpenAt;
const stableEnd = Math.min(fileStableEnd, stableInternalWebCitationBoundary(text));
return stripInternalWebCitations(normalizeCodexFileCitations(text.slice(0, stableEnd)));
}
export function stableCitationBoundary(text: string): number {
const stopTokenEnd = stableStandaloneModelStopTokenBoundary(text);
const open = findUnfinishedCitationOpen(text);
if (open !== -1) {
return Math.min(open, stableInternalWebCitationBoundary(text), stopTokenEnd);
}
const maxProbe = Math.min(text.length, CODEX_FILE_CITATION_OPEN.length - 1);
for (let k = maxProbe; k > 0; k -= 1) {
if (text.endsWith(CODEX_FILE_CITATION_OPEN.slice(0, k))) {
return Math.min(text.length - k, stableInternalWebCitationBoundary(text), stopTokenEnd);
}
}
return Math.min(stableInternalWebCitationBoundary(text), stopTokenEnd);
}
function emitAgentMessageProgress(
itemId: string,
rawText: string,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const previousRawText = ctx.rt.itemRawText.get(itemId) ?? '';
// AgentEvent.text 是只能追加的协议。快照和专用 delta 出现乱序或
// 分叉时不能把另一个版本的尾巴拼进已发正文;completed 的全文会做终态校准。
if (!rawText.startsWith(previousRawText)) return;
// itemTextLen 记录的是**归一化后已发出**的长度:citation 替换会改变文本长度,
// diff 必须在归一化空间里做,不能混用原文长度。
const prevLen = ctx.rt.itemTextLen.get(itemId) ?? 0;
const emitted = stripInternalWebCitations(
normalizeCodexFileCitations(rawText.slice(0, stableCitationBoundary(rawText))),
);
const delta = emitted.slice(prevLen);
ctx.rt.itemRawText.set(itemId, rawText);
ctx.rt.itemTextLen.set(itemId, emitted.length);
if (delta.length === 0) return;
queue.push({
type: 'text',
data: { text: delta, isFinal: false, agentMessageId: itemId,
...(ctx.rt.itemMessagePhase.has(itemId) ? { phase: ctx.rt.itemMessagePhase.get(itemId) } : {}),
},
source: 'codex',
});
}
function reconcileAgentMessageProgress(
itemId: string,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const deltaText = ctx.rt.itemDeltaText.get(itemId);
const snapshotText = ctx.rt.itemSnapshotText.get(itemId);
const currentText = ctx.rt.itemRawText.get(itemId) ?? '';
let candidate: string | undefined;
if (deltaText === undefined) {
candidate = snapshotText;
} else if (snapshotText === undefined) {
candidate = deltaText;
} else if (deltaText.startsWith(snapshotText)) {
candidate = deltaText;
} else if (snapshotText.startsWith(deltaText)) {
candidate = snapshotText;
} else if (deltaText.startsWith(currentText)) {
// 两个源分叉后锁定仍能延续已发前缀的专用 delta,不混拼快照尾巴。
candidate = deltaText;
} else if (snapshotText.startsWith(currentText)) {
// 快照先到时同理锁定快照流;delta 追平后会自动恢复共识。
candidate = snapshotText;
}
if (candidate !== undefined) emitAgentMessageProgress(itemId, candidate, queue, ctx);
}
/**
* Codex 专用正文 delta。专用流与 item/updated 快照共用同一份已发长度,二者同时
* 出现时不会重复;快照缺席时也能保持与 Claude Code / Pi 相同的实时正文契约。
*/
export function translateAgentMessageDelta(
params: AgentMessageDeltaNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (!params.delta) return;
samplingSegment(ctx.rt, params.threadId, params.turnId).itemIds.add(params.itemId);
const currentText = ctx.rt.itemRawText.get(params.itemId) ?? '';
const previousDeltaText = ctx.rt.itemDeltaText.get(params.itemId) ?? '';
let rawText: string;
if (currentText.startsWith(previousDeltaText) && currentText.length > previousDeltaText.length) {
// 快照已经比 dedicated delta 游标超前:新 chunk 可能是延迟重放的补齐段,
// 也可能是漏帧之后的真新文本。先消费与快照 gap 的重叠,再把剩余部分追加。
const snapshotGap = currentText.slice(previousDeltaText.length);
if (snapshotGap.startsWith(params.delta)) {
rawText = previousDeltaText + params.delta;
} else if (params.delta.startsWith(snapshotGap)) {
rawText = currentText + params.delta.slice(snapshotGap.length);
} else {
rawText = currentText + params.delta;
}
} else {
rawText = previousDeltaText + params.delta;
}
ctx.rt.itemDeltaText.set(params.itemId, rawText);
reconcileAgentMessageProgress(params.itemId, queue, ctx);
}
function handleAgentMessage(
phase: ItemPhase,
item: AgentMessageItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const rawText = item.text ?? '';
if (item.phase) ctx.rt.itemMessagePhase.set(item.id, item.phase);
if (phase === 'completed') {
ctx.rt.itemTextLen.delete(item.id);
ctx.rt.itemRawText.delete(item.id);
ctx.rt.itemDeltaText.delete(item.id);
ctx.rt.itemSnapshotText.delete(item.id);
ctx.rt.itemMessagePhase.delete(item.id);
// 既有契约:completed 只出 final 全文、不补 delta(desktop codexTranslator.test
// 钉死 3 事件形状)。boundary 按住的尾段与「completed 才首次出现的文本」同一待遇:
// 不进 delta 流,由 final 全文兜底(main 落库层 onAssistantTextEvent 的 isFinal
// 分支以更长 final 覆盖 delta 累积,不丢内容)。
// 输出被截断在标记中间(有明确的 open、永远等不到 close)时,把残尾剥掉——
// 内部语法不该漏给用户;只剥「扫描到文本末尾仍未闭合」的确定截断残尾(它之后
// 没有正文可吞),疑似前缀(不足完整 open 字面量)可能是真实正文,保留。
// finalizeCodexCitationText 是与历史导入共用的统一口径。
queue.push({
type: 'text',
data: {
text: finalizeCodexCitationText(rawText),
isFinal: true,
isFullText: true,
agentMessageId: item.id,
...(item.phase ? { phase: item.phase } : {}),
},
source: 'codex',
});
return;
}
ctx.rt.itemSnapshotText.set(item.id, rawText);
reconcileAgentMessageProgress(item.id, queue, ctx);
}
// ── reasoning → thinking {stage} ─────────────────────────────────────────────
// v2 reasoning 是 { summary: string[], content: string[] } 两路文本数组。
// 对外当成单一文本流: 优先用 summary (OpenAI 实际填的字段), content 备选。
// summary.length=0 时整个 reasoning 不显示 (与 displayReasoning='off' 一致)。
function joinReasoningText(item: ReasoningItem): string {
if (item.summary && item.summary.length > 0) return item.summary.join('\n\n');
if (item.content && item.content.length > 0) return item.content.join('\n\n');
return '';
}
// 不变式 (用户 A 决定): reasoning 全程无文本时, **不创建** thinking block —
// 不 emit start / delta / final 任何一项, renderer 也就不显示空卡片。
// reasoningStartedAt.has(item.id) 即等价于 "已 emit start", 用作"是否已建块"标志。
function handleReasoning(
phase: ItemPhase,
item: ReasoningItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const text = joinReasoningText(item);
if (phase === 'started') {
if (text.length === 0) return; // 文本为空, 暂不建块, 等 delta / completed 真有内容再说
ensureReasoningStarted(item.id, queue, ctx);
ctx.rt.reasoningTextLen.set(item.id, text.length);
queue.push({
type: 'thinking',
data: { stage: 'delta', blockId: item.id, text },
source: 'codex',
});
return;
}
if (phase === 'updated') {
const prevLen = ctx.rt.reasoningTextLen.get(item.id) ?? 0;
const delta = text.slice(prevLen);
if (delta.length === 0) return;
ensureReasoningStarted(item.id, queue, ctx);
ctx.rt.reasoningTextLen.set(item.id, text.length);
queue.push({
type: 'thinking',
data: { stage: 'delta', blockId: item.id, text: delta },
source: 'codex',
});
return;
}
// completed: 无内容且无前置 emit → 整段静默丢弃 (用户 A: 不显示空 thinking 卡片)
const alreadyStarted = ctx.rt.reasoningStartedAt.has(item.id);
if (text.length === 0 && !alreadyStarted) return;
if (!alreadyStarted) ensureReasoningStarted(item.id, queue, ctx); // 文本只在 completed 才出 (罕见)
const startedAt = ctx.rt.reasoningStartedAt.get(item.id) ?? Date.now();
const durationMs = Date.now() - startedAt;
ctx.rt.reasoningStartedAt.delete(item.id);
ctx.rt.reasoningTextLen.delete(item.id);
queue.push({
type: 'thinking',
data: { stage: 'final', blockId: item.id, text, durationMs },
source: 'codex',
});
}
// ── reasoning delta 流 → thinking {stage:'delta'} ─────────────────────────────
// 三个 v2 notification 拆开消费 (item/started 不一定先到, delta 内部兜底 lazy-init
// 跟 claude-code translator handleStreamEvent thinking_delta 一样)。
//
// 累积语义 (server 端 v2.rs::ReasoningSummaryTextDeltaNotification 注释 + event_mapping.rs):
// summaryPartAdded(idx=N) → summary 数组里开第 N 段
// summaryTextDelta(idx=N, txt) → 追加 txt 到第 N 段
// item/completed → emit thinking final 全文 (renderer 用全文 overwrite 校准)
//
// 我们这里的事件流:
// summaryPartAdded(idx=0) → 不发 (起始段, 不需要分隔符)
// summaryPartAdded(idx>0) → push thinking delta '\n\n' (段间分隔)
// summaryTextDelta(_, delta) → push thinking delta delta
// textDelta(_, delta) → 同 summaryTextDelta (raw 内容流)
//
// renderer (makerChatStore thinking case) 的行为:
// delta = append, final = overwrite — 即便 delta 顺序乱了, final 全文也会校准。
/** delta 流的统一兜底: rt.reasoningStartedAt 没记过就 lazy-init + 发 thinking start。 */
function ensureReasoningStarted(
itemId: string,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (ctx.rt.reasoningStartedAt.has(itemId)) return;
const startedAt = Date.now();
ctx.rt.reasoningStartedAt.set(itemId, startedAt);
ctx.rt.reasoningTextLen.set(itemId, 0);
queue.push({
type: 'thinking',
data: { stage: 'start', blockId: itemId, startedAt },
source: 'codex',
});
}
export function translateReasoningSummaryTextDelta(
params: ReasoningSummaryTextDeltaNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (!params.delta) return;
ensureReasoningStarted(params.itemId, queue, ctx);
const prevLen = ctx.rt.reasoningTextLen.get(params.itemId) ?? 0;
ctx.rt.reasoningTextLen.set(params.itemId, prevLen + params.delta.length);
queue.push({
type: 'thinking',
data: { stage: 'delta', blockId: params.itemId, text: params.delta },
source: 'codex',
});
}
export function translateReasoningSummaryPartAdded(
params: ReasoningSummaryPartAddedNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
// idx=0: 起始段, 无前置内容也无分隔符 — no-op (不预建空块, 等首条 textDelta 才 lazy-emit start)
if (params.summaryIndex === 0) return;
// idx>0 段间分隔符: 仅在已有内容 (start 已 emit) 时才插, 否则跳过 (避免空块)
if (!ctx.rt.reasoningStartedAt.has(params.itemId)) return;
const prevLen = ctx.rt.reasoningTextLen.get(params.itemId) ?? 0;
ctx.rt.reasoningTextLen.set(params.itemId, prevLen + 2);
queue.push({
type: 'thinking',
data: { stage: 'delta', blockId: params.itemId, text: '\n\n' },
source: 'codex',
});
}
export function translateReasoningTextDelta(
params: ReasoningTextDeltaNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (!params.delta) return;
ensureReasoningStarted(params.itemId, queue, ctx);
const prevLen = ctx.rt.reasoningTextLen.get(params.itemId) ?? 0;
ctx.rt.reasoningTextLen.set(params.itemId, prevLen + params.delta.length);
queue.push({
type: 'thinking',
data: { stage: 'delta', blockId: params.itemId, text: params.delta },
source: 'codex',
});
}
// ── commandExecution → tool_use + tool_result_full + tool_result ─────────────
function handleCommandExecution(
phase: ItemPhase,
item: CommandExecutionItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const input = commandExecutionInput(item);
if (phase === 'started') {
if (ctx.rt.emittedToolUse.has(item.id)) return;
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName: 'exec',
input,
},
source: 'codex',
});
return;
}
if (phase === 'updated') {
if (!ctx.rt.emittedToolUse.has(item.id)) {
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName: 'exec',
input,
},
source: 'codex',
});
}
return;
}
// completed
const execEmitted = ctx.rt.emittedToolUse.has(item.id);
ctx.rt.emittedToolUse.delete(item.id);
if (!execEmitted) {
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName: 'exec',
input,
},
source: 'codex',
});
}
const isError = item.status === 'failed' || item.status === 'declined';
queue.push({
type: 'tool_result_full',
data: {
toolUseId: item.id,
// #3793:bwrap 沙箱初始化失败(命令从未执行)时追加宿主归因标注,
// 模型不再盲目重试,用户在工具卡里能看到原因。健康与普通失败路径原样。
fullText: annotateSandboxInitFailure(
stripTerminalControlSequences(item.aggregatedOutput ?? ''),
isError,
item.command,
),
isError,
},
source: 'codex',
});
const exitLabel = item.exitCode != null ? `Exit ${item.exitCode}` : item.status;
queue.push({
type: 'tool_result',
data: { summary: exitLabel, toolUseIds: [item.id] },
source: 'codex',
});
}
// ── mcpToolCall → tool_use + tool_result_full + tool_result ──────────────────
function handleMcpToolCall(
phase: ItemPhase,
item: McpToolCallItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const toolName = `mcp:${item.server}:${item.tool}`;
if (phase === 'started') {
if (ctx.rt.emittedToolUse.has(item.id)) return;
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName,
input: (item.arguments as Record<string, unknown>) ?? {},
},
source: 'codex',
});
return;
}
if (phase === 'updated') {
if (!ctx.rt.emittedToolUse.has(item.id)) {
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: { toolUseId: item.id, toolName, input: (item.arguments as Record<string, unknown>) ?? {} },
source: 'codex',
});
}
return;
}
// completed
ctx.rt.emittedToolUse.delete(item.id);
const isError = !!item.error;
let fullText = '';
if (item.error?.message) {
fullText = item.error.message;
} else if (item.result) {
fullText = mcpToolCallResultToFullText(item.result);
}
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText, isError, ...nativeToolMediaFields(item.result?.content) },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: { summary: isError ? 'failed' : item.status, toolUseIds: [item.id] },
source: 'codex',
});
}
function mcpToolCallResultToFullText(result: McpToolCallResult): string {
const textParts = mcpContentTextParts(result.content);
if (textParts.length > 0) return textParts.join('\n');
if (result.structuredContent !== undefined) {
try {
return JSON.stringify(result.structuredContent, null, 2);
} catch {
return String(result.structuredContent);
}
}
if (result.content !== undefined) {
try {
return JSON.stringify(result.content, null, 2);
} catch {
return String(result.content);
}
}
return '';
}
function mcpContentTextParts(content: unknown[] | undefined): string[] {
if (!Array.isArray(content)) return [];
const parts: string[] = [];
for (const block of content) {
if (typeof block === 'string') {
parts.push(block);
continue;
}
if (!block || typeof block !== 'object') continue;
const b = block as { type?: unknown; text?: unknown };
if (b.type === 'text' && typeof b.text === 'string') {
parts.push(b.text);
}
}
return parts;
}
// ── webSearch → tool_use + tool_result_full + tool_result ────────────────────
// v2 的 legacy query 可能为空,真实动作优先在 action 中;归一成 query 供现有
// maker-shared / Desktop / Mobile 展示链路消费,同时保留 action 供展开详情核验。
function nonEmptyWebSearchText(value: unknown): string {
return typeof value === 'string' ? value.trim() : '';
}
function quoteWebSearchText(value: string): string {
return `'${value.replace(/['\\]/g, (char) => `\\${char}`)}'`;
}
function webSearchActionDetail(action: WebSearchAction | null | undefined): string {
if (!action) return '';
switch (action.type) {
case 'search': {
const query = nonEmptyWebSearchText(action.query);
if (query) return query;
const queries = Array.isArray(action.queries)
? action.queries.map(nonEmptyWebSearchText).filter(Boolean)
: [];
if (queries.length === 0) return '';
return queries.length > 1 ? `${queries[0]} ...` : queries[0];
}
case 'open_page':
case 'openPage':
return nonEmptyWebSearchText(action.url);
case 'find_in_page':
case 'findInPage': {
const url = nonEmptyWebSearchText(action.url);
const pattern = nonEmptyWebSearchText(action.pattern);
if (pattern && url) return `${quoteWebSearchText(pattern)} in ${url}`;
if (pattern) return quoteWebSearchText(pattern);
return url;
}
default:
return '';
}
}
function webSearchInput(
item: WebSearchItem,
actionDetail = webSearchActionDetail(item.action),
): WebSearchInput {
const query = actionDetail || nonEmptyWebSearchText(item.query);
return {
query,
...(item.action ? { action: item.action } : {}),
};
}
function rememberWebSearchInput(
item: WebSearchItem,
input: WebSearchInput,
actionDetail: string,
ctx: CodexTranslateContext,
): WebSearchInput {
const pending = ctx.rt.pendingWebSearchInput.get(item.id);
// 真实 action 优先级最高;在它到达前,保留最新的非空 legacy query 作为兜底。
if (input.query && (actionDetail || !webSearchActionDetail(pending?.action))) {
ctx.rt.pendingWebSearchInput.set(item.id, input);
return input;
}
return pending ?? input;
}
function emitWebSearchToolUse(
item: WebSearchItem,
input: WebSearchInput,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
ctx.rt.emittedToolUse.add(item.id);
ctx.rt.emittedWebSearchInput.set(item.id, input);
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName: 'web_search',
input,
},
source: 'codex',
});
}
function handleWebSearch(
phase: ItemPhase,
item: WebSearchItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const actionDetail = webSearchActionDetail(item.action);
const currentInput = webSearchInput(item, actionDetail);
const input = rememberWebSearchInput(item, currentInput, actionDetail, ctx);
if (phase === 'started') {
if (ctx.rt.emittedToolUse.has(item.id)) return;
// started 的 legacy query 可能为空或只是占位符,updated 才补真实 action;
// 延迟到 action 到达或 completed,避免旧参数先落库后无法无损更新。
if (!actionDetail) return;
emitWebSearchToolUse(item, input, queue, ctx);
return;
}
if (phase === 'updated') {
if (ctx.rt.emittedToolUse.has(item.id) || !actionDetail) return;
emitWebSearchToolUse(item, input, queue, ctx);
return;
}
// completed
const toolUseEmitted = ctx.rt.emittedToolUse.has(item.id);
const emittedInput = ctx.rt.emittedWebSearchInput.get(item.id);
ctx.rt.emittedToolUse.delete(item.id);
ctx.rt.pendingWebSearchInput.delete(item.id);
ctx.rt.emittedWebSearchInput.delete(item.id);
// 防御缺失 started/updated 的历史或异常事件序列,保持 tool_use → result 顺序。
if (!toolUseEmitted) {
// completed 仍无可展示参数时整条忽略,避免补发空白 tool_use 和孤立 result。
if (!input.query) return;
emitWebSearchToolUse(item, input, queue, ctx);
ctx.rt.emittedToolUse.delete(item.id);
ctx.rt.emittedWebSearchInput.delete(item.id);
} else if (input.query && JSON.stringify(input) !== JSON.stringify(emittedInput)) {
// started/updated 用于实时展示;completed 可能补充权威 URL、pattern 或修正后的
// query。沿用同一 toolUseId 补发,由 Desktop 持久层与 renderer 原位更新。
emitWebSearchToolUse(item, input, queue, ctx);
ctx.rt.emittedToolUse.delete(item.id);
ctx.rt.emittedWebSearchInput.delete(item.id);
}
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText: '', isError: false },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: { summary: 'done', toolUseIds: [item.id] },
source: 'codex',
});
}
// ── fileChange → tool_use + tool_result_full + tool_result ───────────────────
// v2 不流式 patch (吞掉了 outputDelta), 只在 completed 时一次性出。
function handleFileChange(
phase: ItemPhase,
item: FileChangeItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (phase !== 'completed') return;
void ctx;
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName: 'file_change',
input: { changes: item.changes },
},
source: 'codex',
});
const isError = item.status === 'failed' || item.status === 'declined';
const summary = item.changes.map((c) => `${c.kind.type} ${c.path}`).join('\n');
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText: summary, isError },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: {
summary: `${item.changes.length} file(s) ${item.status}`,
toolUseIds: [item.id],
},
source: 'codex',
});
}
// ── plan → tool_use(update_plan) + tool_result_full + tool_result ────────────
// v2 Plan item EXPERIMENTAL: { id, text } 单条提案文本。started/updated 也 emit
// update_plan,让 renderer 的计划卡片能实时出现;completed 补 tool_result 作为历史详情。
function handlePlan(
phase: ItemPhase,
item: PlanItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
void ctx;
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName: 'update_plan',
input: { text: item.text },
},
source: 'codex',
});
if (phase !== 'completed') return;
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText: item.text, isError: false },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: { summary: 'plan updated', toolUseIds: [item.id] },
source: 'codex',
});
}
// ── dynamicToolCall → tool_use + tool_result_full + tool_result ──────────────
// 行为对齐 mcpToolCall: started 出 tool_use, updated 兜底, completed 拼 fullText。
// 区别: 工具名 dynamic:${namespace}:${tool}; contentItems 拼 fullText 时, inputImage 退化成
// "<image: url>" 占位 (image 主路径已经走 image event, 这里只为详情面板补全文本可读)。
function dynamicContentItemsToText(items: DynamicToolCallContentItem[] | null | undefined): string {
if (!items || items.length === 0) return '';
const parts: string[] = [];
for (const it of items) {
if (it.type === 'inputText' && typeof (it as { text?: unknown }).text === 'string') {
parts.push((it as { text: string }).text);
} else if (it.type === 'inputImage' && typeof (it as { imageUrl?: unknown }).imageUrl === 'string') {
parts.push(`<image: ${(it as { imageUrl: string }).imageUrl}>`);
}
}
return parts.join('\n');
}
function handleDynamicToolCall(
phase: ItemPhase,
item: DynamicToolCallItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const ns = item.namespace ?? '';
const toolName = ns ? `dynamic:${ns}:${item.tool}` : `dynamic:${item.tool}`;
if (phase === 'started') {
if (ctx.rt.emittedToolUse.has(item.id)) return;
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: {
toolUseId: item.id,
toolName,
input: (item.arguments as Record<string, unknown>) ?? {},
},
source: 'codex',
});
return;
}
if (phase === 'updated') {
if (!ctx.rt.emittedToolUse.has(item.id)) {
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: { toolUseId: item.id, toolName, input: (item.arguments as Record<string, unknown>) ?? {} },
source: 'codex',
});
}
return;
}
// completed
ctx.rt.emittedToolUse.delete(item.id);
const isError = item.status === 'failed' || item.success === false;
const fullText = dynamicContentItemsToText(item.contentItems);
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText, isError, ...nativeToolMediaFields(item.contentItems) },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: { summary: isError ? 'failed' : item.status, toolUseIds: [item.id] },
source: 'codex',
});
}
// ── collabAgentToolCall → tool_use + tool_result_full + tool_result ──────────
// codex 多 agent 协作 (spawn/sendInput/resume/wait/closeAgent)。
// toolName=collab:${tool}; input 透传 prompt / receivers / model / effort 让 UI 详情面板看到调度参数;
// completed 时把 agentsStates 压成线程状态摘要,避免子任务卡片展开后直接展示原始 JSON。
function formatCodexAgentStateLabel(state: unknown): string | undefined {
if (typeof state === 'string') {
const trimmed = state.trim();
return trimmed || undefined;
}
if (!state || typeof state !== 'object' || Array.isArray(state)) return undefined;
const record = state as Record<string, unknown>;
for (const key of ['status', 'state', 'phase']) {
const value = record[key];
if (typeof value === 'string' && value.trim()) return value.trim();
}
for (const key of ['error', 'message', 'summary']) {
const value = record[key];
if (typeof value !== 'string' || !value.trim()) continue;
const oneLine = value.replace(/\s+/g, ' ').trim();
return oneLine.length > 180 ? `${oneLine.slice(0, 179)}…` : oneLine;
}
return undefined;
}
function formatCodexAgentStatesSummary(states: Record<string, unknown> | null | undefined): string | undefined {
const entries = Object.entries(states ?? {});
if (entries.length === 0) return undefined;
return entries
.map(([threadId, state]) => {
const label = formatCodexAgentStateLabel(state);
return label ? `${threadId}: ${label}` : threadId;
})
.join('\n');
}
function handleCollabAgentToolCall(
phase: ItemPhase,
item: CollabAgentToolCallItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
const toolName = `collab:${item.tool}`;
const isSpawn = item.tool.toLowerCase().startsWith('spawn');
const hasSpawnReceiver = !isSpawn || item.receiverThreadIds.length > 0;
const input: Record<string, unknown> = {
senderThreadId: item.senderThreadId,
receiverThreadIds: item.receiverThreadIds,
};
if (item.prompt) input.prompt = item.prompt;
if (item.model) input.model = item.model;
if (item.reasoningEffort) input.reasoningEffort = item.reasoningEffort;
if (phase === 'started') {
// Codex can emit a provisional spawn item before validation has created a
// child thread. If validation then fails (for example an unknown model),
// 0.145 emits no matching terminal collab item. Publishing this empty-
// receiver placeholder would therefore leave an inline card and durable
// Subagent run stuck on running forever. Wait for a receiver-bearing
// updated/completed snapshot, which is the first proof that a child exists.
if (!hasSpawnReceiver) return;
if (ctx.rt.emittedToolUse.has(item.id)) return;
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: { toolUseId: item.id, toolName, input },
source: 'codex',
});
queue.push({
type: 'agent_task_update',
data: toCodexTaskUpdate(item, 'running'),
source: 'codex',
});
return;
}
if (phase === 'updated') {
if (!hasSpawnReceiver) return;
if (!ctx.rt.emittedToolUse.has(item.id)) {
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: { toolUseId: item.id, toolName, input },
source: 'codex',
});
}
queue.push({
type: 'agent_task_update',
data: toCodexTaskUpdate(item, 'running'),
source: 'codex',
});
return;
}
// completed
// Some app-server versions omit item/started and send only the terminal
// collab snapshot. Reconstruct the tool-use boundary before the result so
// the late background item still has a renderer/persistence anchor.
const hadToolUse = ctx.rt.emittedToolUse.has(item.id);
if (!hadToolUse) {
ctx.rt.emittedToolUse.add(item.id);
queue.push({
type: 'tool_use',
data: { toolUseId: item.id, toolName, input },
source: 'codex',
});
}
ctx.rt.emittedToolUse.delete(item.id);
const isError = item.status === 'failed';
const fullText = formatCodexAgentStatesSummary(item.agentsStates) ?? (isError ? 'failed' : item.status);
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText, isError },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: { summary: isError ? 'failed' : item.status, toolUseIds: [item.id] },
source: 'codex',
});
queue.push({
type: 'agent_task_update',
data: toCodexTaskUpdate(
item,
isError ? 'failed' : 'completed',
fullText,
!hadToolUse,
),
source: 'codex',
});
}
// ── subAgentActivity → tool_use + agent_task_update(spawn 可见性) ───────────
// codex 0.145 multi-agent v2:spawn_agent 不发 collabAgentToolCall,只发瞬时
// SubAgentActivityItem(kind=started/interacted/interrupted,无完成事件——子代理
// 的等待与收口由后续 wait_agent 的 collab 卡承载)。不处理它,子代理启动在 UI
// 完全不可见(实测:探索型任务 spawn 3 个子代理,等待窗口内聊天流零卡片)。
// started 渲染成子代理卡并置 running:卡片本体与 Claude 子代理共用
// AgentTaskCard,后续 tokens / 工具调用数 / 耗时与终态由 codex/index.ts 消费子
// 线程 notification 后按同一 taskId 增量更新(见 descendantNotification)。
// interacted 是 followup/send 调用的伴生事件、interrupted 由 interrupt 调用自身
// 承载,均显式静默不再落 unhandled 告警。协议只给 id/kind/agentThreadId/
// agentPath,没有 prompt/model/effort(上游 main 已改为 spawn 直发
// collabAgentToolCall 富卡,vendored codex 升级后自动走上面
// handleCollabAgentToolCall,本函数届时按 id 去重自然让位)。
interface SubAgentActivityItem {
type: 'subAgentActivity';
id: string;
kind: string;
agentThreadId?: string;
agentPath?: string;
/** Newer Codex builds may include the selected child model on the activity. */
model?: string;
reasoningEffort?: string | null;
}
/**
* 从 spawn 类 item 抽出「子线程 id → 子代理卡 taskId」的登记信息,双轨通用:
* - V2(0.145):`subAgentActivity` kind=started,带 agentThreadId
* - V1 与上游 main:`collabAgentToolCall` 的 spawn 工具,派发目标在 receiverThreadIds
*
* 放在 translator 是因为 item 形状知识归它所有;codex/index.ts 只消费结果,不再
* 自己 narrow item 字段。返回 null = 不是 spawn(调用方直接忽略)。
*/
export function readCodexSubagentSpawnRegistration(item: unknown): {
taskId: string;
childThreadIds: string[];
agentPath?: string;
model?: string;
/**
* spawn **本身**收口为失败(V1 `collabAgentToolCall.status === 'failed'`)。
* translator 此时已推过 failed 帧,聚合器据此不得再用快照(仍是 running)盖回去。
* V2 的 subAgentActivity 没有 status 字段,恒为 undefined。
*/
failed?: boolean;
} | null {
if (!item || typeof item !== 'object') return null;
const record = item as Record<string, unknown>;
const taskId = typeof record.id === 'string' && record.id ? record.id : null;
if (!taskId) return null;
if (record.type === 'subAgentActivity') {
if (record.kind !== 'started') return null;
const childThreadId = typeof record.agentThreadId === 'string' ? record.agentThreadId : '';
if (!childThreadId) return null;
return {
taskId,
childThreadIds: [childThreadId],
...(typeof record.agentPath === 'string' && record.agentPath ? { agentPath: record.agentPath } : {}),
...(typeof record.model === 'string' && record.model ? { model: record.model } : {}),
};
}
if (record.type === 'collabAgentToolCall') {
// 工具名两轨拼写不同(V1 spawnAgent / 上游 main spawn),都以 spawn 前缀判定。
const tool = typeof record.tool === 'string' ? record.tool : '';
if (!tool.toLowerCase().startsWith('spawn')) return null;
const receivers = Array.isArray(record.receiverThreadIds)
? record.receiverThreadIds.filter((id): id is string => typeof id === 'string' && id.length > 0)
: [];
if (receivers.length === 0) return null;
return {
taskId,
childThreadIds: receivers,
...(typeof record.model === 'string' && record.model ? { model: record.model } : {}),
...(record.status === 'failed' ? { failed: true } : {}),
};
}
return null;
}
function handleSubAgentActivity(
phase: ItemPhase,
item: SubAgentActivityItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (item.kind !== 'started' || phase === 'updated') return;
// 瞬时 item:started/completed phase 各到一次,按 item.id 去重只发一张卡;
// completed 到达即清 Set(与 collab handler 同规——不清会随 spawn 次数无限增长)。
if (ctx.rt.emittedToolUse.has(item.id)) {
if (phase === 'completed') ctx.rt.emittedToolUse.delete(item.id);
return;
}
// started phase 登记等 completed 清理;只收到 completed(防御)时无后续 phase,不登记。
if (phase === 'started') ctx.rt.emittedToolUse.add(item.id);
const agentPath = typeof item.agentPath === 'string' ? item.agentPath : undefined;
const model = typeof item.model === 'string' && item.model ? item.model : undefined;
const reasoningEffort = typeof item.reasoningEffort === 'string' && item.reasoningEffort
? item.reasoningEffort
: undefined;
const input: Record<string, unknown> = {};
if (agentPath) input.name = agentPath;
if (item.agentThreadId) input.agentThreadId = item.agentThreadId;
if (model) input.model = model;
if (reasoningEffort) input.reasoningEffort = reasoningEffort;
queue.push({
type: 'tool_use',
data: { toolUseId: item.id, toolName: 'collab:spawn', input },
source: 'codex',
});
// fullText 只放结构化数据(agentPath 原文):用户可见的「已启动」句子由 renderer
// 按 locale 组装(AgentTaskCard 以 result===input.name 识别本卡),translator 不
// 合成任何语言的句子——否则英文回执会持久化进历史(review r3698558356)。
queue.push({
type: 'tool_result_full',
data: { toolUseId: item.id, fullText: agentPath ?? '', isError: false },
source: 'codex',
});
queue.push({
type: 'tool_result',
data: { summary: 'started', toolUseIds: [item.id] },
source: 'codex',
});
// 卡片置 running:tool_result 已就地收口(不留悬空工具调用),而 AgentTaskCard 的
// status 以 update 优先,子代理仍显示为运行中,直到子线程 turn 收口把它翻成终态。
queue.push({
type: 'agent_task_update',
data: {
provider: 'codex',
taskId: item.id,
parentToolUseId: item.id,
status: 'running',
subagentObservation: {
kind: 'spawn',
logicalSubagentId: item.id,
parentToolUseId: item.id,
...(item.agentThreadId ? { providerRunIds: [item.agentThreadId] } : {}),
},
...(item.agentThreadId ? { receiverThreadIds: [item.agentThreadId] } : {}),
...(agentPath ? { title: agentPath } : {}),
...(model ? { model } : {}),
...(reasoningEffort ? { reasoningEffort } : {}),
},
source: 'codex',
});
}
function toCodexTaskUpdate(
item: CollabAgentToolCallItem,
status: AgentTaskStatus,
summary?: string,
completedOnly = false,
): AgentTaskUpdateEventData {
const isSpawn = item.tool.toLowerCase().startsWith('spawn');
const subagentObservation = isSpawn
&& item.receiverThreadIds.length > 0
&& (status !== 'completed' || completedOnly)
? {
kind: status === 'running' || completedOnly ? 'spawn' as const : 'terminal' as const,
logicalSubagentId: item.id,
parentToolUseId: item.id,
...(status === 'running' || completedOnly
? { providerRunIds: item.receiverThreadIds }
: {}),
}
: undefined;
return {
provider: 'codex',
taskId: item.id,
parentToolUseId: item.id,
status,
title: item.tool,
...(item.prompt ? { description: item.prompt } : {}),
...(summary ? { summary } : {}),
...(item.model ? { model: item.model } : {}),
...(item.reasoningEffort ? { reasoningEffort: item.reasoningEffort } : {}),
receiverThreadIds: item.receiverThreadIds,
...(subagentObservation ? { subagentObservation } : {}),
raw: { tool: item.tool, agentsStates: item.agentsStates },
};
}
// Native image reads are tool steps, with their preview inside the work group.
// Only completed items have usable media; emit the step once.
function handleImageView(
phase: ItemPhase,
item: ImageViewItem,
queue: AsyncQueue<AgentEvent>,
): void {
if (phase !== 'completed') return;
queue.push({ type: 'tool_use', source: 'codex',
data: { toolUseId: item.id, toolName: 'view_image', input: { path: item.path } } });
queue.push({ type: 'tool_result_full', source: 'codex',
data: { toolUseId: item.id, fullText: item.path,
processMedia: [{ kind: 'image', path: item.path } satisfies NativeToolMedia] } });
queue.push({ type: 'tool_result', source: 'codex',
data: { toolUseIds: [item.id], summary: 'done' } });
}
// ── imageGeneration → image event (kind='generation') ────────────────────────
// Preserve bytes independently of savedPath: that path may belong to another computer.
// Decode/validate/store in the Host, outside the synchronous translator hot path.
function isUrlLike(s: string): boolean {
return /^(https?:|data:)/i.test(s);
}
function handleImageGeneration(
phase: ItemPhase,
item: ImageGenerationItem,
queue: AsyncQueue<AgentEvent>,
identity: { threadId: string; turnId: string },
): void {
if (phase !== 'completed') return;
const data: GeneratedImageEventData = {
kind: 'generation',
blockId: item.id,
threadId: identity.threadId,
turnId: identity.turnId,
status: item.status,
};
if (item.revisedPrompt) data.revisedPrompt = item.revisedPrompt;
if (item.savedPath) data.path = item.savedPath;
if (item.result) {
if (isUrlLike(item.result)) data.url = item.result;
// Keep the historical path-only result shape, but never interpret Base64 as a path.
else if (/^(?:[A-Za-z]:[\\/]|\.\.?[\\/])/.test(item.result)
|| /\.(?:png|jpe?g|gif|webp)$/i.test(item.result)) data.path ??= item.result;
else data.data = item.result;
}
queue.push({ type: 'image', data, source: 'codex' });
}
// ── contextCompaction → compact_boundary ─────────────────────────────────────
// codex auto-compact 边界 — 协议只给 id, 没有 trigger / pre/post tokens / duration。
// trigger 一律 'auto' (codex 没暴露手动 compact 入口给 UI), 其他字段 0 占位。
// 与 claude-code translator handleSystem (subtype=compact_boundary) 形状对齐。
function handleContextCompaction(
phase: ItemPhase,
item: ContextCompactionItem,
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
if (phase !== 'completed') return;
ctx.log.info('codex ◾ contextCompaction', { id: item.id });
queue.push({
type: 'compact_boundary',
data: {
boundaryId: item.id,
trigger: 'auto',
preTokens: 0,
postTokens: 0,
durationMs: 0,
},
source: 'codex',
});
ctx.onCompactBoundary?.();
}
// ── account/rateLimits/updated → 'account_usage' event ───────────────────────
// 账号级 notification, host 已做 fan-out + replay 到所有 active subscriber, 这里
// 直接把 params.rateLimits 作为 event.data 透传给 renderer。data shape 不立类型
// (跟 image / compact_boundary 一样 inline), renderer 端 useAccountUsage hook
// 按字段嗅探解析。
export function translateAccountRateLimitsUpdated(
params: AccountRateLimitsUpdatedNotification['params'],
queue: AsyncQueue<AgentEvent>,
ctx: CodexTranslateContext,
): void {
void ctx;
queue.push({
type: 'account_usage',
data: normalizeAccountRateLimitSnapshot(params.rateLimits),
source: 'codex',
});
}