import type { CodexAppFrameData, CodexAppStreamClosedData, CodexAppTransferCommitResult, CodexAppTransferReadResult, } from '@dsh-remote/protocol' import { CODEX_APP_TRANSFER_CHUNK_BYTES, MAX_CODEX_APP_TRANSFER_BYTES, } from '@dsh-remote/protocol' import type { RemoteClientCore } from './index.js' import { createRemoteId, RemoteGatewayError } from './remote-gateway.js' export type AgentBackend = 'harness' | 'codex' export interface DisplaySession { id: string backend: AgentBackend nativeId: string sessionTreeId?: string title?: string preview?: string cwd?: string /** Model reported by the CodeX Thread or its most recent Turn. */ model?: string reasoningEffort?: string createdAt: number updatedAt: number status: 'idle' | 'running' | 'waiting' | 'failed' archived?: boolean pinned?: boolean } export interface CodexCwdWorkspace { id: string name: string path: string position: number createdAt: number updatedAt: number } export interface DisplayImage { uri: string name?: string } export interface DisplayHistoryItem { id: string sessionId: string backend: AgentBackend kind: 'message' | 'tool' | 'file-change' | 'approval' | 'status' | 'error' | 'unknown' role?: 'user' | 'assistant' text?: string images?: DisplayImage[] status?: 'running' | 'completed' | 'failed' | 'declined' createdAt?: number nativeRef: { threadId?: string turnId?: string itemId?: string requestHandle?: string } details?: Record } export interface CodexThreadListPage { sessions: DisplaySession[] nextCursor?: string } export interface CodexHistoryView { session: DisplaySession items: DisplayHistoryItem[] } export interface CodexPendingApproval { requestHandle: string kind: 'command' | 'file-change' command?: string reason?: string } export interface CodexTimelineState { session: DisplaySession items: DisplayHistoryItem[] activeTurnId?: string approval?: CodexPendingApproval } export interface CodexStream { streamId: string close(): Promise } const MAX_DISPLAY_ITEM_TEXT = 256 * 1024 const CODEX_IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']) const DATA_IMAGE_URL = /^data:(image\/(?:png|jpeg|webp|gif));base64,([A-Za-z0-9+/]+={0,2})$/u /** Shared Web/Android client for the independent Codex domain in Remote. */ export class CodexRemoteClient { constructor(private readonly core: RemoteClientCore, private readonly historyPreview = false) {} /** Low-level allowlisted request used by the Desktop Web loopback facade. */ private previewSupported = true async request(method: string, params: unknown, signal?: AbortSignal): Promise { if (method === 'dsh/sessionHistory' && this.historyPreview && this.previewSupported) { try {return await this.core.rpc('codex.app.call', {method, params, previewHistory: true}, signal)} catch (error) { const code = (error as {code?: string})?.code if (code !== 'INVALID_MESSAGE' && code !== 'RESPONSE_TOO_LARGE') throw error if (code === 'INVALID_MESSAGE') this.previewSupported = false } } const largeHistory = method === 'dsh/historyDetail' || method === 'dsh/sessionHistory' || method === 'thread/read' && isRecord(params) && params.includeTurns === true return this.call(method, params, largeHistory || hasImageInput(params), signal) } async account(signal?: AbortSignal): Promise { return this.call('account/read', { refreshToken: false }, false, signal) } async models(signal?: AbortSignal): Promise { return this.call('model/list', {}, false, signal) } async threads(params: Record = {}, signal?: AbortSignal): Promise { const result = await this.call('thread/list', params, false, signal) if (!isRecord(result) || !Array.isArray(result.data)) throw invalidResponse('thread list') return { sessions: result.data.map(projectCodexThread).filter((value): value is DisplaySession => value !== undefined), ...(typeof result.nextCursor === 'string' ? { nextCursor: result.nextCursor } : {}), } } async history(threadId: string, signal?: AbortSignal): Promise { const result = await this.call('thread/read', { threadId, includeTurns: true }, true, signal) if (!isRecord(result) || !isRecord(result.thread)) throw invalidResponse('thread history') const session = projectCodexThread(result.thread) if (session === undefined) throw invalidResponse('thread history') return { session, items: projectCodexHistory(result.thread) } } async start(cwd: string, model?: string, signal?: AbortSignal): Promise { const result = await this.call('thread/start', { cwd, ...(model === undefined ? {} : { model }) }, false, signal) return requireProjectedThread(result) } async resume(threadId: string, signal?: AbortSignal): Promise { return requireProjectedThread(await this.call('thread/resume', { threadId }, false, signal)) } async fork(threadId: string, lastTurnId?: string, signal?: AbortSignal): Promise { return requireProjectedThread(await this.call('thread/fork', { threadId, ...(lastTurnId === undefined ? {} : { lastTurnId }), }, false, signal)) } async rename(threadId: string, name: string, signal?: AbortSignal): Promise { await this.call('thread/name/set', { threadId, name }, false, signal) } async prompt(threadId: string, text: string, signal?: AbortSignal): Promise { return this.call('turn/start', { threadId, input: [{ type: 'text', text }] }, false, signal) } async steer(threadId: string, expectedTurnId: string, text: string, signal?: AbortSignal): Promise { return this.call('turn/steer', { threadId, expectedTurnId, input: [{ type: 'text', text }], }, false, signal) } async interrupt(threadId: string, turnId: string, signal?: AbortSignal): Promise { await this.call('turn/interrupt', { threadId, turnId }, false, signal) } async respond(requestHandle: string, decision: 'accept' | 'decline' | 'cancel', signal?: AbortSignal): Promise { await this.core.rpc('codex.app.respond', { requestHandle, decision }, signal) } async subscribe( threadId: string, onFrame: (frame: CodexAppFrameData['frame']) => void, signal?: AbortSignal, onClose?: (reason: CodexAppStreamClosedData['reason']) => void, ): Promise { const streamId = createRemoteId() let closed = false let unsubscribe: () => void = () => undefined const markClosed = () => { if (closed) return false closed = true unsubscribe() return true } unsubscribe = this.core.onEvent(event => { if (!isRecord(event.data) || event.data.streamId !== streamId) return if (event.event === 'codex.app.stream.closed') { if (!markClosed()) return onClose?.(codexStreamCloseReason(event.data.reason)) return } if (event.event !== 'codex.app.frame' || !isRecord(event.data.frame) || typeof event.data.frame.method !== 'string') return onFrame(event.data.frame as CodexAppFrameData['frame']) }) try { await this.core.rpc('codex.app.stream.open', { streamId, threadId }, signal) } catch (error) { unsubscribe() throw error } return { streamId, close: async () => { if (!markClosed()) return await this.core.rpc('codex.app.stream.close', { streamId }).catch(() => undefined) }, } } private async call( method: string, params: unknown, transfer: boolean, signal?: AbortSignal, ): Promise { const envelope = { method, params } if (!transfer) return this.core.rpc('codex.app.call', envelope, signal) return this.callTransferred(new TextEncoder().encode(JSON.stringify(envelope)), signal) } private async callTransferred(encoded: Uint8Array, signal?: AbortSignal): Promise { if (encoded.byteLength === 0 || encoded.byteLength > MAX_CODEX_APP_TRANSFER_BYTES) { throw new RemoteGatewayError('INVALID_MESSAGE', 'The Codex request exceeds the transfer limit.') } const transferId = createCodexTransferId() const totalChunks = Math.ceil(encoded.byteLength / CODEX_APP_TRANSFER_CHUNK_BYTES) let opened = false try { await this.core.rpc('codex.app.transfer.open', { transferId, totalBytes: encoded.byteLength, totalChunks }, signal) opened = true for (let index = 0; index < totalChunks; index += 1) { const start = index * CODEX_APP_TRANSFER_CHUNK_BYTES const chunk = encoded.subarray(start, Math.min(start + CODEX_APP_TRANSFER_CHUNK_BYTES, encoded.byteLength)) await this.core.rpc('codex.app.transfer.chunk', { transferId, index, data: bytesToBase64(chunk) }, signal) } const committed = await this.core.rpc( 'codex.app.transfer.commit', { transferId }, signal, ) if (committed.kind === 'inline') return committed.response if (committed.transferId !== transferId || committed.totalBytes <= 0 || committed.totalBytes > MAX_CODEX_APP_TRANSFER_BYTES || committed.totalChunks !== Math.ceil(committed.totalBytes / CODEX_APP_TRANSFER_CHUNK_BYTES)) { throw invalidResponse('transfer descriptor') } const response = new Uint8Array(committed.totalBytes) let offset = 0 for (let index = 0; index < committed.totalChunks; index += 1) { const result = await this.core.rpc( 'codex.app.transfer.read', { transferId, index }, signal, ) if (result.transferId !== transferId || result.index !== index) throw invalidResponse('transfer ordering') const chunk = base64ToBytes(result.data) const expected = Math.min(CODEX_APP_TRANSFER_CHUNK_BYTES, committed.totalBytes - offset) if (chunk.byteLength !== expected) throw invalidResponse('transfer chunk') response.set(chunk, offset) offset += chunk.byteLength } return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(response)) as unknown } finally { if (opened) await this.core.rpc('codex.app.transfer.close', { transferId }).catch(() => undefined) } } } function hasImageInput(params: unknown): boolean { return isRecord(params) && Array.isArray(params.input) && params.input.some(value => isRecord(value) && value.type === 'image') } export function projectCodexThread(value: unknown): DisplaySession | undefined { if (!isRecord(value) || typeof value.id !== 'string') return undefined const createdAt = normalizeTimestamp(value.createdAt) const updatedAt = normalizeTimestamp(value.updatedAt) || createdAt const model = projectCodexModel(value) const preview = typeof value.preview === 'string' && value.preview.trim().length > 0 ? value.preview : firstUserPreview(projectCodexHistory(value)) return { id: `codex:${value.id}`, backend: 'codex', nativeId: value.id, ...(typeof value.sessionId === 'string' ? { sessionTreeId: value.sessionId } : {}), ...(typeof value.name === 'string' && value.name.length > 0 ? { title: value.name } : {}), ...(preview === undefined ? {} : { preview }), ...(typeof value.cwd === 'string' ? { cwd: value.cwd } : {}), ...(model.model === undefined ? {} : { model: model.model }), ...(model.reasoningEffort === undefined ? {} : { reasoningEffort: model.reasoningEffort }), createdAt, updatedAt, status: projectThreadStatus(value.status), ...(typeof value.archived === 'boolean' ? { archived: value.archived } : {}), ...(typeof value.isPinned === 'boolean' ? { pinned: value.isPinned } : {}), } } /** * Extract model metadata without assuming one App Server release's exact * Thread shape. Newer servers put it on the Thread, while older responses * expose it only on the most recent Turn. */ export function projectCodexModel(value: unknown): { model?: string; reasoningEffort?: string } { if (!isRecord(value)) return {} const candidates: unknown[] = [] if (Array.isArray(value.turns)) { for (let index = value.turns.length - 1; index >= 0; index -= 1) candidates.push(value.turns[index]) } candidates.push(value) for (const candidate of candidates) { if (!isRecord(candidate)) continue const model = typeof candidate.model === 'string' && candidate.model.length > 0 ? candidate.model : typeof candidate.modelId === 'string' && candidate.modelId.length > 0 ? candidate.modelId : undefined if (model === undefined) continue const reasoningEffort = typeof candidate.reasoningEffort === 'string' && candidate.reasoningEffort.length > 0 ? candidate.reasoningEffort : typeof candidate.effort === 'string' && candidate.effort.length > 0 ? candidate.effort : undefined return { model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }) } } return {} } /** * Builds a deterministic, bounded Workspace fallback from cwd values that the * App Server already exposed through thread/list. Callers should use this only * when project/list has no usable projects. */ export function deriveCodexCwdWorkspaces(values: unknown[]): CodexCwdWorkspace[] { const byPath = new Map() const usedIds = new Set() for (const value of values) { const session = projectCodexThread(value) if (session === undefined || session.cwd === undefined || session.cwd.length === 0) continue const path = session.cwd if (!isAbsoluteWorkspacePath(path)) continue const key = normalizeWorkspacePath(path) const existing = byPath.get(key) if (existing !== undefined) { existing.createdAt = earliestTimestamp(existing.createdAt, session.createdAt) existing.updatedAt = Math.max(existing.updatedAt, session.updatedAt) continue } const baseId = `cwd-${hashWorkspacePath(key)}` let id = baseId for (let suffix = 2; usedIds.has(id); suffix += 1) id = `${baseId}-${suffix}` usedIds.add(id) byPath.set(key, { id, name: workspaceBasename(path), path, position: byPath.size, createdAt: session.createdAt, updatedAt: session.updatedAt, }) } return [...byPath.values()] } export function projectCodexHistory(thread: unknown): DisplayHistoryItem[] { if (!isRecord(thread) || typeof thread.id !== 'string' || !Array.isArray(thread.turns)) return [] const sessionId = `codex:${thread.id}` const output: DisplayHistoryItem[] = [] for (const turn of thread.turns) { if (!isRecord(turn) || typeof turn.id !== 'string' || !Array.isArray(turn.items)) continue for (let index = 0; index < turn.items.length; index += 1) { const item = turn.items[index] output.push(projectCodexItem(item, thread.id, turn.id, sessionId, index)) } } return output } /** Creates a replaceable persisted baseline before live notifications are reduced. */ export function createCodexTimelineState(thread: unknown): CodexTimelineState | undefined { const session = projectCodexThread(thread) if (session === undefined) return undefined const record = isRecord(thread) ? thread : {} const activeTurnId = findActiveTurnId(record.turns) return { session, items: projectCodexHistory(thread), ...(activeTurnId === undefined ? {} : { activeTurnId }), } } /** * Reduces official App Server notifications into the DSH display projection. * Persisted baselines replace this state after reconnect; mutations are never * replayed by the reducer. */ export function reduceCodexTimelineFrame( state: CodexTimelineState, frame: { method: string; params: unknown }, ): CodexTimelineState { const next = reduceCodexFrame(state, frame) if (next.session.preview?.trim()) return next const preview = firstUserPreview(next.items) return preview === undefined ? next : { ...next, session: { ...next.session, preview } } } /** A live Thread has no preview until a later read; retain its first user message. */ function firstUserPreview(items: DisplayHistoryItem[]): string | undefined { for (const item of items) { if (item.kind !== 'message' || item.role !== 'user') continue const preview = item.text?.replace(/\s+/g, ' ').trim().slice(0, 160) if (preview) return preview } return undefined } function reduceCodexFrame( state: CodexTimelineState, frame: { method: string; params: unknown }, ): CodexTimelineState { const params = isRecord(frame.params) ? frame.params : {} if (frame.method === 'thread/status/changed') { const status = projectThreadStatus(params.status) // An inactive/system-error status is terminal evidence for the current // turn even if the App Server omits or delays turn/completed. Clear the // turn handle so a later approval resolution cannot revive `running`. if (status === 'idle' || status === 'failed') { const terminalItemStatus = status === 'failed' ? 'failed' as const : 'completed' as const const next = { ...state, session: { ...state.session, status }, // Some App Server failure paths report only thread/status/changed and // omit turn/completed. Settle transient rows so the UI cannot keep an // assistant spinner or running tool forever. items: state.items.map(item => item.status === 'running' ? { ...item, status: terminalItemStatus } : item), } delete next.activeTurnId return next } return { ...state, session: { ...state.session, status } } } if (frame.method === 'thread/name/updated' && typeof params.threadName === 'string') { return { ...state, session: { ...state.session, title: params.threadName } } } if (frame.method === 'thread/archived') return { ...state, session: { ...state.session, archived: true } } if (frame.method === 'thread/unarchived') return { ...state, session: { ...state.session, archived: false } } if (frame.method === 'turn/started') { const turn = isRecord(params.turn) ? params.turn : undefined const turnId = typeof turn?.id === 'string' ? turn.id : undefined return { ...state, items: turn === undefined ? state.items : upsertItems(state.items, projectTurn(turn, state.session.nativeId)), ...(turnId === undefined ? {} : { activeTurnId: turnId }), session: { ...state.session, status: 'running' }, } } if (frame.method === 'item/started' || frame.method === 'item/completed') { const item = params.item const turnId = extractNotificationTurnId(params) if (turnId === undefined) return state return { ...state, items: upsertItems(state.items, [projectCodexItem(item, state.session.nativeId, turnId, state.session.id, state.items.length)]), } } if (frame.method === 'item/agentMessage/delta' && typeof params.itemId === 'string' && typeof params.delta === 'string') { const turnId = extractNotificationTurnId(params) ?? state.activeTurnId ?? 'active' const itemId = params.itemId const id = `codex:${state.session.nativeId}:${turnId}:${itemId}` const index = state.items.findIndex(item => item.id === id || item.nativeRef.itemId === itemId) if (index < 0) { return { ...state, items: [...state.items, { id, sessionId: state.session.id, backend: 'codex', kind: 'message', role: 'assistant', text: params.delta, status: 'running', nativeRef: { threadId: state.session.nativeId, turnId, itemId }, }], } } const next = [...state.items] const current = next[index]! next[index] = { ...current, text: `${current.text ?? ''}${params.delta}`, status: 'running' } return { ...state, items: next } } if ((frame.method === 'item/reasoning/summaryTextDelta' || frame.method === 'item/reasoning/textDelta' || frame.method === 'item/plan/delta') && typeof params.itemId === 'string' && typeof params.delta === 'string') { const turnId = extractNotificationTurnId(params) ?? state.activeTurnId ?? 'active' const type = frame.method === 'item/plan/delta' ? 'plan' : 'reasoning' return appendOrCreateStatusItem(state, params.itemId, turnId, type, params.delta) } if (frame.method === 'turn/plan/updated' && Array.isArray(params.plan)) { const turnId = extractNotificationTurnId(params) ?? state.activeTurnId ?? 'active' const text = params.plan.flatMap(value => { const item = isRecord(value) ? value : undefined if (typeof item?.step !== 'string') return [] const marker = item.status === 'completed' ? '[x]' : item.status === 'inProgress' ? '[~]' : '[ ]' return [`${marker} ${item.step}`] }).join('\n') return replaceOrCreateStatusItem(state, `plan:${turnId}`, turnId, 'plan', text) } if ((frame.method === 'item/commandExecution/outputDelta' || frame.method === 'item/fileChange/outputDelta') && typeof params.itemId === 'string' && typeof params.delta === 'string') { return appendItemText(state, params.itemId, params.delta) } if (frame.method === 'item/mcpToolCall/progress' && typeof params.itemId === 'string' && typeof params.message === 'string') { return appendItemText(state, params.itemId, `\n${params.message}`) } if (frame.method === 'item/fileChange/patchUpdated' && typeof params.itemId === 'string' && Array.isArray(params.changes)) { return replaceItemText(state, params.itemId, fileChangeText(params.changes)) } if (frame.method === 'serverRequest/resolved' && state.approval !== undefined) { const requestHandle = state.approval.requestHandle return { ...state, approval: undefined, items: state.items.map(item => item.nativeRef.requestHandle === requestHandle ? { ...item, status: 'completed' as const } : item), session: { ...state.session, status: state.activeTurnId === undefined ? 'idle' : 'running' }, } } if (frame.method === 'turn/completed') { const turn = isRecord(params.turn) ? params.turn : undefined const failed = turn?.status === 'failed' || turn?.error !== null && turn?.error !== undefined const next = { ...state, session: { ...state.session, status: failed ? 'failed' as const : 'idle' as const }, items: turn === undefined ? state.items : upsertItems(state.items, projectTurn(turn, state.session.nativeId)), approval: undefined, } delete next.activeTurnId return next } if ((frame.method === 'item/commandExecution/requestApproval' || frame.method === 'item/fileChange/requestApproval') && typeof params.requestHandle === 'string') { const command = commandText(params.command) const approval: CodexPendingApproval = { requestHandle: params.requestHandle, kind: frame.method === 'item/commandExecution/requestApproval' ? 'command' : 'file-change', ...(command === undefined ? {} : { command }), ...(typeof params.reason === 'string' ? { reason: params.reason } : {}), } const turnId = extractNotificationTurnId(params) const approvalItem: DisplayHistoryItem = { id: `codex:${state.session.nativeId}:${turnId ?? 'approval'}:${params.requestHandle}`, sessionId: state.session.id, backend: 'codex', kind: 'approval', text: command ?? (approval.kind === 'file-change' ? 'File change approval' : 'Command approval'), status: 'running', nativeRef: { threadId: state.session.nativeId, ...(turnId === undefined ? {} : { turnId }), requestHandle: params.requestHandle, }, details: { kind: approval.kind, ...(approval.reason === undefined ? {} : { reason: approval.reason }), }, } return { ...state, approval, items: upsertItems(state.items, [approvalItem]), session: { ...state.session, status: 'waiting' } } } return state } export function projectCodexItem( value: unknown, threadId: string, turnId: string, sessionId: string, index: number, ): DisplayHistoryItem { const item = isRecord(value) ? value : {} const itemId = typeof item.id === 'string' ? item.id : `${turnId}:${index}` const type = typeof item.type === 'string' ? item.type : 'unknown' const base = { id: `codex:${threadId}:${turnId}:${itemId}`, sessionId, backend: 'codex' as const, nativeRef: { threadId, turnId, ...(typeof item.id === 'string' ? { itemId: item.id } : {}) }, ...(normalizeTimestamp(item.createdAt) > 0 ? { createdAt: normalizeTimestamp(item.createdAt) } : {}), } if (type === 'userMessage') { const images = itemImages(item) return { ...base, kind: 'message', role: 'user', text: itemText(item), ...(images.length === 0 ? {} : { images }), } } if (type === 'agentMessage') { const images = itemImages(item) return { ...base, kind: 'message', role: 'assistant', text: itemText(item), ...(images.length === 0 ? {} : { images }), status: projectItemStatus(item.status), } } if (type === 'commandExecution') { return { ...base, kind: 'tool', text: commandExecutionText(item), status: projectItemStatus(item.status), details: { type } } } if (isToolItemType(type)) { const images = toolItemImages(item) return { ...base, kind: 'tool', text: toolCallText(item), ...(images.length === 0 ? {} : { images }), status: projectItemStatus(item.status), details: { type }, } } if (type === 'fileChange') { return { ...base, kind: 'file-change', text: fileChangeText(item.changes), status: projectItemStatus(item.status), details: { type } } } if (type === 'plan' || type === 'reasoning') { return { ...base, kind: 'status', text: itemText(item) ?? textArray(item.summary) ?? type, details: { type } } } if (type === 'error') return { ...base, kind: 'error', text: itemText(item), status: 'failed', details: { type } } return { ...base, kind: 'unknown', text: `Unsupported Codex item: ${type}`, details: { type } } } function projectTurn(turn: Record, threadId: string): DisplayHistoryItem[] { if (typeof turn.id !== 'string' || !Array.isArray(turn.items)) return [] const sessionId = `codex:${threadId}` return turn.items.map((item, index) => projectCodexItem(item, threadId, turn.id as string, sessionId, index)) } function upsertItems(current: DisplayHistoryItem[], incoming: DisplayHistoryItem[]): DisplayHistoryItem[] { if (incoming.length === 0) return current const next = [...current] for (const item of incoming) { const index = next.findIndex(value => value.id === item.id) if (index < 0) next.push(item) else next[index] = item } return next } function appendItemText(state: CodexTimelineState, itemId: string, delta: string): CodexTimelineState { const index = state.items.findIndex(item => item.nativeRef.itemId === itemId) if (index < 0) return state const items = [...state.items] const current = items[index]! items[index] = { ...current, text: boundedText(`${current.text ?? ''}${delta}`), status: 'running' } return { ...state, items } } function replaceItemText(state: CodexTimelineState, itemId: string, text: string): CodexTimelineState { const index = state.items.findIndex(item => item.nativeRef.itemId === itemId) if (index < 0) return state const items = [...state.items] items[index] = { ...items[index]!, text: boundedText(text), status: 'running' } return { ...state, items } } function appendOrCreateStatusItem( state: CodexTimelineState, itemId: string, turnId: string, type: 'reasoning' | 'plan', delta: string, ): CodexTimelineState { const index = state.items.findIndex(item => item.nativeRef.itemId === itemId && item.details?.type === type) if (index < 0) return replaceOrCreateStatusItem(state, itemId, turnId, type, delta) const items = [...state.items] const current = items[index]! items[index] = { ...current, text: boundedText(`${current.text ?? ''}${delta}`), status: 'running' } return { ...state, items } } function replaceOrCreateStatusItem( state: CodexTimelineState, itemId: string, turnId: string, type: 'reasoning' | 'plan', text: string, ): CodexTimelineState { const id = `codex:${state.session.nativeId}:${turnId}:${itemId}` const incoming: DisplayHistoryItem = { id, sessionId: state.session.id, backend: 'codex', kind: 'status', text: boundedText(text), status: 'running', nativeRef: { threadId: state.session.nativeId, turnId, itemId }, details: { type }, } const index = state.items.findIndex(item => item.id === id || item.nativeRef.itemId === itemId) if (index < 0) return { ...state, items: [...state.items, incoming] } const items = [...state.items] items[index] = incoming return { ...state, items } } function findActiveTurnId(value: unknown): string | undefined { if (!Array.isArray(value)) return undefined for (let index = value.length - 1; index >= 0; index -= 1) { const turn = isRecord(value[index]) ? value[index] : undefined if (typeof turn?.id === 'string' && (turn.status === 'inProgress' || turn.status === 'running')) return turn.id } return undefined } function extractNotificationTurnId(params: Record): string | undefined { if (typeof params.turnId === 'string') return params.turnId if (isRecord(params.turn) && typeof params.turn.id === 'string') return params.turn.id return undefined } function commandText(value: unknown): string | undefined { if (typeof value === 'string') return value if (Array.isArray(value) && value.every(part => typeof part === 'string')) return value.join(' ') return undefined } function requireProjectedThread(result: unknown): DisplaySession { if (!isRecord(result)) throw invalidResponse('thread') const session = projectCodexThread(result.thread) if (session === undefined) throw invalidResponse('thread') return session } function projectThreadStatus(value: unknown): DisplaySession['status'] { if (!isRecord(value) || typeof value.type !== 'string') return 'idle' if (value.type === 'systemError') return 'failed' if (value.type !== 'active') return 'idle' return Array.isArray(value.activeFlags) && value.activeFlags.includes('waitingOnApproval') ? 'waiting' : 'running' } function projectItemStatus(value: unknown): DisplayHistoryItem['status'] { if (value === 'inProgress') return 'running' if (value === 'failed') return 'failed' if (value === 'declined') return 'declined' return 'completed' } function itemText(item: Record): string | undefined { if (typeof item.text === 'string') return boundedText(item.text) if (typeof item.content === 'string') return boundedText(item.content) const content = Array.isArray(item.content) ? item.content : Array.isArray(item.input) ? item.input : undefined if (content === undefined) return undefined const parts = content.flatMap(value => { if (typeof value === 'string') return [value] if (!isRecord(value)) return [] if (typeof value.text === 'string') return [value.text] return typeof value.content === 'string' ? [value.content] : [] }) return parts.length > 0 ? boundedText(parts.join('\n')) : undefined } function itemImages(item: Record): DisplayImage[] { const content = Array.isArray(item.content) ? item.content : Array.isArray(item.input) ? item.input : [] return content.flatMap(value => { if (!isRecord(value) || !isImageContent(value)) return [] const uri = imageDataUri(value) if (uri === undefined) return [] return [{ uri, ...(typeof value.name === 'string' && value.name.length > 0 ? { name: value.name } : {}), }] }) } function toolItemImages(item: Record): DisplayImage[] { const candidates = [ isRecord(item.result) ? item.result : undefined, isRecord(item.output) ? item.output : undefined, Array.isArray(item.contentItems) ? { content: item.contentItems } : undefined, Array.isArray(item.output) ? { content: item.output } : undefined, ] for (const candidate of candidates) { if (candidate === undefined || !Array.isArray(candidate.content)) continue const images = itemImages(candidate) if (images.length > 0) return images } return [] } function isImageContent(value: Record): boolean { return value.type === 'image' || value.type === 'input_image' } function imageDataUri(value: Record): string | undefined { const url = typeof value.url === 'string' ? value.url : typeof value.image_url === 'string' ? value.image_url : isRecord(value.image_url) && typeof value.image_url.url === 'string' ? value.image_url.url : undefined const parsed = url === undefined ? undefined : parseDataImageUrl(url) if (parsed !== undefined) return parsed.url if (typeof value.data !== 'string' || !isCanonicalBase64(value.data)) return undefined const mediaType = typeof value.mediaType === 'string' ? value.mediaType : typeof value.mimeType === 'string' ? value.mimeType : sniffImageMediaType(value.data) return mediaType !== undefined && CODEX_IMAGE_MEDIA_TYPES.has(mediaType) ? `data:${mediaType};base64,${value.data}` : undefined } function parseDataImageUrl(value: string): { url: string; mediaType: string; data: string } | undefined { const match = DATA_IMAGE_URL.exec(value) if (match === null) return undefined const mediaType = match[1]! const data = match[2]! if (!CODEX_IMAGE_MEDIA_TYPES.has(mediaType) || !isCanonicalBase64(data)) return undefined return { url: `data:${mediaType};base64,${data}`, mediaType, data } } function isCanonicalBase64(value: string): boolean { return value.length >= 4 && value.length % 4 === 0 && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value) } function sniffImageMediaType(data: string): string | undefined { const bytes = base64PrefixBytes(data, 32) if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) return 'image/png' if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg' if (bytes.length >= 6 && bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38 && (bytes[4] === 0x37 || bytes[4] === 0x39) && bytes[5] === 0x61) return 'image/gif' if (bytes.length >= 12 && bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 && bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50) return 'image/webp' return undefined } function base64PrefixBytes(value: string, maxBytes: number): Uint8Array { const chars = value.slice(0, Math.ceil(maxBytes / 3) * 4) let binary: string try { binary = atob(chars) } catch { return new Uint8Array() } const bytes = new Uint8Array(Math.min(binary.length, maxBytes)) for (let index = 0; index < bytes.length; index += 1) bytes[index] = binary.charCodeAt(index) return bytes } function isToolItemType(type: string): boolean { return type === 'mcpToolCall' || type === 'dynamicToolCall' || type === 'functionCallOutput' || type === 'hookPrompt' || type === 'collabAgentToolCall' || type === 'subAgentActivity' || type === 'webSearch' || type === 'imageView' || type === 'imageGeneration' || type === 'sleep' || type === 'enteredReviewMode' || type === 'exitedReviewMode' || type === 'contextCompaction' } function toolLabel(item: Record): string | undefined { if (typeof item.tool === 'string') return item.tool if (typeof item.server === 'string' && typeof item.name === 'string') return `${item.server}: ${item.name}` if (typeof item.command === 'string') return item.command if (Array.isArray(item.command) && item.command.every(value => typeof value === 'string')) return item.command.join(' ') return typeof item.type === 'string' ? item.type : undefined } function commandExecutionText(item: Record): string | undefined { const command = toolLabel(item) const output = typeof item.aggregatedOutput === 'string' ? item.aggregatedOutput : undefined if (command === undefined) return output === undefined ? undefined : boundedText(output) return boundedText(output === undefined || output === '' ? command : `${command}\n\n${output}`) } function toolCallText(item: Record): string | undefined { const type = typeof item.type === 'string' ? item.type : undefined if (type === 'webSearch') { const count = Array.isArray(item.results) ? item.results.length : 0 return count === 0 ? 'Web search completed.' : `Web search returned ${count} result${count === 1 ? '' : 's'}.` } if (type === 'imageView') return `Viewed image: ${typeof item.path === 'string' ? item.path : 'image'}` if (type === 'imageGeneration') { return typeof item.savedPath === 'string' ? `Generated image: ${item.savedPath}` : `Image generation ${typeof item.status === 'string' ? item.status : 'completed'}.` } if (type === 'contextCompaction') return 'CodeX compacted the conversation context.' if (type === 'enteredReviewMode' || type === 'exitedReviewMode') { const action = type === 'enteredReviewMode' ? 'Entered' : 'Exited' return `${action} review mode${typeof item.review === 'string' ? `: ${item.review}` : '.'}` } if (type === 'sleep') return `Waited ${typeof item.durationMs === 'number' && Number.isFinite(item.durationMs) ? item.durationMs : 0} ms.` if (type === 'subAgentActivity') { const kind = isRecord(item.kind) && typeof item.kind.type === 'string' ? item.kind.type : typeof item.kind === 'string' ? item.kind : 'Subagent activity' return [kind, typeof item.agentPath === 'string' ? item.agentPath : undefined] .filter((value): value is string => value !== undefined).join(': ') } const label = toolLabel(item) const error = compactUnknown(item.error) const rawResult = item.result ?? item.contentItems const result = itemText(isRecord(rawResult) ? rawResult : {}) ?? (toolItemImages(item).length > 0 ? undefined : compactUnknown(rawResult)) return boundedText([label, error, result].filter((value): value is string => value !== undefined && value !== '').join('\n\n')) || undefined } function fileChangeText(value: unknown): string { if (!Array.isArray(value)) return 'File changes' const changes = value.flatMap(change => { if (!isRecord(change) || typeof change.path !== 'string') return [] const kind = typeof change.kind === 'string' ? change.kind : 'update' return [`[${kind}] ${change.path}`] }) return boundedText(changes.length === 0 ? 'File changes' : changes.join('\n')) } function textArray(value: unknown): string | undefined { return Array.isArray(value) && value.every(part => typeof part === 'string') ? boundedText(value.join('\n')) : undefined } function compactUnknown(value: unknown): string | undefined { if (value === undefined || value === null) return undefined if (typeof value === 'string') return boundedText(value) try { return boundedText(JSON.stringify(value, undefined, 2)) } catch { return undefined } } function boundedText(value: string): string { return value.length <= MAX_DISPLAY_ITEM_TEXT ? value : `${value.slice(0, MAX_DISPLAY_ITEM_TEXT)}\n…` } function normalizeWorkspacePath(value: string): string { return value.replace(/[\\/]+$/u, '') || value } function isAbsoluteWorkspacePath(value: string): boolean { return value.startsWith('/') || /^\\\\[^\\]+\\[^\\]+/u.test(value) || /^[A-Za-z]:[\\/]/u.test(value) } function workspaceBasename(value: string): string { const normalized = normalizeWorkspacePath(value) return normalized.split(/[\\/]/u).at(-1) || value } function earliestTimestamp(left: number, right: number): number { if (left <= 0) return right if (right <= 0) return left return Math.min(left, right) } function hashWorkspacePath(value: string): string { let hash = 0x811c9dc5 for (let index = 0; index < value.length; index += 1) { hash ^= value.charCodeAt(index) hash = Math.imul(hash, 0x01000193) } return (hash >>> 0).toString(36) } function normalizeTimestamp(value: unknown): number { if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return 0 return value < 10_000_000_000 ? value * 1_000 : value } function bytesToBase64(value: Uint8Array): string { let binary = '' for (let index = 0; index < value.length; index += 1) binary += String.fromCharCode(value[index]!) return btoa(binary) } function base64ToBytes(value: string): Uint8Array { let binary: string try { binary = atob(value) } catch { throw invalidResponse('transfer data') } const bytes = new Uint8Array(binary.length) for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index) if (bytesToBase64(bytes) !== value) throw invalidResponse('transfer data') return bytes } function invalidResponse(part: string): RemoteGatewayError { return new RemoteGatewayError('INVALID_MESSAGE', `The Host returned an invalid Codex ${part}.`) } function codexStreamCloseReason(value: unknown): CodexAppStreamClosedData['reason'] { return value === 'cancelled' || value === 'completed' || value === 'failed' || value === 'peer-disconnected' ? value : 'failed' } function createCodexTransferId(): string { if (globalThis.crypto?.randomUUID !== undefined) return globalThis.crypto.randomUUID() const bytes = new Uint8Array(16) if (globalThis.crypto?.getRandomValues !== undefined) { globalThis.crypto.getRandomValues(bytes) } else { for (let index = 0; index < bytes.length; index += 1) bytes[index] = Math.floor(Math.random() * 256) } bytes[6] = (bytes[6]! & 0x0f) | 0x40 bytes[8] = (bytes[8]! & 0x3f) | 0x80 const hex = [...bytes].map(value => value.toString(16).padStart(2, '0')).join('') return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` } function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) }