@meistrari/agent-core 0.0.0 → 0.1.0

package/src/agents/codex/codex-event-mapper.ts

@@ -0,0 +1,708 @@
+import type { AgentError, AgentEventActor, AgentMessageRole, AgentSubagentStatus, AgentToolCallStatus, AgentToolContent, AgentToolResult, AgentTurnEndStatus, AgentUsage, JsonObject, JsonValue } from '../../protocol'
+import type { AgentWorkStatus } from '../../protocol/agent-work'
+import type { AgentEventDraft } from '../agent-event-stream'
+import type { CodexJsonRpcMessage, CodexServerNotification } from './codex-json-rpc-client'
+import type { ServerNotificationParamsByMethod } from './codex-protocol'
+import { jsonObjectSchema, jsonValueSchema } from '../../protocol'
+import { CANONICAL_TOOL } from '../../protocol/agent-tool-name'
+import { createRuntimeWorkItemId } from '../agent-id'
+import { AgentProviderProtocolError } from '../agent-runtime-error'
+import { stripAuthorContext } from '../author-context'
+import { optionalNonEmpty, removeUndefined } from '../normalize'
+import { isCodexServerNotification } from './codex-json-rpc-client'
+
+export type CodexNotification = CodexServerNotification
+
+type CodexTokenUsage = ServerNotificationParamsByMethod['thread/tokenUsage/updated']['tokenUsage']
+type CodexTokenCounts = CodexTokenUsage['total']
+type CodexPlanStepStatus = ServerNotificationParamsByMethod['turn/plan/updated']['plan'][number]['status']
+type CodexStartedItem = ServerNotificationParamsByMethod['item/started']['item']
+type CodexCompletedItem = ServerNotificationParamsByMethod['item/completed']['item']
+type CodexWebSearchItem = Extract<CodexCompletedItem, { type: 'webSearch' }>
+type CodexFileChangeItem = Extract<CodexCompletedItem, { type: 'fileChange' }>
+type CodexImageGenerationItem = Extract<CodexCompletedItem, { type: 'imageGeneration' }>
+type CodexUserMessageItem = Extract<CodexCompletedItem, { type: 'userMessage' }>
+type CodexHookPromptItem = Extract<CodexCompletedItem, { type: 'hookPrompt' }>
+type CodexDynamicToolCompletedItem = Extract<CodexCompletedItem, { type: 'dynamicToolCall' }>
+type CodexDynamicToolContentItem = NonNullable<CodexDynamicToolCompletedItem['contentItems']>[number]
+type CodexCollabAgentToolCompletedItem = Extract<CodexCompletedItem, { type: 'collabAgentToolCall' }>
+type CodexCollabAgentToolStartedItem = Extract<CodexStartedItem, { type: 'collabAgentToolCall' }>
+type CodexSubAgentActivityCompletedItem = Extract<CodexCompletedItem, { type: 'subAgentActivity' }>
+type CodexCollabAgentState = CodexCollabAgentToolCompletedItem['agentsStates'][string]
+type CodexThread = ServerNotificationParamsByMethod['thread/started']['thread']
+type CodexThreadMetadata = Pick<CodexThread, 'id' | 'agentNickname' | 'agentRole'>
+type CodexTurn = ServerNotificationParamsByMethod['turn/completed']['turn']
+type CodexTurnError = NonNullable<CodexTurn['error']>
+type CodexSubagentRef = Extract<AgentEventActor, { type: 'subagent' }>
+interface CodexPromptCommandRef { commandId: string, origin: 'user' | 'supervisor' }
+type CodexTurnEventDraft = Extract<AgentEventDraft, { turnId: string }>
+type CodexUnownedTurnEventDraft = CodexTurnEventDraft extends infer Draft
+    ? Draft extends CodexTurnEventDraft
+        ? Omit<Draft, 'actor'>
+        : never
+    : never
+
+const mainActor = { type: 'main', actorId: 'main' } satisfies AgentEventActor
+
+export interface CodexEventMapperState {
+    readonly endedSubagentIds: Set<string>
+    readonly subagentByThreadId: Map<string, CodexSubagentRef>
+    readonly subagentById: Map<string, CodexSubagentRef>
+    readonly subagentNameByThreadId: Map<string, string>
+    readonly pendingDraftsByThreadId: Map<string, CodexUnownedTurnEventDraft[]>
+    readonly turnErrorsById: Map<string, AgentError>
+    readonly startedTurnIds: Set<string>
+    readonly startedReasoningIds: Set<string>
+    readonly reasoningSummaryById: Map<string, Map<number, string>>
+    readonly promptCommandByClientUserMessageId: Map<string, CodexPromptCommandRef>
+    mainThreadId?: string
+}
+
+export function createCodexEventMapperState(): CodexEventMapperState {
+    return { endedSubagentIds: new Set(), subagentByThreadId: new Map(), subagentById: new Map(), subagentNameByThreadId: new Map(), pendingDraftsByThreadId: new Map(), turnErrorsById: new Map(), startedTurnIds: new Set(), startedReasoningIds: new Set(), reasoningSummaryById: new Map(), promptCommandByClientUserMessageId: new Map() }
+}
+
+export function codexNotificationFromMessage(message: CodexJsonRpcMessage): CodexNotification | null {
+    return isCodexServerNotification(message) ? message : null
+}
+
+export function cacheCodexThreadMetadata(thread: CodexThreadMetadata, state: CodexEventMapperState): void {
+    cacheThreadMetadata(thread, state)
+}
+
+export function mapCodexNotification(notification: CodexNotification, state: CodexEventMapperState): AgentEventDraft[] {
+    // Codex has many app-server notifications; the runtime maps the subset that has a provider-neutral AgentEvent.
+
+    switch (notification.method) {
+        case 'thread/started':
+            cacheThreadMetadata(notification.params.thread, state)
+            return []
+        case 'turn/started':
+            state.mainThreadId ??= notification.params.threadId
+            state.startedTurnIds.add(notification.params.turn.id)
+            return emitOrBufferByThread({ draft: { type: 'turn.started', turnId: notification.params.turn.id, payload: {} }, threadId: notification.params.threadId, state })
+        case 'turn/completed': {
+            if (!state.startedTurnIds.has(notification.params.turn.id))
+                return []
+            const payload = turnEndedPayload(notification.params.turn, state)
+            return [
+                ...mapChildTurnCompleted({ threadId: notification.params.threadId, turnId: notification.params.turn.id, turnPayload: payload, state }),
+                ...emitOrBufferByThread({ draft: { type: 'turn.ended', turnId: notification.params.turn.id, payload }, threadId: notification.params.threadId, state }),
+            ]
+        }
+        case 'thread/tokenUsage/updated': {
+            if (!state.startedTurnIds.has(notification.params.turnId))
+                return []
+            const usage = usageFromTokenUsage(notification.params.tokenUsage)
+            if (!usage)
+                return []
+            return emitOrBufferByThread({ draft: { type: 'usage', turnId: notification.params.turnId, payload: { usage } }, threadId: notification.params.threadId, state })
+        }
+        case 'turn/plan/updated':
+            if (!state.startedTurnIds.has(notification.params.turnId) || notification.params.threadId !== state.mainThreadId)
+                return []
+            return [{
+                type: 'work.observed',
+                turnId: notification.params.turnId,
+                actor: mainActor,
+                payload: {
+                    observations: [{
+                        kind: 'snapshot',
+                        items: notification.params.plan.map(item => ({
+                            id: createRuntimeWorkItemId(),
+                            title: item.step,
+                            status: workStatusFromCodexPlan(item.status),
+                        })),
+                    }],
+                },
+            }]
+        case 'error':
+            if (!state.startedTurnIds.has(notification.params.turnId))
+                return []
+            if (!notification.params.willRetry)
+                state.turnErrorsById.set(notification.params.turnId, agentErrorFromCodexTurnError(notification.params.error))
+            return []
+        case 'item/agentMessage/delta':
+            if (!state.startedTurnIds.has(notification.params.turnId))
+                return []
+            return emitOrBufferByThread({ draft: { type: 'message.delta', turnId: notification.params.turnId, payload: { messageId: notification.params.itemId, role: 'assistant', delta: notification.params.delta } }, threadId: notification.params.threadId, state })
+        case 'item/reasoning/summaryTextDelta': {
+            if (!state.startedTurnIds.has(notification.params.turnId) || !notification.params.delta)
+                return []
+            appendReasoningSummaryDelta({ reasoningId: notification.params.itemId, summaryIndex: notification.params.summaryIndex, delta: notification.params.delta, state })
+            if (!state.startedReasoningIds.has(notification.params.itemId)) {
+                const summary = accumulatedReasoningSummary(notification.params.itemId, state)
+                if (!summary)
+                    return []
+                const started = ensureReasoningStarted({ reasoningId: notification.params.itemId, turnId: notification.params.turnId, threadId: notification.params.threadId, state })
+                return [...started, ...emitOrBufferByThread({ draft: { type: 'reasoning.summary.delta', turnId: notification.params.turnId, payload: { reasoningId: notification.params.itemId, text: summary } }, threadId: notification.params.threadId, state })]
+            }
+            return emitOrBufferByThread({ draft: { type: 'reasoning.summary.delta', turnId: notification.params.turnId, payload: { reasoningId: notification.params.itemId, text: notification.params.delta } }, threadId: notification.params.threadId, state })
+        }
+        case 'item/commandExecution/outputDelta':
+        case 'item/fileChange/outputDelta':
+            if (!state.startedTurnIds.has(notification.params.turnId))
+                return []
+            return emitOrBufferByThread({ draft: { type: 'tool.output.delta', turnId: notification.params.turnId, payload: { toolCallId: notification.params.itemId, delta: notification.params.delta } }, threadId: notification.params.threadId, state })
+        case 'item/started':
+            if (!state.startedTurnIds.has(notification.params.turnId))
+                return []
+            return mapItemStarted({ turnId: notification.params.turnId, threadId: notification.params.threadId, item: notification.params.item, state })
+        case 'item/completed':
+            if (!state.startedTurnIds.has(notification.params.turnId))
+                return []
+            return mapItemCompleted({ turnId: notification.params.turnId, threadId: notification.params.threadId, item: notification.params.item, state })
+        default:
+            return []
+    }
+}
+
+function workStatusFromCodexPlan(status: CodexPlanStepStatus): AgentWorkStatus {
+    if (status === 'inProgress')
+        return 'in_progress'
+    return status
+}
+
+function turnEndedPayload(turn: CodexTurn, state: CodexEventMapperState): Extract<AgentEventDraft, { type: 'turn.ended' }>['payload'] {
+    const status = turnEndStatusFromCodex(turn.status)
+    const providerError = turn.error ? agentErrorFromCodexTurnError(turn.error) : state.turnErrorsById.get(turn.id)
+    if (providerError)
+        state.turnErrorsById.delete(turn.id)
+
+    return removeUndefined({
+        status,
+        reason: turn.status,
+        error: providerError,
+        duration: turn.durationMs ?? undefined,
+    })
+}
+
+function turnEndStatusFromCodex(status: CodexTurn['status']): AgentTurnEndStatus {
+    if (status === 'completed')
+        return 'completed'
+    if (status === 'failed')
+        return 'failed'
+    if (status === 'interrupted')
+        return 'interrupted'
+
+    throw new AgentProviderProtocolError({ message: `Codex emitted turn/completed with non-terminal status: ${status}` })
+}
+
+function mapItemStarted({ turnId, threadId, item, state }: { turnId: string, threadId: string, item: CodexStartedItem, state: CodexEventMapperState }): AgentEventDraft[] {
+    const message = messageForItem(item, state)
+    if (message)
+        return emitOrBufferByThread({ draft: { type: 'message.started', turnId, payload: removeUndefined({ messageId: item.id, ...message }) }, threadId, state })
+
+    const toolCall = toolCallStart(item)
+    if (toolCall)
+        return emitOrBufferByThread({ draft: { type: 'tool.call.started', turnId, payload: { toolCallId: item.id, toolName: toolCall.toolName, input: toolCall.input } }, threadId, state })
+
+    if (item.type === 'contextCompaction')
+        return emitOrBufferByThread({ draft: { type: 'context.compaction.started', turnId, payload: { compactionId: item.id, trigger: 'unknown' } }, threadId, state })
+
+    return []
+}
+
+function toolCallStart(item: CodexStartedItem): { toolName: string, input: JsonValue } | undefined {
+    if (item.type === 'commandExecution')
+        return { toolName: CANONICAL_TOOL.bash, input: toJsonObject({ command: Array.isArray(item.command) ? item.command.join(' ') : String(item.command ?? ''), cwd: item.cwd }) }
+    if (item.type === 'webSearch')
+        return { toolName: CANONICAL_TOOL.webSearch, input: toJsonObject({ query: optionalNonEmpty(item.query) }) }
+    if (item.type === 'fileChange')
+        return { toolName: CANONICAL_TOOL.edit, input: jsonInput({ files: item.changes.map(change => removeUndefined({ path: change.path, kind: change.kind?.type })) }) }
+    if (item.type === 'imageView')
+        return { toolName: CANONICAL_TOOL.viewImage, input: toJsonObject({ path: item.path }) }
+    if (item.type === 'imageGeneration')
+        return { toolName: CANONICAL_TOOL.imageGeneration, input: toJsonObject({ revisedPrompt: optionalNonEmpty(item.revisedPrompt) }) }
+    if (item.type === 'dynamicToolCall')
+        return { toolName: item.tool, input: jsonInput(item.arguments) }
+    if (item.type === 'collabAgentToolCall')
+        return { toolName: item.tool, input: collabToolInput(item) }
+    return undefined
+}
+
+function appendReasoningSummaryDelta({ reasoningId, summaryIndex, delta, state }: { reasoningId: string, summaryIndex: number, delta: string, state: CodexEventMapperState }): void {
+    const sections = state.reasoningSummaryById.get(reasoningId) ?? new Map<number, string>()
+    sections.set(summaryIndex, (sections.get(summaryIndex) ?? '') + delta)
+    state.reasoningSummaryById.set(reasoningId, sections)
+}
+
+function ensureReasoningStarted({ reasoningId, turnId, threadId, state }: { reasoningId: string, turnId: string, threadId: string, state: CodexEventMapperState }): AgentEventDraft[] {
+    if (state.startedReasoningIds.has(reasoningId))
+        return []
+    state.startedReasoningIds.add(reasoningId)
+    return emitOrBufferByThread({ draft: { type: 'reasoning.started', turnId, payload: { reasoningId } }, threadId, state })
+}
+
+function mapItemCompleted({ turnId, threadId, item, state }: { turnId: string, threadId: string, item: CodexCompletedItem, state: CodexEventMapperState }): AgentEventDraft[] {
+    const message = messageForItem(item, state)
+    if (message)
+        return emitOrBufferByThread({ draft: { type: 'message.ended', turnId, payload: removeUndefined({ messageId: item.id, ...message, text: messageEndedText(item) }) }, threadId, state })
+
+    const completion = toolCallCompletion(item)
+    if (completion)
+        return emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: removeUndefined({ toolCallId: item.id, ...completion }) }, threadId, state })
+
+    if (item.type === 'subAgentActivity')
+        return mapSubAgentActivityCompleted({ turnId, threadId, item, state })
+
+    if (item.type === 'contextCompaction')
+        return emitOrBufferByThread({ draft: { type: 'context.compaction.completed', turnId, payload: { compactionId: item.id, trigger: 'unknown', status: 'completed' } }, threadId, state })
+
+    if (item.type === 'reasoning')
+        return mapReasoningCompleted({ turnId, threadId, item, state })
+
+    if (item.type === 'collabAgentToolCall')
+        return mapCollabAgentToolCompleted({ turnId, threadId, item, mapperState: state })
+
+    return []
+}
+
+function mapReasoningCompleted({ turnId, threadId, item, state }: { turnId: string, threadId: string, item: Extract<CodexCompletedItem, { type: 'reasoning' }>, state: CodexEventMapperState }): AgentEventDraft[] {
+    const accumulatedSummary = accumulatedReasoningSummary(item.id, state)
+    state.reasoningSummaryById.delete(item.id)
+
+    const authoritativeSummary = summaryIfDisplayable(item.summary?.join('\n'))
+    const summary = authoritativeSummary ?? accumulatedSummary
+    if (!summary)
+        return []
+
+    return [
+        ...ensureReasoningStarted({ reasoningId: item.id, turnId, threadId, state }),
+        ...emitOrBufferByThread({ draft: { type: 'reasoning.ended', turnId, payload: removeUndefined({ reasoningId: item.id, summary }) }, threadId, state }),
+    ]
+}
+
+function accumulatedReasoningSummary(reasoningId: string, state: CodexEventMapperState): string | undefined {
+    return summaryIfDisplayable([...state.reasoningSummaryById.get(reasoningId)?.entries() ?? []]
+        .sort(([left], [right]) => left - right)
+        .map(([, section]) => section)
+        .join('\n'))
+}
+
+function summaryIfDisplayable(value: string | undefined): string | undefined {
+    return optionalNonEmpty(value) ? value : undefined
+}
+
+function messageForItem(item: CodexStartedItem | CodexCompletedItem, state: CodexEventMapperState): { role: AgentMessageRole, commandId?: string } | undefined {
+    if (item.type === 'agentMessage')
+        return { role: 'assistant' }
+    if (item.type === 'hookPrompt')
+        return { role: 'system' }
+    if (item.type !== 'userMessage')
+        return undefined
+
+    const promptCommand = item.clientId ? state.promptCommandByClientUserMessageId.get(item.clientId) : undefined
+    const role: AgentMessageRole = promptCommand?.origin === 'supervisor' ? 'system' : 'user'
+    return removeUndefined({ role, commandId: promptCommand?.commandId })
+}
+
+function toolCallCompletion(item: CodexCompletedItem): { status: AgentToolCallStatus, output?: AgentToolResult, error?: AgentError } | undefined {
+    if (item.type === 'webSearch')
+        return { status: 'completed', output: webSearchResult(item) }
+    if (item.type === 'fileChange') {
+        const status = fileChangeStatus(item.status)
+        return { status, output: fileChangeResult(item, status), error: status === 'failed' ? { message: 'Codex failed to apply the patch.' } : undefined }
+    }
+    if (item.type === 'imageView')
+        return { status: 'completed', output: { success: true, content: [{ type: 'text', text: item.path }] } }
+    if (item.type === 'imageGeneration')
+        return { status: item.status === 'failed' ? 'failed' : 'completed', output: imageGenerationResult(item) }
+    if (item.type === 'commandExecution') {
+        const status = item.exitCode === undefined || item.exitCode === null || item.exitCode === 0 ? 'completed' : 'failed'
+        return { status, output: commandExecutionResult(item, status), error: 'error' in item && typeof item.error === 'string' ? { message: item.error } : undefined }
+    }
+    if (item.type === 'dynamicToolCall')
+        return { status: item.success === false ? 'failed' : 'completed', output: dynamicToolResult(item) }
+    return undefined
+}
+
+function webSearchResult(item: CodexWebSearchItem): AgentToolResult {
+    const lines: string[] = []
+    const query = optionalNonEmpty(item.query)
+    if (query)
+        lines.push(`Query: ${query}`)
+    const url = webSearchActionUrl(item.action)
+    if (url)
+        lines.push(url)
+    return { success: true, content: [{ type: 'text', text: lines.join('\n') || 'Web search completed.' }] }
+}
+
+function webSearchActionUrl(action: CodexWebSearchItem['action']): string | undefined {
+    if (action && (action.type === 'openPage' || action.type === 'findInPage'))
+        return optionalNonEmpty(action.url)
+    return undefined
+}
+
+function fileChangeStatus(status: CodexFileChangeItem['status']): AgentToolCallStatus {
+    if (status === 'failed')
+        return 'failed'
+    if (status === 'declined')
+        return 'cancelled'
+    return 'completed'
+}
+
+function fileChangeResult(item: CodexFileChangeItem, status: AgentToolCallStatus): AgentToolResult | undefined {
+    const text = item.changes.map(change => change.diff).filter(diff => diff && diff.trim()).join('\n')
+    if (!text)
+        return undefined
+    return { success: status === 'completed', content: [{ type: 'text', text }] }
+}
+
+function imageGenerationResult(item: CodexImageGenerationItem): AgentToolResult | undefined {
+    const lines: string[] = []
+    const savedPath = optionalNonEmpty(item.savedPath)
+    if (savedPath)
+        lines.push(`Saved to ${savedPath}`)
+    const revised = optionalNonEmpty(item.revisedPrompt)
+    if (revised)
+        lines.push(`Revised prompt: ${revised}`)
+    if (!lines.length)
+        return undefined
+    return { success: item.status !== 'failed', content: [{ type: 'text', text: lines.join('\n') }] }
+}
+
+function messageEndedText(item: CodexCompletedItem): string | undefined {
+    if (item.type === 'userMessage')
+        return userMessageText(item)
+    if (item.type === 'hookPrompt')
+        return hookPromptText(item)
+    if (item.type === 'agentMessage')
+        return item.text || undefined
+    return undefined
+}
+
+function userMessageText(item: CodexUserMessageItem): string | undefined {
+    const parts: string[] = []
+    for (const entry of item.content) {
+        if (entry.type === 'text')
+            parts.push(entry.text)
+    }
+    return optionalNonEmpty(stripAuthorContext(parts.join('\n')))
+}
+
+function hookPromptText(item: CodexHookPromptItem): string | undefined {
+    return optionalNonEmpty(item.fragments.map(fragment => fragment.text).join('\n'))
+}
+
+function commandExecutionResult(item: Extract<CodexCompletedItem, { type: 'commandExecution' }>, status: 'completed' | 'failed'): AgentToolResult | undefined {
+    const text = optionalNonEmpty(item.aggregatedOutput ?? undefined)
+    if (!text)
+        return undefined
+
+    return { success: status === 'completed', content: [{ type: 'text', text }] }
+}
+
+function dynamicToolResult(item: CodexDynamicToolCompletedItem): AgentToolResult | undefined {
+    if (!item.contentItems)
+        return undefined
+
+    return {
+        success: item.success ?? item.status !== 'failed',
+        content: item.contentItems.map(dynamicToolContent),
+    }
+}
+
+function dynamicToolContent(item: CodexDynamicToolContentItem): AgentToolContent {
+    if (item.type === 'inputText')
+        return { type: 'text', text: item.text }
+
+    if (item.type === 'inputAudio')
+        return { type: 'text', text: item.audioUrl }
+
+    const dataUrl = /^data:([^;,]+);base64,(.*)$/s.exec(item.imageUrl)
+    if (dataUrl)
+        return { type: 'image', mimeType: dataUrl[1] ?? 'application/octet-stream', data: dataUrl[2] ?? '' }
+
+    return { type: 'text', text: item.imageUrl }
+}
+
+function mapCollabAgentToolCompleted({ turnId, threadId, item, mapperState }: { turnId: string, threadId: string, item: CodexCollabAgentToolCompletedItem, mapperState: CodexEventMapperState }): AgentEventDraft[] {
+    const drafts = emitOrBufferByThread({
+        draft: {
+            type: 'tool.call.completed',
+            turnId,
+            payload: removeUndefined({
+                toolCallId: item.id,
+                status: item.status === 'failed' ? 'failed' as const : 'completed' as const,
+                error: item.status === 'failed' ? { message: `Codex ${item.tool} failed.` } : undefined,
+            }),
+        },
+        threadId,
+        state: mapperState,
+    })
+
+    if (item.tool === 'spawnAgent') {
+        const subagentId = item.receiverThreadIds.at(0)
+        if (!subagentId || item.status === 'failed' || mapperState.subagentByThreadId.has(subagentId))
+            return drafts
+
+        const actor = subagentActorFromCollabItem({ subagentId, parentToolCallId: item.id, name: mapperState.subagentNameByThreadId.get(subagentId) })
+        mapperState.subagentByThreadId.set(subagentId, actor)
+        mapperState.subagentById.set(subagentId, actor)
+        drafts.push({
+            type: 'subagent.started',
+            turnId,
+            actor,
+            payload: removeUndefined({
+                ...subagentPayloadRef(actor),
+                description: optionalNonEmpty(item.prompt),
+            }),
+        })
+        drafts.push(...flushPendingDrafts(subagentId, mapperState))
+        return drafts
+    }
+
+    if (item.tool !== 'wait' && item.tool !== 'closeAgent')
+        return drafts
+
+    drafts.push(...Object.entries(item.agentsStates).flatMap(([subagentId, state]) => {
+        const status = subagentStatusFromAgentState(state)
+        const actor = mapperState.subagentById.get(subagentId)
+        if (!status || !actor || mapperState.endedSubagentIds.has(subagentId))
+            return []
+
+        mapperState.endedSubagentIds.add(subagentId)
+        return [{
+            type: 'subagent.ended',
+            turnId,
+            actor,
+            payload: removeUndefined({
+                ...subagentPayloadRef(actor),
+                status,
+                summary: optionalNonEmpty(state.message),
+                error: status === 'failed' ? { message: optionalNonEmpty(state.message) ?? `Subagent ${subagentId} failed.` } : undefined,
+            }),
+        } satisfies AgentEventDraft]
+    }))
+    return drafts
+}
+
+function mapSubAgentActivityCompleted(input: { turnId: string, threadId: string, item: CodexSubAgentActivityCompletedItem, state: CodexEventMapperState }): AgentEventDraft[] {
+    const { turnId, threadId, item, state } = input
+    if (item.kind === 'started') {
+        if (state.subagentByThreadId.has(item.agentThreadId))
+            return []
+
+        const actor = subagentActorFromCollabItem({
+            subagentId: item.agentThreadId,
+            parentToolCallId: item.id,
+            name: item.agentPath,
+        })
+        state.subagentByThreadId.set(item.agentThreadId, actor)
+        state.subagentById.set(item.agentThreadId, actor)
+        return [
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.started', turnId, payload: { toolCallId: item.id, toolName: 'spawnAgent' } }, threadId, state }),
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, status: 'completed' } }, threadId, state }),
+            {
+                type: 'subagent.started',
+                turnId,
+                actor,
+                payload: subagentPayloadRef(actor),
+            },
+            ...flushPendingDrafts(item.agentThreadId, state),
+        ]
+    }
+
+    if (item.kind === 'interacted') {
+        return [
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.started', turnId, payload: { toolCallId: item.id, toolName: 'sendInput' } }, threadId, state }),
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, status: 'completed' } }, threadId, state }),
+        ]
+    }
+
+    if (item.kind !== 'interrupted')
+        return []
+
+    const actor = state.subagentByThreadId.get(item.agentThreadId)
+    if (!actor || state.endedSubagentIds.has(item.agentThreadId))
+        return []
+
+    state.endedSubagentIds.add(item.agentThreadId)
+    return [{
+        type: 'subagent.ended',
+        turnId,
+        actor,
+        payload: {
+            ...subagentPayloadRef(actor),
+            status: 'cancelled',
+        },
+    }]
+}
+
+function mapChildTurnCompleted(input: {
+    threadId: string
+    turnId: string
+    turnPayload: Extract<AgentEventDraft, { type: 'turn.ended' }>['payload']
+    state: CodexEventMapperState
+}): AgentEventDraft[] {
+    const actor = input.state.subagentByThreadId.get(input.threadId)
+    if (!actor || input.state.endedSubagentIds.has(actor.subagentId))
+        return []
+
+    input.state.endedSubagentIds.add(actor.subagentId)
+    return [subagentEndedFromTurn({ actor, turnId: input.turnId, turnPayload: input.turnPayload })]
+}
+
+function subagentEndedFromTurn(input: {
+    actor: CodexSubagentRef
+    turnId: string
+    turnPayload: Extract<AgentEventDraft, { type: 'turn.ended' }>['payload']
+}): AgentEventDraft {
+    return {
+        type: 'subagent.ended',
+        turnId: input.turnId,
+        actor: input.actor,
+        payload: removeUndefined({
+            ...subagentPayloadRef(input.actor),
+            status: input.turnPayload.status === 'interrupted' ? 'cancelled' : input.turnPayload.status,
+            error: input.turnPayload.error,
+        }),
+    }
+}
+
+function subagentStatusFromAgentState(state: CodexCollabAgentState): AgentSubagentStatus | undefined {
+    if (state.status === 'completed')
+        return 'completed'
+    if (state.status === 'errored' || state.status === 'notFound')
+        return 'failed'
+    if (state.status === 'interrupted' || state.status === 'shutdown')
+        return 'cancelled'
+
+    return undefined
+}
+
+function agentErrorFromCodexTurnError(error: CodexTurnError): AgentError {
+    return removeUndefined({
+        message: error.message,
+        code: codexErrorCode(error.codexErrorInfo),
+    })
+}
+
+function codexErrorCode(info: CodexTurnError['codexErrorInfo']): string | undefined {
+    if (!info)
+        return undefined
+    if (typeof info === 'string')
+        return info
+    const key = Object.keys(info).at(0)
+    return key || undefined
+}
+
+function emitOrBufferByThread({ draft, threadId, state }: { draft: CodexUnownedTurnEventDraft, threadId: string, state: CodexEventMapperState }): AgentEventDraft[] {
+    const actor = actorForThread(threadId, state)
+    if (actor)
+        return [{ ...draft, actor }]
+
+    const pending = state.pendingDraftsByThreadId.get(threadId) ?? []
+    pending.push(draft)
+    state.pendingDraftsByThreadId.set(threadId, pending)
+    return []
+}
+
+function actorForThread(threadId: string, state: CodexEventMapperState): AgentEventActor | undefined {
+    const subagentActor = state.subagentByThreadId.get(threadId)
+    if (subagentActor)
+        return subagentActor
+    return state.mainThreadId === undefined || threadId === state.mainThreadId ? mainActor : undefined
+}
+
+function flushPendingDrafts(threadId: string, state: CodexEventMapperState): AgentEventDraft[] {
+    const actor = state.subagentByThreadId.get(threadId)
+    if (!actor)
+        return []
+    const pending = state.pendingDraftsByThreadId.get(threadId) ?? []
+    state.pendingDraftsByThreadId.delete(threadId)
+
+    const drafts: AgentEventDraft[] = []
+    for (const draft of pending) {
+        if (draft.type === 'turn.ended' && !state.endedSubagentIds.has(actor.subagentId)) {
+            state.endedSubagentIds.add(actor.subagentId)
+            drafts.push(subagentEndedFromTurn({ actor, turnId: draft.turnId, turnPayload: draft.payload }))
+        }
+        drafts.push({ ...draft, actor })
+    }
+    return drafts
+}
+
+function cacheThreadMetadata(thread: CodexThreadMetadata, state: CodexEventMapperState): void {
+    const name = codexSubagentDisplayName(thread)
+    if (name)
+        cacheSubagentName({ subagentId: thread.id, name }, state)
+}
+
+function cacheSubagentName(input: { subagentId: string, name: string }, state: CodexEventMapperState): void {
+    state.subagentNameByThreadId.set(input.subagentId, input.name)
+    const existing = state.subagentByThreadId.get(input.subagentId)
+    if (!existing || existing.name === input.name)
+        return
+
+    const renamed = { ...existing, name: input.name }
+    state.subagentByThreadId.set(input.subagentId, renamed)
+    state.subagentById.set(existing.subagentId, renamed)
+}
+
+function codexSubagentDisplayName(thread: CodexThreadMetadata): string | undefined {
+    const nickname = optionalNonEmpty(thread.agentNickname)
+    const role = optionalNonEmpty(thread.agentRole)
+    if (nickname && role)
+        return `${nickname} [${role}]`
+    return nickname ?? role
+}
+
+function subagentActorFromCollabItem(input: { subagentId: string, parentToolCallId: string, name?: string }): CodexSubagentRef {
+    return removeUndefined({
+        type: 'subagent' as const,
+        actorId: input.subagentId,
+        subagentId: input.subagentId,
+        parentActorId: 'main',
+        origin: { type: 'tool_call' as const, toolCallId: input.parentToolCallId },
+        parentToolCallId: input.parentToolCallId,
+        name: input.name,
+    })
+}
+
+function subagentPayloadRef(actor: CodexSubagentRef): Pick<CodexSubagentRef, 'actorId' | 'subagentId' | 'parentActorId' | 'origin' | 'parentToolCallId' | 'name'> {
+    return removeUndefined({
+        actorId: actor.actorId,
+        subagentId: actor.subagentId,
+        parentActorId: actor.parentActorId,
+        origin: actor.origin,
+        parentToolCallId: actor.parentToolCallId,
+        name: actor.name,
+    })
+}
+
+function collabToolInput(item: CodexCollabAgentToolStartedItem): JsonObject {
+    return toJsonObject({
+        senderThreadId: item.senderThreadId,
+        receiverThreadIds: item.receiverThreadIds.join(','),
+        prompt: item.prompt,
+        model: item.model,
+        reasoningEffort: typeof item.reasoningEffort === 'string' ? item.reasoningEffort : undefined,
+    })
+}
+
+function usageFromTokenUsage(value: CodexTokenUsage | undefined): AgentUsage | undefined {
+    return value ? usageFromCounts(value.last) : undefined
+}
+
+function usageFromCounts(value: CodexTokenCounts): AgentUsage {
+    return removeUndefined({
+        inputTokens: value.inputTokens,
+        outputTokens: value.outputTokens,
+        cacheReadTokens: value.cachedInputTokens,
+        reasoningOutputTokens: value.reasoningOutputTokens,
+        totalTokens: value.totalTokens,
+    })
+}
+
+function jsonInput(value: unknown): JsonValue {
+    const parsed = jsonValueSchema.safeParse(value)
+    if (parsed.success)
+        return parsed.data
+    return {}
+}
+
+function toJsonObject(value: { readonly [K in string]?: string | number | boolean | null | undefined }): JsonObject {
+    return jsonObjectSchema.parse(Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)))
+}