Skip to content
171 changes: 171 additions & 0 deletions src/main/codex/codex-structured-item-translation.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
import { describe, expect, it } from 'vitest'
import { agentJournalItemKey } from '../../shared/agent-session-journal-item-key'
import {
codexItemBody,
codexItemIdentity,
codexMessageBlocks,
CodexTurnOrdinals,
isCodexMessageItemType,
readCodexThreadItem,
type CodexThreadItem
} from './codex-structured-item-translation'

const THREAD_ID = 'thread-abc'
const TURN_ID = 'turn-1'

/**
* Captured from a live `codex app-server` turn: Codex numbers items in arrival
* order and includes the command it ran.
*/
const LIVE_TURN: CodexThreadItem[] = [
{ type: 'userMessage', id: 'item-0', content: [{ type: 'text', text: 'list the files' }] },
{ type: 'agentMessage', id: 'item-1', text: 'Let me look.' },
{
type: 'commandExecution',
id: 'item-2',
command: 'ls',
cwd: '/tmp',
status: 'completed',
exitCode: 0,
aggregatedOutput: 'a\nb\n'
},
{ type: 'agentMessage', id: 'item-3', text: 'Two files.' }
]

/**
* The SAME turn read back after `thread/resume`: ids are renumbered from 1 and
* the command execution is gone entirely, because Codex does not persist it.
*/
const RESUMED_TURN: CodexThreadItem[] = [
{ type: 'userMessage', id: 'item-1', content: [{ type: 'text', text: 'list the files' }] },
{ type: 'agentMessage', id: 'item-2', text: 'Let me look.' },
{ type: 'agentMessage', id: 'item-3', text: 'Two files.' }
]

function keysFor(items: CodexThreadItem[]): string[] {
const ordinals = new CodexTurnOrdinals()
return items
.filter((item) => isCodexMessageItemType(item.type))
.map((item) =>
agentJournalItemKey(
codexItemIdentity({ threadId: THREAD_ID, turnId: TURN_ID, item, ordinals })
)
)
}

describe('codex item identity', () => {
it('gives a resumed turn the same message keys as the live turn it renumbered', () => {
expect(keysFor(LIVE_TURN)).toEqual(keysFor(RESUMED_TURN))
})

it('numbers messages 0,1,2 on both sides — the projection skips the dropped command', () => {
const ordinals = new CodexTurnOrdinals()
const live = LIVE_TURN.map((item) =>
codexItemIdentity({ threadId: THREAD_ID, turnId: TURN_ID, item, ordinals })
)

expect(live.map((id) => (id.provider === 'codex' ? id.ordinal : null))).toEqual([0, 1, null, 2])
})

it('survives an item type this build does not model, because both sides skip it alike', () => {
const withUnknown = [
LIVE_TURN[0] as CodexThreadItem,
{ type: 'somethingCodexAddedLater', id: 'item-9' },
LIVE_TURN[1] as CodexThreadItem
]

expect(keysFor(withUnknown)).toEqual(keysFor([LIVE_TURN[0], LIVE_TURN[1]] as CodexThreadItem[]))
})

it('assigns an ordinal once and reuses it, so a delta and its completion upsert one row', () => {
const ordinals = new CodexTurnOrdinals()
ordinals.ordinalFor(TURN_ID, 'item-0')

expect(ordinals.ordinalFor(TURN_ID, 'item-1')).toBe(1)
expect(ordinals.ordinalFor(TURN_ID, 'item-0')).toBe(0)
})

it('restarts numbering per turn', () => {
const ordinals = new CodexTurnOrdinals()
ordinals.ordinalFor(TURN_ID, 'item-0')

expect(ordinals.ordinalFor('turn-2', 'item-1')).toBe(0)
})

it('keys a non-message item and a turnless message in the orca namespace', () => {
const ordinals = new CodexTurnOrdinals()
const command = codexItemIdentity({
threadId: THREAD_ID,
turnId: TURN_ID,
item: LIVE_TURN[2] as CodexThreadItem,
ordinals
})
const orphan = codexItemIdentity({
threadId: THREAD_ID,
turnId: null,
item: LIVE_TURN[1] as CodexThreadItem,
ordinals
})

expect(command).toEqual({ provider: 'orca', clientMessageId: 'codex-item:thread-abc:item-2' })
expect(orphan).toEqual({ provider: 'orca', clientMessageId: 'codex-item:thread-abc:item-1' })
})
})

