@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.3

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

@@ -1,15 +1,17 @@
-import type { AgentError, AgentEventActor, AgentMessageRole, AgentSubagentStatus, AgentToolCallStatus, AgentToolContent, AgentToolResult, AgentTurnEndStatus, AgentUsage, JsonObject, JsonValue } from '../../protocol'
+import type { AgentContextSnapshot, AgentError, AgentEventActor, AgentMessageRole, AgentSubagentStatus, AgentToolCallStatus, AgentToolContent, AgentToolResult, AgentTurnEndStatus, AgentUsage, AgentUsageAccounting, 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 { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
 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 { jsonToolContent, mcpToolContent, ownJsonSlot } from '../mcp-tool-content'
 import { optionalNonEmpty, removeUndefined } from '../normalize'
+import { stripSessionContext } from '../session-context'
 import { isCodexServerNotification } from './codex-json-rpc-client'
 
 export type CodexNotification = CodexServerNotification
@@ -26,6 +28,7 @@ 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 CodexMcpToolCompletedItem = Extract<CodexCompletedItem, { type: 'mcpToolCall' }>
 type CodexCollabAgentToolCompletedItem = Extract<CodexCompletedItem, { type: 'collabAgentToolCall' }>
 type CodexCollabAgentToolStartedItem = Extract<CodexStartedItem, { type: 'collabAgentToolCall' }>
 type CodexSubAgentActivityCompletedItem = Extract<CodexCompletedItem, { type: 'subAgentActivity' }>
@@ -36,6 +39,8 @@ 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 CodexMainTurnState = { status: 'closed' } | { status: 'open', turnId: string }
+type CodexContextSnapshotBaseline = { status: 'empty' } | { status: 'reported', snapshot: AgentContextSnapshot }
 type CodexTurnEventDraft = Extract<AgentEventDraft, { turnId: string }>
 type CodexUnownedTurnEventDraft = CodexTurnEventDraft extends infer Draft
     ? Draft extends CodexTurnEventDraft
@@ -44,6 +49,9 @@ type CodexUnownedTurnEventDraft = CodexTurnEventDraft extends infer Draft
     : never
 
 const mainActor = { type: 'main', actorId: 'main' } satisfies AgentEventActor
+// Codex's own remaining-context formula (codex-rs `protocol.rs` / `tui/token_usage.rs`, 0.153.4)
+// subtracts a fixed 12,000-token baseline from both the used count and the capacity.
+const CODEX_CONTEXT_BASELINE_TOKENS = 12_000
 
 export interface CodexEventMapperState {
     readonly endedSubagentIds: Set<string>
@@ -56,11 +64,37 @@ export interface CodexEventMapperState {
     readonly startedReasoningIds: Set<string>
     readonly reasoningSummaryById: Map<string, Map<number, string>>
     readonly promptCommandByClientUserMessageId: Map<string, CodexPromptCommandRef>
+    readonly seenMainTurnIds: Set<string>
+    readonly openContextCompactionIds: Set<string>
+    readonly closedContextCompactionIds: Set<string>
+    currentMainTurn: CodexMainTurnState
+    contextSnapshotBaseline: CodexContextSnapshotBaseline
     mainThreadId?: string
+    // Usage accounting scope owned by this run; see codexUsageAccounting.
+    readonly usageScopeInstanceId: string
+    readonly usageAccountingByThreadId: Map<string, { total: string, usage: AgentUsage }>
 }
 
 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() }
+    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(),
+        seenMainTurnIds: new Set(),
+        openContextCompactionIds: new Set(),
+        closedContextCompactionIds: new Set(),
+        currentMainTurn: { status: 'closed' },
+        contextSnapshotBaseline: { status: 'empty' },
+        usageScopeInstanceId: randomUUID(),
+        usageAccountingByThreadId: new Map(),
+    }
 }
 
 export function codexNotificationFromMessage(message: CodexJsonRpcMessage): CodexNotification | null {
@@ -79,13 +113,14 @@ export function mapCodexNotification(notification: CodexNotification, state: Cod
             cacheThreadMetadata(notification.params.thread, state)
             return []
         case 'turn/started':
-            state.mainThreadId ??= notification.params.threadId
             state.startedTurnIds.add(notification.params.turn.id)
+            observeMainTurnStarted({ threadId: notification.params.threadId, turnId: notification.params.turn.id, state })
             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)
+            observeMainTurnCompleted({ threadId: notification.params.threadId, turnId: notification.params.turn.id, 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 }),
@@ -95,21 +130,21 @@ export function mapCodexNotification(notification: CodexNotification, state: Cod
             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,
-                accounting: {
-                    observationId: createHash('sha256').update(notification.params.threadId).update(JSON.stringify(notification.params.tokenUsage.total)).digest('hex'),
-                    mode: 'cumulative',
-                    scopeId: notification.params.threadId,
-                    includesChildren: false,
-                    usage: {
-                        ...usageFromCounts(notification.params.tokenUsage.total),
-                        inputTokens: Math.max(0, notification.params.tokenUsage.total.inputTokens - notification.params.tokenUsage.total.cachedInputTokens),
-                    },
-                },
-            } }, threadId: notification.params.threadId, state })
+            const usageDrafts = usage
+                ? emitOrBufferByThread({ draft: { type: 'usage', turnId: notification.params.turnId, payload: {
+                        usage,
+                        accounting: codexUsageAccounting(notification.params.threadId, notification.params.tokenUsage, state),
+                    } }, threadId: notification.params.threadId, state })
+                : []
+            return [
+                ...usageDrafts,
+                ...mapContextSnapshotFromTokenUsage({
+                    threadId: notification.params.threadId,
+                    turnId: notification.params.turnId,
+                    tokenUsage: notification.params.tokenUsage,
+                    state,
+                }),
+            ]
         }
         case 'turn/plan/updated':
             if (!state.startedTurnIds.has(notification.params.turnId) || notification.params.threadId !== state.mainThreadId)
