@meistrari/agent-core 0.0.0 → 0.1.0

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

@@ -0,0 +1,736 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { TaskCreateInput, TaskCreateOutput, TaskGetInput, TaskGetOutput, TaskListInput, TaskListOutput, TaskUpdateInput, TaskUpdateOutput } from '@anthropic-ai/claude-agent-sdk/sdk-tools'
+import type { MessageParam } from '@anthropic-ai/sdk/resources'
+import type { BetaMessage, BetaRawMessageStreamEvent, BetaUsage } from '@anthropic-ai/sdk/resources/beta/messages/messages'
+import type { AgentError, AgentEventActor, AgentUsage, JsonValue } from '../../protocol'
+import type { AgentWorkObservation } from '../../protocol/agent-work'
+import type { AgentEventDraft } from '../agent-event-stream'
+import z from 'zod'
+import { jsonValueSchema } from '../../protocol'
+import { canonicalToolName } from '../../protocol/agent-tool-name'
+import { agentWorkStatusSchema } from '../../protocol/agent-work'
+import { createRuntimeTurnId } from '../agent-id'
+import { AgentProviderProtocolError } from '../agent-runtime-error'
+import { optionalNonEmpty, removeUndefined } from '../normalize'
+import { CLAUDE_AGENT_TOOL_SERVER } from './claude-tool-mapper'
+
+type UserContentBlock = Exclude<MessageParam['content'], string>[number]
+type UserToolResultBlock = Extract<UserContentBlock, { type: 'tool_result' }>
+type ClaudeStatusMessage = Extract<SDKMessage, { type: 'system', subtype: 'status' }>
+type ClaudeCompactBoundaryMessage = Extract<SDKMessage, { type: 'system', subtype: 'compact_boundary' }>
+type ClaudeTaskStartedMessage = Extract<SDKMessage, { type: 'system', subtype: 'task_started' }>
+type ClaudeTaskProgressMessage = Extract<SDKMessage, { type: 'system', subtype: 'task_progress' }>
+type ClaudeTaskNotificationMessage = Extract<SDKMessage, { type: 'system', subtype: 'task_notification' }>
+type ClaudeUserMessage = Extract<SDKMessage, { type: 'user' }>
+type ClaudeSubagentActor = Extract<AgentEventActor, { type: 'subagent' }>
+type TaskCreateWorkInput = Pick<TaskCreateInput, 'subject' | 'description'>
+type TaskGetWorkInput = Pick<TaskGetInput, 'taskId'>
+type TaskUpdateWorkInput = Pick<TaskUpdateInput, 'taskId' | 'subject'>
+type TaskListWorkInput = TaskListInput
+interface TaskCreateWorkOutput { task: Pick<TaskCreateOutput['task'], 'id' | 'subject'> }
+interface TaskGetWorkOutput { task: Pick<NonNullable<TaskGetOutput['task']>, 'id' | 'subject' | 'status'> | null }
+type TaskUpdateWorkOutput = Pick<TaskUpdateOutput, 'success' | 'taskId' | 'updatedFields' | 'statusChange'>
+interface TaskListWorkOutput { tasks: Array<Pick<TaskListOutput['tasks'][number], 'id' | 'subject' | 'status'>> }
+type PendingClaudeWorkCall
+    = | { kind: 'create', input: TaskCreateWorkInput }
+        | { kind: 'get', input: TaskGetWorkInput }
+        | { kind: 'update', input: TaskUpdateWorkInput }
+        | { kind: 'list', input: TaskListWorkInput }
+type ClaudeTurnEventDraft = Extract<AgentEventDraft, { turnId: string }>
+type ClaudeUnownedTurnEventDraft = ClaudeTurnEventDraft extends infer Draft
+    ? Draft extends ClaudeTurnEventDraft
+        ? Omit<Draft, 'actor'>
+        : never
+    : never
+
+const mainActor = { type: 'main', actorId: 'main' } satisfies AgentEventActor
+
+const taskCreateWorkInputSchema = z.object({
+    subject: z.string().min(1),
+    description: z.string(),
+}).passthrough() satisfies z.ZodType<TaskCreateWorkInput>
+
+const taskGetWorkInputSchema = z.object({
+    taskId: z.string().min(1),
+}).passthrough() satisfies z.ZodType<TaskGetWorkInput>
+
+const taskUpdateWorkInputSchema = z.object({
+    taskId: z.string().min(1),
+    subject: z.string().min(1).optional(),
+}).passthrough() satisfies z.ZodType<TaskUpdateWorkInput>
+
+const taskListWorkInputSchema = z.object({}).passthrough() satisfies z.ZodType<TaskListWorkInput>
+
+const taskCreateWorkOutputSchema = z.object({
+    task: z.object({
+        id: z.string().min(1),
+        subject: z.string().min(1),
+    }).passthrough(),
+}).passthrough() satisfies z.ZodType<TaskCreateWorkOutput>
+
+const taskGetWorkOutputSchema = z.object({
+    task: z.object({
+        id: z.string().min(1),
+        subject: z.string().min(1),
+        status: agentWorkStatusSchema,
+    }).passthrough().nullable(),
+}).passthrough() satisfies z.ZodType<TaskGetWorkOutput>
+
+const taskUpdateWorkOutputSchema = z.object({
+    success: z.boolean(),
+    taskId: z.string().min(1),
+    updatedFields: z.array(z.string()),
+    statusChange: z.object({
+        from: z.string(),
+        to: z.enum(['pending', 'in_progress', 'completed', 'deleted']),
+    }).passthrough().optional(),
+}).passthrough() satisfies z.ZodType<TaskUpdateWorkOutput>
+
+const taskListWorkOutputSchema = z.object({
+    tasks: z.array(z.object({
+        id: z.string().min(1),
+        subject: z.string().min(1),
+        status: agentWorkStatusSchema,
+    }).passthrough()),
+}).passthrough() satisfies z.ZodType<TaskListWorkOutput>
+
+export interface ClaudeEventMapperState {
+    readonly toolNameById: Map<string, string>
+    readonly pendingWorkCallById: Map<string, PendingClaudeWorkCall>
+    readonly startedMessageIds: Set<string>
+    readonly endedMessageIds: Set<string>
+    readonly streamedTextByMessageId: Map<string, string>
+    readonly streamedReasoningMessageIds: Set<string>
+    readonly streamedReasoningByMessageId: Map<string, string>
+    readonly contentBlockTypeByIndex: Map<number, string>
+    readonly subagentByToolCallId: Map<string, ClaudeSubagentActor>
+    readonly actorByMessageId: Map<string, AgentEventActor>
+    readonly startedReasoningIds: Set<string>
+    readonly endedReasoningIds: Set<string>
+    turnStarted: boolean
+    interrupt: { status: 'none' } | { status: 'requesting' | 'accepted', turnId: string }
+    sessionState?: 'running' | 'idle'
+    currentTurnId?: string
+    currentMessageId?: string
+    currentCompactionId?: string
+}
+
+export function createClaudeEventMapperState(): ClaudeEventMapperState {
+    return {
+        toolNameById: new Map(),
+        pendingWorkCallById: new Map(),
+        startedMessageIds: new Set(),
+        endedMessageIds: new Set(),
+        streamedTextByMessageId: new Map(),
+        streamedReasoningMessageIds: new Set(),
+        streamedReasoningByMessageId: new Map(),
+        contentBlockTypeByIndex: new Map(),
+        subagentByToolCallId: new Map(),
+        actorByMessageId: new Map(),
+        startedReasoningIds: new Set(),
+        endedReasoningIds: new Set(),
+        turnStarted: false,
+        interrupt: { status: 'none' },
+    }
+}
+
+export function mapClaudeMessage(message: SDKMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+
+    if (message.type === 'system') {
+        if (message.subtype === 'session_state_changed' && message.state === 'running')
+            ensureTurnStarted(drafts, state)
+        if (message.subtype === 'session_state_changed' && message.state === 'idle')
+            ensureSessionIdle(drafts, state)
+        if (message.subtype === 'status')
+            drafts.push(...mapStatusMessage(message, state))
+        if (message.subtype === 'compact_boundary')
+            drafts.push(...mapCompactBoundaryMessage(message, state))
+        if (message.subtype === 'task_started')
+            drafts.push(...mapTaskStartedMessage(message, state))
+        if (message.subtype === 'task_progress')
+            drafts.push(...mapTaskProgressMessage(message, state))
+        if (message.subtype === 'task_notification')
+            drafts.push(...mapTaskNotificationMessage(message, state))
+        return drafts
+    }
+
+    if (message.type === 'assistant') {
+        const turnId = ensureTurnStarted(drafts, state)
+        const actor = actorFromParentToolUseId(message.parent_tool_use_id, state)
+        ensureAssistantMessageStarted(drafts, state, message.message, turnId, actor)
+        drafts.push(...mapAssistantContent(message.message, state, turnId, actor, message.parent_tool_use_id === null))
+        if (message.message.stop_reason !== null || shouldEndAssistantSnapshot(message.message, state, actor))
+            endAssistantMessage(drafts, state, message.message, turnId, actor)
+        return drafts
+    }
+
+    if (message.type === 'stream_event') {
+        const turnId = ensureTurnStarted(drafts, state)
+        const actor = actorFromParentToolUseId(message.parent_tool_use_id, state)
+        drafts.push(...mapStreamEvent(message.event, state, turnId, actor))
+        return drafts
+    }
+
+    if (message.type === 'user') {
+        const turnId = ensureTurnStarted(drafts, state)
+        const actor = actorFromParentToolUseId(message.parent_tool_use_id, state)
+        const content = message.message.content
+        const messageId = message.uuid ?? `user-${turnId}`
+        if (typeof content === 'string')
+            return actor ? subagentUserMessageEvents({ messageId, text: content, turnId, actor }) : drafts
+        if (actor)
+            drafts.push(...subagentUserContentEvents({ messageId, content, turnId, actor }))
+        drafts.push(...content.flatMap(block => mapUserContentBlock(block, message, state, turnId, actor, message.parent_tool_use_id === null)))
+        return drafts
+    }
+
+    if (message.type === 'result') {
+        const turnId = ensureTurnStarted(drafts, state)
+        const usage = usageFromObject(message.usage)
+        // Claude Agent SDK result usage is per completed ask/turn for the stream-json path we use,
+        // not a monotonic counter across the long-lived query. Emit it directly so summing
+        // normalized usage events gives the run total; do not diff against prior results.
+        if (usage)
+            drafts.push({ type: 'usage', turnId, actor: mainActor, payload: { usage } })
+        endOpenReasoning(drafts, state, turnId)
+        const interruptAccepted = state.interrupt.status === 'accepted' && state.interrupt.turnId === turnId
+        drafts.push({ type: 'turn.ended', turnId, actor: mainActor, payload: turnEndedPayload(message, interruptAccepted) })
+        ensureSessionIdle(drafts, state)
+        state.pendingWorkCallById.clear()
+        state.turnStarted = false
+        state.interrupt = { status: 'none' }
+        state.currentTurnId = undefined
+        state.currentMessageId = undefined
+        state.currentCompactionId = undefined
+        return drafts
+    }
+
+    return drafts
+}
+
+function mapStatusMessage(message: ClaudeStatusMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    if (message.status === 'compacting') {
+        const turnId = ensureTurnStarted(drafts, state)
+        if (state.currentCompactionId)
+            return drafts
+        state.currentCompactionId = message.uuid
+        drafts.push({ type: 'context.compaction.started', turnId, actor: mainActor, payload: { compactionId: state.currentCompactionId, trigger: 'unknown' } })
+        return drafts
+    }
+
+    if (message.compact_result === 'failed') {
+        const turnId = ensureTurnStarted(drafts, state)
+        const compactionId = state.currentCompactionId ?? message.uuid
+        drafts.push({
+            type: 'context.compaction.completed',
+            turnId,
+            actor: mainActor,
+            payload: {
+                compactionId,
+                trigger: 'unknown',
+                status: 'failed',
+                error: { message: message.compact_error ?? 'Claude compaction failed.' },
+            },
+        })
+        state.currentCompactionId = undefined
+    }
+
+    return drafts
+}
+
+function mapTaskStartedMessage(message: ClaudeTaskStartedMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    const turnId = ensureTurnStarted(drafts, state)
+    const actor = subagentActorFromTask({ subagentId: message.task_id, parentToolCallId: message.tool_use_id, name: message.subagent_type })
+    if (message.tool_use_id)
+        state.subagentByToolCallId.set(message.tool_use_id, actor)
+    drafts.push({
+        type: 'subagent.started',
+        turnId,
+        actor,
+        payload: removeUndefined({
+            ...subagentPayloadRef(actor),
+            description: message.description,
+        }),
+    })
+    return drafts
+}
+
+function mapTaskProgressMessage(message: ClaudeTaskProgressMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    const turnId = ensureTurnStarted(drafts, state)
+    const actor = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id, name: message.subagent_type }, state)
+    drafts.push({
+        type: 'subagent.progress',
+        turnId,
+        actor,
+        payload: removeUndefined({
+            ...subagentPayloadRef(actor),
+            summary: optionalNonEmpty(message.summary),
+            lastToolName: optionalNonEmpty(message.last_tool_name),
+            usage: usageFromTaskUsage(message.usage),
+        }),
+    })
+    return drafts
+}
+
+function mapTaskNotificationMessage(message: ClaudeTaskNotificationMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    const turnId = ensureTurnStarted(drafts, state)
+    const actor = subagentActorForTaskMessage({ subagentId: message.task_id, parentToolCallId: message.tool_use_id }, state)
+    drafts.push({
+        type: 'subagent.ended',
+        turnId,
+        actor,
+        payload: removeUndefined({
+            ...subagentPayloadRef(actor),
+            status: taskNotificationStatus(message.status),
+            summary: optionalNonEmpty(message.summary),
+            usage: message.usage ? usageFromTaskUsage(message.usage) : undefined,
+            error: message.status === 'failed' ? { message: optionalNonEmpty(message.summary) ?? `Subagent ${message.task_id} failed.` } : undefined,
+        }),
+    })
+    return drafts
+}
+
+function mapCompactBoundaryMessage(message: ClaudeCompactBoundaryMessage, state: ClaudeEventMapperState): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    const turnId = ensureTurnStarted(drafts, state)
+    const compactionId = state.currentCompactionId ?? message.uuid
+    drafts.push({
+        type: 'context.compaction.completed',
+        turnId,
+        actor: mainActor,
+        payload: removeUndefined({
+            compactionId,
+            trigger: message.compact_metadata.trigger,
+            status: 'completed' as const,
+            duration: message.compact_metadata.duration_ms,
+            inputTokensBefore: message.compact_metadata.pre_tokens,
+            inputTokensAfter: message.compact_metadata.post_tokens,
+        }),
+    })
+    state.currentCompactionId = undefined
+    return drafts
+}
+
+function mapAssistantContent(message: BetaMessage, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor | undefined, isMain: boolean): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    const streamedText = state.streamedTextByMessageId.has(message.id)
+    const streamedReasoning = state.streamedReasoningMessageIds.has(message.id)
+    for (const block of message.content) {
+        if (block.type === 'text' && !streamedText) {
+            drafts.push(withActor({ type: 'message.delta', turnId, payload: { messageId: message.id, role: 'assistant', delta: block.text } }, actor))
+        }
+        if (block.type === 'thinking' && !streamedReasoning) {
+            const reasoningId = ensureReasoningStarted(drafts, state, turnId, message.id, actor)
+            const text = optionalNonEmpty(block.thinking)
+            if (text)
+                drafts.push(withActor({ type: 'reasoning.summary.delta', turnId, payload: { reasoningId, text } }, actor))
+        }
+        if (block.type === 'tool_use') {
+            const toolName = normalizeToolName(block.name)
+            state.toolNameById.set(block.id, toolName)
+            if (isMain) {
+                const pendingWorkCall = pendingClaudeWorkCall(block.name, block.input)
+                if (pendingWorkCall)
+                    state.pendingWorkCallById.set(block.id, pendingWorkCall)
+            }
+            drafts.push(withActor({ type: 'tool.call.started', turnId, payload: { toolCallId: block.id, toolName, input: jsonInput(block.input) } }, actor))
+        }
+    }
+    return drafts
+}
+
+function mapUserContentBlock(block: UserContentBlock, message: ClaudeUserMessage, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor | undefined, isMain: boolean): AgentEventDraft[] {
+    if (block.type !== 'tool_result')
+        return []
+    const toolCallId = block.tool_use_id
+    const pendingWorkCall = state.pendingWorkCallById.get(toolCallId)
+    if (pendingWorkCall)
+        state.pendingWorkCallById.delete(toolCallId)
+
+    const text = textFromToolResultContent(block.content)
+    const output = { success: block.is_error !== true, content: text ? [{ type: 'text' as const, text }] : [] }
+    const drafts: AgentEventDraft[] = []
+    if (text)
+        drafts.push(withActor({ type: 'tool.output.delta', turnId, payload: { toolCallId, delta: text } }, actor))
+    drafts.push(withActor({
+        type: 'tool.call.completed',
+        turnId,
+        payload: removeUndefined({
+            toolCallId,
+            status: block.is_error === true ? 'failed' : 'completed',
+            output,
+            error: block.is_error === true ? { message: text || `Tool ${state.toolNameById.get(toolCallId) ?? toolCallId} failed.` } : undefined,
+        }),
+    }, actor))
+
+    if (!pendingWorkCall || block.is_error === true || !isMain)
+        return drafts
+
+    const observations = workObservationsFromClaudeResult(pendingWorkCall, message.tool_use_result)
+    if (observations.length > 0)
+        drafts.push({ type: 'work.observed', turnId, actor: mainActor, payload: { observations } })
+    return drafts
+}
+
+function pendingClaudeWorkCall(name: string, input: unknown): PendingClaudeWorkCall | undefined {
+    if (name === 'TaskCreate') {
+        const parsed = taskCreateWorkInputSchema.safeParse(input)
+        return parsed.success ? { kind: 'create', input: parsed.data } : undefined
+    }
+    if (name === 'TaskGet') {
+        const parsed = taskGetWorkInputSchema.safeParse(input)
+        return parsed.success ? { kind: 'get', input: parsed.data } : undefined
+    }
+    if (name === 'TaskUpdate') {
+        const parsed = taskUpdateWorkInputSchema.safeParse(input)
+        return parsed.success ? { kind: 'update', input: parsed.data } : undefined
+    }
+    if (name === 'TaskList') {
+        const parsed = taskListWorkInputSchema.safeParse(input)
+        return parsed.success ? { kind: 'list', input: parsed.data } : undefined
+    }
+    return undefined
+}
+
+function workObservationsFromClaudeResult(call: PendingClaudeWorkCall, structuredResult: unknown): AgentWorkObservation[] {
+    if (call.kind === 'create') {
+        const output = parseClaudeTaskResult({ value: structuredResult, toolName: 'TaskCreate', schema: taskCreateWorkOutputSchema })
+        return [{ kind: 'item_observed', item: { id: output.task.id, title: output.task.subject, status: 'pending' } }]
+    }
+    if (call.kind === 'get') {
+        const output = parseClaudeTaskResult({ value: structuredResult, toolName: 'TaskGet', schema: taskGetWorkOutputSchema })
+        return output.task
+            ? [{ kind: 'item_observed', item: { id: output.task.id, title: output.task.subject, status: output.task.status } }]
+            : [{ kind: 'item_removed', itemId: call.input.taskId }]
+    }
+    if (call.kind === 'list') {
+        const output = parseClaudeTaskResult({ value: structuredResult, toolName: 'TaskList', schema: taskListWorkOutputSchema })
+        return [{
+            kind: 'snapshot',
+            items: output.tasks.map(task => ({ id: task.id, title: task.subject, status: task.status })),
+        }]
+    }
+
+    const output = parseClaudeTaskResult({ value: structuredResult, toolName: 'TaskUpdate', schema: taskUpdateWorkOutputSchema })
+    if (!output.success)
+        return []
+
+    const observations: AgentWorkObservation[] = []
+    if (output.updatedFields.includes('subject') && call.input.subject)
+        observations.push({ kind: 'item_renamed', itemId: output.taskId, title: call.input.subject })
+    if (output.updatedFields.includes('status') && output.statusChange) {
+        if (output.statusChange.to === 'deleted')
+            observations.push({ kind: 'item_removed', itemId: output.taskId })
+        else observations.push({ kind: 'item_status_changed', itemId: output.taskId, status: output.statusChange.to })
+    }
+    return observations
+}
+
+function parseClaudeTaskResult<Output>({ value, toolName, schema }: { value: unknown, toolName: string, schema: z.ZodType<Output> }): Output {
+    const parsed = schema.safeParse(value)
+    if (parsed.success)
+        return parsed.data
+    throw new AgentProviderProtocolError({
+        message: `Claude ${toolName} returned missing or malformed structured output.`,
+        cause: parsed.error,
+    })
+}
+
+function mapStreamEvent(event: BetaRawMessageStreamEvent, state: ClaudeEventMapperState, turnId: string, actor: AgentEventActor | undefined): AgentEventDraft[] {
+    const drafts: AgentEventDraft[] = []
+    if (event.type === 'message_start') {
+        state.currentMessageId = event.message.id
+        if (actor)
+            state.actorByMessageId.set(event.message.id, actor)
+        ensureAssistantMessageStarted(drafts, state, event.message, turnId, actor)
+        return drafts
+    }
+
+    if (event.type === 'content_block_start') {
+        const messageId = currentMessageId(state)
+        const messageActor = actor ?? state.actorByMessageId.get(messageId)
+        state.contentBlockTypeByIndex.set(event.index, event.content_block.type)
+        if (event.content_block.type === 'thinking') {
+            state.streamedReasoningMessageIds.add(messageId)
+            ensureReasoningStarted(drafts, state, turnId, messageId, messageActor)
+        }
+        return drafts
+    }
+
+    if (event.type === 'content_block_stop') {
+        const messageId = currentMessageId(state)
+        const messageActor = actor ?? state.actorByMessageId.get(messageId)
+        const blockType = state.contentBlockTypeByIndex.get(event.index)
+        if (blockType === 'thinking')
+            endReasoning(drafts, state, turnId, messageId, state.streamedReasoningByMessageId.get(messageId), messageActor)
+        state.contentBlockTypeByIndex.delete(event.index)
+        return drafts
+    }
+
+    if (event.type === 'message_stop') {
+        const messageId = currentMessageId(state)
+        const messageActor = actor ?? state.actorByMessageId.get(messageId)
+        endAssistantMessageById(drafts, state, turnId, messageId, state.streamedTextByMessageId.get(messageId), messageActor)
+        state.actorByMessageId.delete(messageId)
+        state.currentMessageId = undefined
+        state.contentBlockTypeByIndex.clear()
+        return drafts
+    }
+
+    if (event.type !== 'content_block_delta')
+        return drafts
+
+    const messageId = currentMessageId(state)
+    const messageActor = actor ?? state.actorByMessageId.get(messageId)
+    const delta = event.delta
+    if (delta.type === 'thinking_delta') {
+        state.streamedReasoningMessageIds.add(messageId)
+        state.streamedReasoningByMessageId.set(messageId, `${state.streamedReasoningByMessageId.get(messageId) ?? ''}${delta.thinking}`)
+        const reasoningId = ensureReasoningStarted(drafts, state, turnId, messageId, messageActor)
+        if (delta.thinking)
+            drafts.push(withActor({ type: 'reasoning.summary.delta', turnId, payload: { reasoningId, text: delta.thinking } }, messageActor))
+    }
+    if (delta.type === 'text_delta') {
+        state.streamedTextByMessageId.set(messageId, `${state.streamedTextByMessageId.get(messageId) ?? ''}${delta.text}`)
+        drafts.push(withActor({ type: 'message.delta', turnId, payload: { messageId, role: 'assistant', delta: delta.text } }, messageActor))
+    }
+    return drafts
+}
+
+function ensureTurnStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperState): string {
+    if (state.turnStarted && state.currentTurnId)
+        return state.currentTurnId
+    state.turnStarted = true
+    state.interrupt = { status: 'none' }
+    state.currentTurnId = createRuntimeTurnId()
+    state.currentMessageId = undefined
+    state.contentBlockTypeByIndex.clear()
+    drafts.push({ type: 'turn.started', turnId: state.currentTurnId, actor: mainActor, payload: {} })
+    ensureSessionRunning(drafts, state)
+    return state.currentTurnId
+}
+
+function ensureSessionRunning(drafts: AgentEventDraft[], state: ClaudeEventMapperState): void {
+    if (state.sessionState === 'running')
+        return
+    state.sessionState = 'running'
+    drafts.push({ type: 'session.state.changed', payload: { state: 'running' } })
+}
+
+function ensureSessionIdle(drafts: AgentEventDraft[], state: ClaudeEventMapperState): void {
+    if (state.sessionState === 'idle')
+        return
+    state.sessionState = 'idle'
+    drafts.push({ type: 'session.state.changed', payload: { state: 'idle' } })
+}
+
+function ensureAssistantMessageStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperState, message: BetaMessage, turnId: string, actor: AgentEventActor | undefined): void {
+    state.currentMessageId = message.id
+    if (actor)
+        state.actorByMessageId.set(message.id, actor)
+    if (state.startedMessageIds.has(message.id))
+        return
+    state.startedMessageIds.add(message.id)
+    drafts.push(withActor({ type: 'message.started', turnId, payload: { messageId: message.id, role: 'assistant' } }, actor))
+}
+
+function currentMessageId(state: ClaudeEventMapperState): string {
+    if (state.currentMessageId)
+        return state.currentMessageId
+    throw new AgentProviderProtocolError({ message: 'Claude stream emitted content_block_delta before message_start.' })
+}
+
+function endAssistantMessage(drafts: AgentEventDraft[], state: ClaudeEventMapperState, message: BetaMessage, turnId: string, actor: AgentEventActor | undefined): void {
+    if (state.endedMessageIds.has(message.id))
+        return
+    endReasoning(drafts, state, turnId, message.id, thinkingFromAssistantContent(message.content), actor)
+    endAssistantMessageById(drafts, state, turnId, message.id, textFromAssistantContent(message.content), actor)
+}
+
+function endAssistantMessageById(drafts: AgentEventDraft[], state: ClaudeEventMapperState, turnId: string, messageId: string, text: string | undefined, actor: AgentEventActor | undefined): void {
+    if (state.endedMessageIds.has(messageId))
+        return
+    state.endedMessageIds.add(messageId)
+    drafts.push(withActor({ type: 'message.ended', turnId, payload: removeUndefined({ messageId, role: 'assistant' as const, text: optionalNonEmpty(text) }) }, actor))
+}
+
+function ensureReasoningStarted(drafts: AgentEventDraft[], state: ClaudeEventMapperState, turnId: string, messageId: string, actor: AgentEventActor | undefined): string {
+    const reasoningId = reasoningIdForMessage(messageId)
+    if (!state.startedReasoningIds.has(reasoningId)) {
+        state.startedReasoningIds.add(reasoningId)
+        drafts.push(withActor({ type: 'reasoning.started', turnId, payload: { reasoningId } }, actor))
+    }
+    return reasoningId
+}
+
+function endReasoning(drafts: AgentEventDraft[], state: ClaudeEventMapperState, turnId: string, messageId: string, summary: string | undefined, actor: AgentEventActor | undefined): void {
+    const reasoningId = reasoningIdForMessage(messageId)
+    if (!state.startedReasoningIds.has(reasoningId) || state.endedReasoningIds.has(reasoningId))
+        return
+    state.endedReasoningIds.add(reasoningId)
+    drafts.push(withActor({ type: 'reasoning.ended', turnId, payload: removeUndefined({ reasoningId, summary: optionalNonEmpty(summary) }) }, actor))
+}
+
+function endOpenReasoning(drafts: AgentEventDraft[], state: ClaudeEventMapperState, turnId: string): void {
+    for (const reasoningId of state.startedReasoningIds) {
+        if (!state.endedReasoningIds.has(reasoningId)) {
+            state.endedReasoningIds.add(reasoningId)
+            drafts.push({ type: 'reasoning.ended', turnId, actor: mainActor, payload: { reasoningId } })
+        }
+    }
+}
+
+function reasoningIdForMessage(messageId: string): string {
+    return `reasoning-${messageId}`
+}
+
+function turnEndedPayload(message: Extract<SDKMessage, { type: 'result' }>, interruptAccepted: boolean): Extract<AgentEventDraft, { type: 'turn.ended' }>['payload'] {
+    if (interruptAccepted && message.subtype === 'error_during_execution') {
+        return removeUndefined({
+            status: 'interrupted' as const,
+            reason: 'interrupted',
+            duration: message.duration_ms,
+        })
+    }
+
+    if (message.subtype === 'success' && message.is_error !== true) {
+        return removeUndefined({
+            status: 'completed' as const,
+            reason: message.stop_reason ?? message.subtype,
+            duration: message.duration_ms,
+        })
+    }
+
+    return removeUndefined({
+        status: 'failed' as const,
+        reason: message.stop_reason ?? message.subtype,
+        duration: message.duration_ms,
+        error: resultError(message),
+    })
+}
+
+function resultError(message: Extract<SDKMessage, { type: 'result' }>): AgentError {
+    const errors = 'errors' in message && Array.isArray(message.errors) ? message.errors : []
+    return {
+        message: errors.length > 0 ? errors.join('\n') : `Claude result ended with ${message.subtype}.`,
+        code: message.subtype,
+    }
+}
+
+function shouldEndAssistantSnapshot(message: BetaMessage, state: ClaudeEventMapperState, actor: ClaudeSubagentActor | undefined): boolean {
+    return actor !== undefined
+        && !state.streamedTextByMessageId.has(message.id)
+        && !state.streamedReasoningMessageIds.has(message.id)
+}
+
+function actorFromParentToolUseId(parentToolUseId: string | null, state: ClaudeEventMapperState): ClaudeSubagentActor | undefined {
+    return parentToolUseId ? state.subagentByToolCallId.get(parentToolUseId) : undefined
+}
+
+function subagentActorForTaskMessage(input: { subagentId: string, parentToolCallId?: string, name?: string }, state: ClaudeEventMapperState): ClaudeSubagentActor {
+    const existing = input.parentToolCallId ? state.subagentByToolCallId.get(input.parentToolCallId) : undefined
+    return existing ?? subagentActorFromTask(input)
+}
+
+function subagentActorFromTask(input: { subagentId: string, parentToolCallId?: string, name?: string }): ClaudeSubagentActor {
+    return removeUndefined({
+        type: 'subagent' as const,
+        actorId: input.subagentId,
+        subagentId: input.subagentId,
+        parentActorId: 'main',
+        origin: input.parentToolCallId ? { type: 'tool_call' as const, toolCallId: input.parentToolCallId } : { type: 'provider_task' as const, taskId: input.subagentId },
+        parentToolCallId: input.parentToolCallId,
+        name: input.name,
+    })
+}
+
+function subagentPayloadRef(actor: ClaudeSubagentActor): Pick<ClaudeSubagentActor, '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 subagentUserContentEvents(input: { messageId: string, content: UserContentBlock[], turnId: string, actor: ClaudeSubagentActor }): AgentEventDraft[] {
+    const text = input.content.map(block => block.type === 'text' ? block.text : '').join('')
+    return text ? subagentUserMessageEvents({ messageId: input.messageId, text, turnId: input.turnId, actor: input.actor }) : []
+}
+
+function subagentUserMessageEvents(input: { messageId: string, text: string, turnId: string, actor: ClaudeSubagentActor }): AgentEventDraft[] {
+    return [
+        withActor({ type: 'message.started', turnId: input.turnId, payload: { messageId: input.messageId, role: 'user' } }, input.actor),
+        withActor({ type: 'message.delta', turnId: input.turnId, payload: { messageId: input.messageId, role: 'user', delta: input.text } }, input.actor),
+        withActor({ type: 'message.ended', turnId: input.turnId, payload: { messageId: input.messageId, role: 'user', text: input.text } }, input.actor),
+    ]
+}
+
+function taskNotificationStatus(status: ClaudeTaskNotificationMessage['status']): 'completed' | 'failed' | 'cancelled' {
+    if (status === 'completed')
+        return 'completed'
+    if (status === 'failed')
+        return 'failed'
+    return 'cancelled'
+}
+
+function usageFromTaskUsage(usage: ClaudeTaskProgressMessage['usage']): AgentUsage {
+    return { totalTokens: usage.total_tokens }
+}
+
+function withActor(draft: ClaudeUnownedTurnEventDraft, actor: AgentEventActor | undefined): AgentEventDraft {
+    return { ...draft, actor: actor ?? mainActor }
+}
+
+const CLAUDE_RUNTIME_TOOL_PREFIX = `mcp__${CLAUDE_AGENT_TOOL_SERVER}__`
+
+function normalizeToolName(name: string): string {
+    // Our runtime tools arrive as mcp__coding_agent__<tool>; strip the prefix so they match Codex.
+    const local = name.startsWith(CLAUDE_RUNTIME_TOOL_PREFIX) ? name.slice(CLAUDE_RUNTIME_TOOL_PREFIX.length) : name
+    return canonicalToolName(local)
+}
+
+function usageFromObject(value: BetaUsage | undefined): AgentUsage | undefined {
+    if (!value)
+        return undefined
+    return removeUndefined({
+        inputTokens: value.input_tokens,
+        outputTokens: value.output_tokens,
+        cacheReadTokens: value.cache_read_input_tokens ?? undefined,
+        cacheWriteTokens: value.cache_creation_input_tokens ?? undefined,
+        totalTokens: value.input_tokens + value.output_tokens + (value.cache_read_input_tokens ?? 0) + (value.cache_creation_input_tokens ?? 0),
+    })
+}
+
+function textFromAssistantContent(content: BetaMessage['content']): string | undefined {
+    const text = content.map(block => block.type === 'text' ? block.text : '').join('')
+    return text || undefined
+}
+
+function thinkingFromAssistantContent(content: BetaMessage['content']): string | undefined {
+    const text = content.map(block => block.type === 'thinking' ? block.thinking : '').join('')
+    return text || undefined
+}
+
+function textFromToolResultContent(content: UserToolResultBlock['content']): string | undefined {
+    if (!content)
+        return undefined
+    if (typeof content === 'string')
+        return content
+    const text = content.map(block => block.type === 'text' ? block.text : '').join('\n')
+    return text || undefined
+}
+
+function jsonInput(value: unknown): JsonValue {
+    const parsed = jsonValueSchema.safeParse(value)
+    if (parsed.success)
+        return parsed.data
+    return {}
+}