describe('codex item bodies', () => {
it('reads structured user content and flat agent text alike', () => {
expect(codexMessageBlocks(LIVE_TURN[0] as CodexThreadItem)).toEqual([
{ type: 'text', text: 'list the files' }
])
expect(codexMessageBlocks(LIVE_TURN[1] as CodexThreadItem)).toEqual([
{ type: 'text', text: 'Let me look.' }
])
})

it('maps a finished zero-exit command to a completed shell tool call', () => {
expect(codexItemBody(LIVE_TURN[2] as CodexThreadItem)).toEqual({
kind: 'tool-call',
name: 'shell',
input: { command: 'ls', cwd: '/tmp' },
state: 'completed',
output: { head: 'a\nb\n', byteLength: 4, truncated: false, digest: expect.any(String) }
})
})

it('calls a nonzero exit a failure even though codex calls the status completed', () => {
const body = codexItemBody({
type: 'commandExecution',
id: 'item-2',
command: 'false',
status: 'completed',
exitCode: 1
})

expect(body).toMatchObject({ state: 'failed' })
})

it('treats an unfinished command as running and an aborted one as failed', () => {
expect(
codexItemBody({ type: 'commandExecution', id: 'a', command: 'sleep', status: 'inProgress' })
).toMatchObject({ state: 'running' })
expect(
codexItemBody({ type: 'commandExecution', id: 'a', command: 'sleep', status: 'aborted' })
).toMatchObject({ state: 'failed' })
})

it('renders reasoning as status and skips an item with nothing to show', () => {
expect(codexItemBody({ type: 'reasoning', id: 'r', text: 'thinking' })).toEqual({
kind: 'status',
text: 'thinking'
})
expect(codexItemBody({ type: 'reasoning', id: 'r' })).toBeNull()
expect(codexItemBody({ type: 'agentMessage', id: 'm', text: '' })).toBeNull()
expect(codexItemBody({ type: 'webSearch', id: 'w' })).toBeNull()
})

it('refuses a value that is not a thread item at all', () => {
expect(readCodexThreadItem({ type: 'agentMessage' })).toBeNull()
expect(readCodexThreadItem(null)).toBeNull()
expect(readCodexThreadItem({ type: 'agentMessage', id: 'm' })).not.toBeNull()
})
})
191 changes: 191 additions & 0 deletions src/main/codex/codex-structured-item-translation.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
import type {
AgentJournalItemBody,
AgentJournalItemIdentity
} from '../../shared/agent-session-journal-types'
import type { NativeChatBlock } from '../../shared/native-chat-types'
import {
boundInlineText,
DEFAULT_JOURNAL_PAYLOAD_LIMITS
} from '../native-chat/agent-session-journal/journal-payload-bounds'

// Codex thread items → journal item bodies and durable identities.
//
// THE ORDINAL RULE, and why it is not "index within the turn". Codex renumbers
// item ids positionally on resume (`item-1`…`item-N` across the whole thread),
// and a resumed turn does NOT contain every item the live turn emitted —
// reasoning and command execution are dropped from persisted history. Numbering
// by live position would therefore shift every message after the first tool
// call and hand the user a duplicate of the assistant's answer after a resume.
//
// So the ordinal counts MESSAGE items only, and the same projection is applied
// to the live stream and to a resumed turn's item list. Any other item type —
// including ones this build does not model — is skipped identically on both
// sides, which is what makes the key survive a Codex release that adds one.

/** Only these carry a durable `(threadId, turnId, ordinal)` identity. */
const CODEX_MESSAGE_ITEM_TYPES = new Set(['userMessage', 'agentMessage'])

export type CodexThreadItem = {
type: string
id: string
[key: string]: unknown
}

export function isCodexMessageItemType(type: string): boolean {
return CODEX_MESSAGE_ITEM_TYPES.has(type)
}

export function readCodexThreadItem(value: unknown): CodexThreadItem | null {
if (typeof value !== 'object' || value === null) {
return null
}
const record = value as Record<string, unknown>
return typeof record.type === 'string' && typeof record.id === 'string'
? (record as CodexThreadItem)
: null
}

/**
* Ordinals for one thread, assigned on first sight and never reassigned.
*
* Non-message items are given no ordinal at all rather than a number from a
* second counter: a counter that a resumed history cannot reproduce is worse
* than no key, because it would look reconcilable and reconcile wrongly.
*/
export class CodexTurnOrdinals {
private readonly turns = new Map<string, Map<string, number>>()

ordinalFor(turnId: string, codexItemId: string): number {
const assigned = this.turns.get(turnId) ?? new Map<string, number>()
this.turns.set(turnId, assigned)
const existing = assigned.get(codexItemId)
if (existing !== undefined) {
return existing
}
const ordinal = assigned.size
assigned.set(codexItemId, ordinal)
return ordinal
}

forgetTurn(turnId: string): void {
this.turns.delete(turnId)
}
}