@@ -134,7 +169,9 @@ export function mapCodexNotification(notification: CodexNotification, state: Cod
                 return []
             if (!notification.params.willRetry)
                 state.turnErrorsById.set(notification.params.turnId, agentErrorFromCodexTurnError(notification.params.error))
-            return []
+            return codexErrorCode(notification.params.error.codexErrorInfo) === 'contextWindowExceeded'
+                ? reportContextSnapshot({ threadId: notification.params.threadId, turnId: notification.params.turnId, snapshot: { status: 'unknown' }, state })
+                : []
         case 'item/agentMessage/delta':
             if (!state.startedTurnIds.has(notification.params.turnId))
                 return []
@@ -157,6 +194,10 @@ export function mapCodexNotification(notification: CodexNotification, state: Cod
             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/mcpToolCall/progress':
+            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.message } }, threadId: notification.params.threadId, state })
         case 'item/started':
             if (!state.startedTurnIds.has(notification.params.turnId))
                 return []
@@ -210,27 +251,55 @@ function mapItemStarted({ turnId, threadId, item, state }: { turnId: string, thr
     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')
+    if (item.type === 'contextCompaction') {
+        observeContextCompactionStarted({ threadId, turnId, compactionId: item.id, state })
         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 {
+    const toolName = toolNameForItem(item)
+    if (!toolName)
+        return undefined
+
+    if (item.type === 'commandExecution')
+        return { toolName, input: toJsonObject({ command: Array.isArray(item.command) ? item.command.join(' ') : String(item.command ?? ''), cwd: item.cwd }) }
+    if (item.type === 'webSearch')
+        return { toolName, input: toJsonObject({ query: optionalNonEmpty(item.query) }) }
+    if (item.type === 'fileChange')
+        return { toolName, input: jsonInput({ files: item.changes.map(change => removeUndefined({ path: change.path, kind: change.kind?.type })) }) }
+    if (item.type === 'imageView')
+        return { toolName, input: toJsonObject({ path: item.path }) }
+    if (item.type === 'imageGeneration')
+        return { toolName, input: toJsonObject({ revisedPrompt: optionalNonEmpty(item.revisedPrompt) }) }
+    if (item.type === 'dynamicToolCall')
+        return { toolName, input: jsonInput(item.arguments) }
+    if (item.type === 'mcpToolCall')
+        return { toolName, input: jsonInput(item.arguments) }
+    if (item.type === 'collabAgentToolCall')
+        return { toolName, input: collabToolInput(item) }
+    return undefined
+}
+
+function toolNameForItem(item: CodexStartedItem | CodexCompletedItem): string | 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 }) }
+        return CANONICAL_TOOL.bash
     if (item.type === 'webSearch')
