Repository navigation
Journal what a Codex session streams, and prove it end to end #13394
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
4a9004f
5b34f31
115ef40
61cb67c
d28861f
b4ed53f
76cce58
f763791
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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() | ||
| }) | ||
| }) |
| 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[] = [] | ||
| 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') { | ||
|
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 }] } | ||
| } | ||
There was a problem hiding this comment.
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.