/**
* Durable identity for a Codex item, or null for one that has none.
*
* Non-message items fall back to the `orca` namespace keyed by the Codex item
* id. That id is unstable across resume, so those rows are live-session detail
* that a recovered journal simply will not contain — which is correct: Codex
* itself does not persist them either.
*/
export function codexItemIdentity(input: {
threadId: string
turnId: string | null
item: CodexThreadItem
ordinals: CodexTurnOrdinals
}): AgentJournalItemIdentity {
const { item, turnId } = input
if (turnId && isCodexMessageItemType(item.type)) {
return {
provider: 'codex',
threadId: input.threadId,
turnId,
ordinal: input.ordinals.ordinalFor(turnId, item.id)
}
}
return { provider: 'orca', clientMessageId: `codex-item:${input.threadId}:${item.id}` }
}

function readString(source: Record<string, unknown>, key: string): string | null {
const value = source[key]
return typeof value === 'string' && value.length > 0 ? value : null
}

/** `userMessage` carries structured content parts; `agentMessage` a flat text. */
export function codexMessageBlocks(item: CodexThreadItem): NativeChatBlock[] {
const text = readString(item, 'text')
if (text !== null) {
return [{ type: 'text', text }]
}
const content = item.content
if (!Array.isArray(content)) {
return []
}
const blocks: NativeChatBlock[] = []

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Translate image content parts in provider user-message echoes. turnInputFor sends image and localImage blocks, but this echo path retains only text; because an accepted submission aliases to the provider key, the echo then revises the optimistic row and replaces its complete mixed text/image body with text only. Map image/localImage back to image-ref blocks and test reconciliation of mixed content.

for (const part of content) {
if (typeof part !== 'object' || part === null) {
continue
}
const partText = readString(part as Record<string, unknown>, 'text')
if (partText !== null) {
blocks.push({ type: 'text', text: partText })
}
}
return blocks
}

/** Codex reports `inProgress` then a terminal status; a zero exit code is the
* only thing that makes a finished command a success. */
function commandState(item: CodexThreadItem): 'running' | 'completed' | 'failed' {
const status = readString(item, 'status')
if (status === null || status === 'inProgress') {
return 'running'
}
if (status !== 'completed') {
return 'failed'
}
const exitCode = item.exitCode
return typeof exitCode === 'number' && exitCode !== 0 ? 'failed' : 'completed'
}

function commandBody(item: CodexThreadItem): AgentJournalItemBody {
const output = readString(item, 'aggregatedOutput')
return {
kind: 'tool-call',
name: 'shell',
input: { command: item.command ?? null, cwd: item.cwd ?? null },
state: commandState(item),
...(output === null
? {}
: { output: boundInlineText(output, DEFAULT_JOURNAL_PAYLOAD_LIMITS).bounded })
}
}

/**
* Journal body for a Codex item, or null for one with nothing to render.
*
* An unmodelled item type is skipped rather than journaled as a placeholder: a
* row the client cannot render is worse than a gap, and the ordinal projection
* already guarantees skipping it costs the following messages nothing.
*/
export function codexItemBody(item: CodexThreadItem): AgentJournalItemBody | null {
if (item.type === 'userMessage' || item.type === 'agentMessage') {
const blocks = codexMessageBlocks(item)
return blocks.length === 0
? null
: { kind: 'message', role: item.type === 'userMessage' ? 'user' : 'assistant', blocks }
}
if (item.type === 'commandExecution') {
return commandBody(item)
}
if (item.type === 'fileChange') {
return {
kind: 'tool-call',
name: 'apply_patch',
input: { changes: item.changes ?? null },
state: commandState(item)
}
}
if (item.type === 'reasoning') {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Handle array-shaped reasoning content. Current app-server reasoning items expose summary/content as arrays, so readString returns null and the item is silently skipped. Join and bound the supported array elements into the status body, and add a real-wire-shape fixture so reasoning does not disappear from the journal.

const text = readString(item, 'text') ?? readString(item, 'summary')
return text === null ? null : { kind: 'status', text }
}
return null
}

/** Snapshot body for text still streaming, before its item completes. */
export function codexStreamingMessageBody(text: string): AgentJournalItemBody {
return { kind: 'message', role: 'assistant', blocks: [{ type: 'text', text }] }
}
Loading
Loading