-        return { toolName: CANONICAL_TOOL.webSearch, input: toJsonObject({ query: optionalNonEmpty(item.query) }) }
+        return CANONICAL_TOOL.webSearch
     if (item.type === 'fileChange')
-        return { toolName: CANONICAL_TOOL.edit, input: jsonInput({ files: item.changes.map(change => removeUndefined({ path: change.path, kind: change.kind?.type })) }) }
+        return CANONICAL_TOOL.edit
     if (item.type === 'imageView')
-        return { toolName: CANONICAL_TOOL.viewImage, input: toJsonObject({ path: item.path }) }
+        return CANONICAL_TOOL.viewImage
     if (item.type === 'imageGeneration')
-        return { toolName: CANONICAL_TOOL.imageGeneration, input: toJsonObject({ revisedPrompt: optionalNonEmpty(item.revisedPrompt) }) }
+        return CANONICAL_TOOL.imageGeneration
     if (item.type === 'dynamicToolCall')
-        return { toolName: item.tool, input: jsonInput(item.arguments) }
+        return item.tool
+    if (item.type === 'mcpToolCall')
+        return `mcp:${item.server}/${item.tool}`
     if (item.type === 'collabAgentToolCall')
-        return { toolName: item.tool, input: collabToolInput(item) }
+        return item.tool
     return undefined
 }
 
@@ -259,8 +328,10 @@ function mapItemCompleted({ turnId, threadId, item, state }: { turnId: string, t
     if (item.type === 'subAgentActivity')
         return mapSubAgentActivityCompleted({ turnId, threadId, item, state })
 
-    if (item.type === 'contextCompaction')
+    if (item.type === 'contextCompaction') {
+        observeContextCompactionCompleted({ threadId, turnId, compactionId: item.id, state })
         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 })
@@ -310,26 +381,54 @@ function messageForItem(item: CodexStartedItem | CodexCompletedItem, state: Code
     return removeUndefined({ role, commandId: promptCommand?.commandId })
 }
 
-function toolCallCompletion(item: CodexCompletedItem): { status: AgentToolCallStatus, output?: AgentToolResult, error?: AgentError } | undefined {
+function toolCallCompletion(item: CodexCompletedItem): { toolName: string, status: AgentToolCallStatus, output?: AgentToolResult, error?: AgentError } | undefined {
+    const toolName = toolNameForItem(item)
+    if (!toolName)
+        return undefined
+
     if (item.type === 'webSearch')
-        return { status: 'completed', output: webSearchResult(item) }
+        return { toolName, 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 }
+        return { toolName, 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 }] } }
+        return { toolName, 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) }
+        return { toolName, 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'
+        const status = item.status === 'declined'
+            ? 'cancelled'
+            : item.status !== 'completed' || (item.exitCode != null && item.exitCode !== 0) ? 'failed' : 'completed'
         const error = 'error' in item && typeof item.error === 'string'
             ? { message: item.error }
-            : status === 'failed' ? { message: `Command exited with code ${item.exitCode}.` } : undefined
-        return { status, output: commandExecutionResult(item, status), error }
+            : status === 'failed'
+                ? { message: item.exitCode != null && item.exitCode !== 0
+                        ? `Command exited with code ${item.exitCode}.`
+                        : item.status === 'inProgress' ? 'Command completion status was inconsistent.' : 'Command execution failed.' }
+                : undefined
+        return { toolName, status, output: commandExecutionResult(item, status), error }
     }
     if (item.type === 'dynamicToolCall')
