From 9f539adeb454393d05047e8f51f5828d847feb6f Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 14:44:15 +0800 Subject: [PATCH] Import packages/client-core/src/codex-client.ts --- packages/client-core/src/codex-client.ts | 1099 ++++++++++++++++++++++ 1 file changed, 1099 insertions(+) create mode 100644 packages/client-core/src/codex-client.ts diff --git a/packages/client-core/src/codex-client.ts b/packages/client-core/src/codex-client.ts new file mode 100644 index 0000000..c80a159 --- /dev/null +++ b/packages/client-core/src/codex-client.ts @@ -0,0 +1,1099 @@ +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) +}