-        return { status: item.success === false ? 'failed' : 'completed', output: dynamicToolResult(item) }
+        return { toolName, status: item.success === false ? 'failed' : 'completed', output: dynamicToolResult(item) }
+    if (item.type === 'mcpToolCall') {
+        if (item.status === 'inProgress') {
+            return {
+                toolName,
+                status: 'failed',
+                output: mcpToolResult(item, 'failed'),
+                error: { message: 'MCP tool result could not be determined because completion status was inconsistent.' },
+            }
+        }
+
+        const status = item.status
+        return {
+            toolName,
+            status,
+            output: mcpToolResult(item, status),
+            error: status === 'failed' ? mcpToolError(item.error?.message) : undefined,
+        }
+    }
     return undefined
 }
 
@@ -373,9 +472,18 @@ function imageGenerationResult(item: CodexImageGenerationItem): AgentToolResult
     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') }] }
+    const content: AgentToolContent[] = lines.length > 0 ? [{ type: 'text', text: lines.join('\n') }] : []
+    if (item.result !== '')
+        content.push({ type: 'image', data: item.result, mimeType: 'image/png' })
+    const failure = ownJsonSlot(item, 'failure')
+    if (item.result === '' || failure !== undefined || item.transparentBackground !== undefined) {
+        content.push(jsonToolContent({
+            ...(item.result === '' ? { result: '' } : {}),
+            ...(failure !== undefined ? { failure } : {}),
+            ...(item.transparentBackground !== undefined ? { transparentBackground: item.transparentBackground } : {}),
+        }))
+    }
+    return { success: item.status !== 'failed', content }
 }
 
 function messageEndedText(item: CodexCompletedItem): string | undefined {
@@ -391,17 +499,17 @@ function messageEndedText(item: CodexCompletedItem): string | undefined {
 function userMessageText(item: CodexUserMessageItem): string | undefined {
     const parts: string[] = []
     for (const entry of item.content) {
-        if (entry.type === 'text')
+        if (entry.type === 'text' && typeof entry.text === 'string')
             parts.push(entry.text)
     }
-    return optionalNonEmpty(stripAuthorContext(parts.join('\n')))
+    return optionalNonEmpty(stripSessionContext(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 {
+function commandExecutionResult(item: Extract<CodexCompletedItem, { type: 'commandExecution' }>, status: AgentToolCallStatus): AgentToolResult | undefined {
     // Stdout is content, not a label: whitespace and an explicitly empty
     // successful output must survive normalization into the complete step.
     // Native build_command_execution_end_item encodes empty captured output as
@@ -414,6 +522,33 @@ function commandExecutionResult(item: Extract<CodexCompletedItem, { type: 'comma
     return { success: status === 'completed', content: [{ type: 'text', text }] }
 }
 
+function mcpToolResult(item: CodexMcpToolCompletedItem, status: 'completed' | 'failed'): AgentToolResult | undefined {
+    if (item.result === null || item.result === undefined)
+        return undefined
+
+    if (typeof item.result !== 'object' || Array.isArray(item.result)) {
+        const parsed = jsonValueSchema.safeParse(item.result)
+        return parsed.success
+            ? { success: status === 'completed', content: [jsonToolContent(parsed.data)] }
+            : undefined
+    }
+
+    const content: AgentToolContent[] = []
+    const resultContent = ownJsonSlot(item.result, 'content')
+    if (resultContent !== undefined) {
+        if (Array.isArray(resultContent))
+            content.push(...resultContent.map(mcpToolContent))
+        else
+            content.push(mcpToolContent(resultContent))
+    }
+    const structuredContent = ownJsonSlot(item.result, 'structuredContent')
+    return removeUndefined({ success: status === 'completed', content, structuredContent })
+}
+
+function mcpToolError(value: unknown): AgentError {
+    return { message: typeof value === 'string' ? value : 'MCP tool call failed.' }
+}
+
 function dynamicToolResult(item: CodexDynamicToolCompletedItem): AgentToolResult | undefined {
     if (!item.contentItems)
         return undefined
@@ -428,14 +563,18 @@ 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 }
+    if (item.type === 'inputAudio') {
+        const dataUrl = /^data:([^;,]+);base64,(.+)$/s.exec(item.audioUrl)
+        return dataUrl
+            ? { type: 'audio', mimeType: dataUrl[1]!, data: dataUrl[2]! }
+            : jsonToolContent({ type: 'audio', uri: 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 }
+    return { type: 'image', uri: item.imageUrl }
 }
 
 function mapCollabAgentToolCompleted({ turnId, threadId, item, mapperState }: { turnId: string, threadId: string, item: CodexCollabAgentToolCompletedItem, mapperState: CodexEventMapperState }): AgentEventDraft[] {
@@ -445,6 +584,7 @@ function mapCollabAgentToolCompleted({ turnId, threadId, item, mapperState }: {
             turnId,
             payload: removeUndefined({
                 toolCallId: item.id,
+                toolName: item.tool,
                 status: item.status === 'failed' ? 'failed' as const : 'completed' as const,
                 error: item.status === 'failed' ? { message: `Codex ${item.tool} failed.` } : undefined,
             }),
@@ -454,23 +594,33 @@ function mapCollabAgentToolCompleted({ turnId, threadId, item, mapperState }: {
     })
 
     if (item.tool === 'spawnAgent') {
-        const subagentId = item.receiverThreadIds.at(0)
-        if (!subagentId || item.status === 'failed' || mapperState.subagentByThreadId.has(subagentId))
+        if (item.status === 'failed')
             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))
+        for (const subagentId of new Set(item.receiverThreadIds)) {
+            if (!subagentId || mapperState.subagentByThreadId.has(subagentId))
+                continue
+
+            const actor = subagentActorFromCollabItem({
+                subagentId,
+                parentThreadId: item.senderThreadId,
+                parentToolCallId: item.id,
+                name: mapperState.subagentNameByThreadId.get(subagentId),
+                state: mapperState,
+            })
+            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
     }
 
@@ -507,14 +657,16 @@ function mapSubAgentActivityCompleted(input: { turnId: string, threadId: string,
 
         const actor = subagentActorFromCollabItem({
             subagentId: item.agentThreadId,
+            parentThreadId: threadId,
             parentToolCallId: item.id,
             name: item.agentPath,
+            state,
         })
         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 }),
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, toolName: 'spawnAgent', status: 'completed' } }, threadId, state }),
             {
                 type: 'subagent.started',
                 turnId,
@@ -528,7 +680,7 @@ function mapSubAgentActivityCompleted(input: { turnId: string, threadId: string,
     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 }),
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, toolName: 'sendInput', status: 'completed' } }, threadId, state }),
         ]
     }
 
@@ -624,7 +776,7 @@ function actorForThread(threadId: string, state: CodexEventMapperState): AgentEv
     const subagentActor = state.subagentByThreadId.get(threadId)
     if (subagentActor)
         return subagentActor
-    return state.mainThreadId === undefined || threadId === state.mainThreadId ? mainActor : undefined
+    return threadId === state.mainThreadId ? mainActor : undefined
 }
 
 function flushPendingDrafts(threadId: string, state: CodexEventMapperState): AgentEventDraft[] {
@@ -670,12 +822,18 @@ function codexSubagentDisplayName(thread: CodexThreadMetadata): string | undefin
     return nickname ?? role
 }
 
-function subagentActorFromCollabItem(input: { subagentId: string, parentToolCallId: string, name?: string }): CodexSubagentRef {
+function subagentActorFromCollabItem(input: {
+    subagentId: string
+    parentThreadId: string
+    parentToolCallId: string
+    name?: string
+    state: CodexEventMapperState
+}): CodexSubagentRef {
     return removeUndefined({
         type: 'subagent' as const,
         actorId: input.subagentId,
         subagentId: input.subagentId,
-        parentActorId: 'main',
+        parentActorId: input.parentThreadId === input.state.mainThreadId ? 'main' : input.parentThreadId,
         origin: { type: 'tool_call' as const, toolCallId: input.parentToolCallId },
         parentToolCallId: input.parentToolCallId,
         name: input.name,
@@ -703,10 +861,169 @@ function collabToolInput(item: CodexCollabAgentToolStartedItem): JsonObject {
     })
 }
 
+function observeMainTurnStarted({ threadId, turnId, state }: { threadId: string, turnId: string, state: CodexEventMapperState }): void {
+    if (threadId !== state.mainThreadId || state.seenMainTurnIds.has(turnId))
+        return
+
+    state.seenMainTurnIds.add(turnId)
+    state.currentMainTurn = { status: 'open', turnId }
+    state.openContextCompactionIds.clear()
+    state.closedContextCompactionIds.clear()
+    invalidateContextSnapshotBaseline(state)
+}
+
+function observeMainTurnCompleted({ threadId, turnId, state }: { threadId: string, turnId: string, state: CodexEventMapperState }): void {
+    if (!isCurrentOpenMainTurn({ threadId, turnId, state }))
+        return
+
+    state.currentMainTurn = { status: 'closed' }
+    state.openContextCompactionIds.clear()
+    state.closedContextCompactionIds.clear()
+}
+
+function observeContextCompactionStarted({ threadId, turnId, compactionId, state }: { threadId: string, turnId: string, compactionId: string, state: CodexEventMapperState }): void {
+    if (!isCurrentOpenMainTurn({ threadId, turnId, state })
+        || state.openContextCompactionIds.has(compactionId)
+        || state.closedContextCompactionIds.has(compactionId)) {
+        return
+    }
+
+    state.openContextCompactionIds.add(compactionId)
+    invalidateContextSnapshotBaseline(state)
+}
+
+function observeContextCompactionCompleted({ threadId, turnId, compactionId, state }: { threadId: string, turnId: string, compactionId: string, state: CodexEventMapperState }): void {
+    if (!isCurrentOpenMainTurn({ threadId, turnId, state }) || state.closedContextCompactionIds.has(compactionId))
+        return
+
+    state.openContextCompactionIds.delete(compactionId)
+    state.closedContextCompactionIds.add(compactionId)
+    invalidateContextSnapshotBaseline(state)
+}
+
+function mapContextSnapshotFromTokenUsage({ threadId, turnId, tokenUsage, state }: { threadId: string, turnId: string, tokenUsage: CodexTokenUsage, state: CodexEventMapperState }): AgentEventDraft[] {
+    if (state.openContextCompactionIds.size > 0)
+        return []
+
+    return reportContextSnapshot({
+        threadId,
+        turnId,
+        snapshot: contextSnapshotFromTokenUsage(tokenUsage),
+        state,
+    })
+}
+
+function contextSnapshotFromTokenUsage(tokenUsage: CodexTokenUsage): AgentContextSnapshot {
+    const { last } = tokenUsage
+    if (!Number.isSafeInteger(last.totalTokens) || last.totalTokens < 0
+        || (last.inputTokens === 0 && last.outputTokens === 0)) {
+        return { status: 'unknown' }
+    }
+
+    const capacityTokens = tokenUsage.modelContextWindow
+    if (!Number.isSafeInteger(capacityTokens) || capacityTokens === null || capacityTokens === undefined || capacityTokens <= 0)
+        return { status: 'observed', usedTokens: last.totalTokens, window: { status: 'unknown' } }
+
+    return {
+        status: 'observed',
+        usedTokens: last.totalTokens,
+        window: {
+            status: 'known',
+            capacityTokens,
+            remainingPercent: remainingContextPercent({ usedTokens: last.totalTokens, capacityTokens }),
+        },
+    }
+}
+
+function remainingContextPercent({ usedTokens, capacityTokens }: { usedTokens: number, capacityTokens: number }): number {
+    if (capacityTokens <= CODEX_CONTEXT_BASELINE_TOKENS)
+        return 0
+
+    const usableTokens = capacityTokens - CODEX_CONTEXT_BASELINE_TOKENS
+    const usedUsableTokens = Math.max(usedTokens - CODEX_CONTEXT_BASELINE_TOKENS, 0)
+    const remainingTokens = Math.max(usableTokens - usedUsableTokens, 0)
+    return Math.round(Math.min(Math.max(100 * remainingTokens / usableTokens, 0), 100))
+}
+
+function reportContextSnapshot({ threadId, turnId, snapshot, state }: { threadId: string, turnId: string, snapshot: AgentContextSnapshot, state: CodexEventMapperState }): AgentEventDraft[] {
+    if (!isCurrentOpenMainTurn({ threadId, turnId, state })
+        || !state.startedTurnIds.has(turnId)
+        || state.openContextCompactionIds.size > 0
+        || contextSnapshotMatchesBaseline(snapshot, state.contextSnapshotBaseline)) {
+        return []
+    }
+
+    state.contextSnapshotBaseline = { status: 'reported', snapshot }
+    return emitOrBufferByThread({
+        draft: { type: 'context.updated', turnId, payload: { snapshot } },
+        threadId,
+        state,
+    })
+}
+
+function isCurrentOpenMainTurn({ threadId, turnId, state }: { threadId: string, turnId: string, state: CodexEventMapperState }): boolean {
+    return threadId === state.mainThreadId
+        && state.currentMainTurn.status === 'open'
+        && state.currentMainTurn.turnId === turnId
+}
+
+function contextSnapshotMatchesBaseline(snapshot: AgentContextSnapshot, baseline: CodexContextSnapshotBaseline): boolean {
+    if (baseline.status === 'empty')
+        return snapshot.status === 'unknown'
+    if (snapshot.status !== baseline.snapshot.status)
+        return false
+    if (snapshot.status === 'unknown' || baseline.snapshot.status === 'unknown')
+        return true
+    if (snapshot.usedTokens !== baseline.snapshot.usedTokens || snapshot.window.status !== baseline.snapshot.window.status)
+        return false
+    if (snapshot.window.status === 'unknown' || baseline.snapshot.window.status === 'unknown')
+        return true
+    return snapshot.window.capacityTokens === baseline.snapshot.window.capacityTokens
+        && snapshot.window.remainingPercent === baseline.snapshot.window.remainingPercent
+}
+
+function invalidateContextSnapshotBaseline(state: CodexEventMapperState): void {
+    state.contextSnapshotBaseline = { status: 'empty' }
+}
+
 function usageFromTokenUsage(value: CodexTokenUsage | undefined): AgentUsage | undefined {
     return value ? usageFromCounts(value.last) : undefined
 }
 
+// Codex reports `total` for the thread loaded in one app-server, and whether a resumed thread
+// restores it depends on the release: 0.153.4 restarts it at zero, 0.155.0 restores it. Accounting
+// therefore sums each model call's `last` usage, once per distinct `total`, in a scope owned by this
+// run. A resumed run opens a new scope, so a checkpoint never regresses or counts a call twice.
+function codexUsageAccounting(threadId: string, tokenUsage: CodexTokenUsage, state: CodexEventMapperState): AgentUsageAccounting {
+    const scopeId = `${threadId}:${state.usageScopeInstanceId}`
+    const total = JSON.stringify(tokenUsage.total)
+    const previous = state.usageAccountingByThreadId.get(threadId)
+    let usage = previous?.usage ?? {}
+    if (previous?.total !== total) {
+        usage = addUsage(usage, {
+            ...usageFromCounts(tokenUsage.last),
+            inputTokens: Math.max(0, tokenUsage.last.inputTokens - tokenUsage.last.cachedInputTokens),
+        })
+        state.usageAccountingByThreadId.set(threadId, { total, usage })
+    }
+    return {
+        observationId: createHash('sha256').update(scopeId).update(JSON.stringify(usage)).digest('hex'),
+        mode: 'cumulative',
+        scopeId,
+        includesChildren: false,
+        usage,
+    }
+}
+
+function addUsage(accumulated: AgentUsage, call: AgentUsage): AgentUsage {
+    const sum: AgentUsage = { ...accumulated }
+    for (const [key, value] of Object.entries(call) as [keyof AgentUsage, number | undefined][]) {
+        if (value !== undefined)
+            sum[key] = (sum[key] ?? 0) + value
+    }
+    return sum
+}
+
 function usageFromCounts(value: CodexTokenCounts): AgentUsage {
     return removeUndefined({
         inputTokens: value.inputTokens,