dsh-lcx-codex 0.3.3 → 0.4.0-rc.13

package/lib/json-store.js

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export class JsonStore {
+  constructor(file, empty, validate, corruptCode = 'LCX_STORE_CORRUPT') {
+    this.file = file
+    this.empty = empty
+    this.validate = validate
+    this.corruptCode = corruptCode
+    this.data = empty()
+    this.refresh()
+  }
+  refresh() {
+    try {
+      const parsed = JSON.parse(readFileSync(this.file, 'utf8'))
+      if (!this.validate(parsed)) throw new Error('invalid store')
+      this.data = parsed
+    } catch (error) {
+      if (error?.code === 'ENOENT') { this.data = this.empty(); return }
+      const wrapped = new Error(`Invalid LCX store ${this.file}`, { cause: error }); wrapped.code = this.corruptCode; throw wrapped
+    }
+  }
+  update(mutator) {
+    this.refresh()
+    const next = mutator(structuredClone(this.data))
+    if (!this.validate(next)) throw new Error(`Refusing to write invalid LCX store ${this.file}`)
+    mkdirSync(dirname(this.file), { recursive: true })
+    const tmp = `${this.file}.${process.pid}.tmp`
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 })
+    try { chmodSync(tmp, 0o600) } catch {}
+    renameSync(tmp, this.file)
+    this.data = next
+  }
+}

package/lib/legacy-v3.js

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs'
+import { baseURLFingerprint, sessionAncestry } from './route.js'
+
+const PATTERN = /\[dsh-lcx-codex-v3-checkpoint:([0-9a-f-]{36})\]/iu
+function textOf(message) { return (message?.content ?? []).filter((b) => b?.type === 'text').map((b) => b.text).join('') }
+export function legacyV3Id(message) { return textOf(message).match(PATTERN)?.[1]?.toLowerCase() }
+export function loadLegacyRecord(file, id) {
+  if (!file || !id) return undefined
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    const record = parsed?.version === 3 ? parsed.checkpoints?.[id] : undefined
+    if (!record || record.version !== 3 || !Array.isArray(record.nativeOutput)) return undefined
+    return structuredClone(record)
+  } catch { return undefined }
+}
+export function legacyRouteCompatible(record, route, ctx) {
+  if (!record || record.provider !== route.provider || record.model !== route.model) return false
+  if (record.baseURLFingerprint !== baseURLFingerprint(route.baseURL)) return false
+  return sessionAncestry(ctx, route.sessionId).includes(record.sourceSessionId ?? record.lineageId)
+}

package/lib/native-checkpoint.js

@@ -0,0 +1,93 @@
+import { baseURLFingerprint, routeCompatible } from './route.js'
+import { persistNativeImageReferences } from './dsh-responses.js'
+
+export const NATIVE_BLOCK_TYPE = 'lcx-native-compaction-v5'
+export const NATIVE_BLOCK_VERSION = 5
+export const LEGACY_V4_BLOCK_TYPE = 'lcx-native-compaction-v4'
+export const LEGACY_V4_BLOCK_VERSION = 4
+const LEGACY_V3_PATTERN = /\[dsh-lcx-codex-v3-checkpoint:([0-9a-f-]{36})\]/iu
+
+export const RETAINED_MESSAGE_TOKEN_BUDGET = 64_000
+export const ASSISTANT_RETENTION_TOKEN_RESERVE = 24_000
+export const ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP = 3_000
+
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+function textOf(message) { return (message?.content ?? []).filter((b) => b?.type === 'text').map((b) => b.text).join('') }
+function estimatedItemTokens(item) { try { return Math.max(1, Math.ceil(JSON.stringify(item).length / 4)) } catch { return RETAINED_MESSAGE_TOKEN_BUDGET + 1 } }
+function isRetainedClientItem(item) { return isObject(item) && (item.type === undefined || item.type === 'message') && ['user', 'developer', 'system'].includes(String(item.role ?? '')) }
+function assistantTextParts(item) { if (!isObject(item) || item.type !== 'message' || item.role !== 'assistant' || !Array.isArray(item.content)) return []; return item.content.filter((part) => part?.type === 'output_text' && typeof part.text === 'string' && part.text.length > 0) }
+function isRetainedAssistantItem(item) { return assistantTextParts(item).length > 0 }
+function assistantText(item) { return assistantTextParts(item).map((part) => part.text).join('') }
+
+function truncateVisibleAssistantItem(item, maxTokens = ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP) {
+  const text = assistantText(item); if (!text) return undefined
+  const maxChars = Math.max(256, maxTokens * 4); let retained = text
+  if (text.length > maxChars) { const marker = '\n…[LCX retained answer truncated]…\n'; const available = Math.max(0, maxChars - marker.length); const head = Math.floor(available * 0.72); const tail = available - head; retained = `${text.slice(0, head)}${marker}${text.slice(Math.max(head, text.length - tail))}` }
+  return { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: retained }] }
+}
+
+function selectNewest(candidates, budget, transform = (value) => structuredClone(value.item)) {
+  const selected = []; let used = 0
+  for (let index = candidates.length - 1; index >= 0; index -= 1) { const candidate = candidates[index]; const item = transform(candidate); if (!item) continue; const tokens = estimatedItemTokens(item); if (tokens > budget || used + tokens > budget) continue; selected.push({ index: candidate.index, item, tokens }); used += tokens }
+  return { selected, used }
+}
+
+export function retainedCompactionInput(input, options = {}) {
+  const budget = Number.isSafeInteger(options.tokenBudget) && options.tokenBudget > 0 ? options.tokenBudget : RETAINED_MESSAGE_TOKEN_BUDGET
+  const candidates = (input ?? []).map((item, index) => ({ item, index })).filter(({ item }) => isRetainedClientItem(item))
+  return selectNewest(candidates, budget).selected.sort((a, b) => a.index - b.index).map(({ item }) => item)
+}
+
+export function retainedConversationPlan(input, options = {}) {
+  const totalBudget = Number.isSafeInteger(options.tokenBudget) && options.tokenBudget > 0 ? options.tokenBudget : RETAINED_MESSAGE_TOKEN_BUDGET
+  const assistantReserve = Math.min(totalBudget, Number.isSafeInteger(options.assistantTokenReserve) && options.assistantTokenReserve >= 0 ? options.assistantTokenReserve : ASSISTANT_RETENTION_TOKEN_RESERVE)
+  const perMessageCap = Number.isSafeInteger(options.assistantPerMessageTokenCap) && options.assistantPerMessageTokenCap > 0 ? options.assistantPerMessageTokenCap : ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP
+  const indexed = (input ?? []).map((item, index) => ({ item, index }))
+  const assistant = selectNewest(indexed.filter(({ item }) => isRetainedAssistantItem(item)), assistantReserve, ({ item }) => truncateVisibleAssistantItem(item, perMessageCap))
+  const remaining = Math.max(0, totalBudget - assistant.used)
+  const client = selectNewest(indexed.filter(({ item }) => isRetainedClientItem(item)), remaining)
+  const selected = [...client.selected, ...assistant.selected].sort((a, b) => a.index - b.index)
+  return { items: selected.map(({ item }) => item), clientCount: client.selected.length, assistantCount: assistant.selected.length, estimatedTokens: client.used + assistant.used, clientEstimatedTokens: client.used, assistantEstimatedTokens: assistant.used }
+}
+export function retainedConversationInput(input, options = {}) { return retainedConversationPlan(input, options).items }
+export function hasRetainedCompactionInput(items) { return (items ?? []).some((item) => isRetainedClientItem(item) || isRetainedAssistantItem(item)) }
+export function compactCheckpointId(message) { const source = message?.source; return source?.kind === 'plugin' && source?.plugin === 'compact' && typeof source.compactionId === 'string' && source.compactionId ? source.compactionId : undefined }
+export function legacyCheckpointId(message) { return textOf(message).match(LEGACY_V3_PATTERN)?.[1]?.toLowerCase() }
+export function activeCompactionId(session) { if (!session?.events) return undefined; const ended = new Set(); for (let index = session.events.length - 1; index >= 0; index -= 1) { const event = session.events[index]; if (event.type === 'compaction/end' && event.data?.compactionId) ended.add(event.data.compactionId); if (event.type === 'compaction/start' && event.data?.compactionId && !ended.has(event.data.compactionId)) return event.data.compactionId } return undefined }
+
+export function createNativeCheckpointBlock({ session, route, result, input = [], imageMap, retentionOptions = {} }) {
+  const compactionId = activeCompactionId(session)
+  if (!compactionId) { const error = new Error('Native compaction could not correlate the active DSH compaction transaction'); error.code = 'LCX_COMPACTION_ID_UNAVAILABLE'; throw error }
+  const retention = retainedConversationPlan(input, retentionOptions)
+  const nativeOutput = persistNativeImageReferences([...retention.items, structuredClone(result.compaction)], imageMap)
+  return { type: NATIVE_BLOCK_TYPE, version: NATIVE_BLOCK_VERSION, retentionPolicy: 'conversation-fidelity-v1', compactionId, provider: route.provider, model: route.model, baseURLFingerprint: baseURLFingerprint(route.baseURL), sourceSessionId: route.sessionId, nativeOutput, nativeCompaction: structuredClone(result.compaction), retainedInputCount: retention.items.length, retainedClientCount: retention.clientCount, retainedAssistantCount: retention.assistantCount, retainedEstimatedTokens: retention.estimatedTokens, createdAt: Date.now() }
+}
+
+export function nativeCheckpointChunks(block, usage) {
+  const text = 'LCX Native V2 checkpoint saved in the DSH session log.'
+  return [{ type: 'block-start', index: 0, blockType: 'text' }, { type: 'text-delta', index: 0, text }, { type: 'block-end', index: 0, block: { type: 'text', text } }, { type: 'block-start', index: 1, blockType: NATIVE_BLOCK_TYPE }, { type: 'block-end', index: 1, block: structuredClone(block) }, ...(usage ? [{ type: 'usage', usage: structuredClone(usage) }] : []), { type: 'finish', reason: { kind: 'stop' } }]
+}
+
+export function compactionSummaryEvent(session, compactionId) { if (!session?.events || !compactionId) return undefined; for (let index = session.events.length - 1; index >= 0; index -= 1) { const event = session.events[index]; if (event.type === 'compaction/summary' && event.data?.compactionId === compactionId) return event } return undefined }
+function nativeBlockFromSummary(event) { const raw = event?.data?.rawOutput ?? []; return raw.find((value) => value?.type === NATIVE_BLOCK_TYPE && value?.version === NATIVE_BLOCK_VERSION) ?? raw.find((value) => value?.type === LEGACY_V4_BLOCK_TYPE && value?.version === LEGACY_V4_BLOCK_VERSION) }
+function validateCount(value) { return value === undefined || (Number.isSafeInteger(value) && value >= 0) }
+export function stateFromSummaryEvent(event) {
+  if (event?.type !== 'compaction/summary') return undefined
+  const block = nativeBlockFromSummary(event); if (!isObject(block)) return undefined
+  if (block.compactionId !== event.data.compactionId || !Array.isArray(block.nativeOutput) || block.nativeOutput.length === 0) return undefined
+  if (typeof block.provider !== 'string' || typeof block.model !== 'string' || typeof block.baseURLFingerprint !== 'string' || typeof block.sourceSessionId !== 'string') return undefined
+  if (!validateCount(block.retainedInputCount) || !validateCount(block.retainedClientCount) || !validateCount(block.retainedAssistantCount)) return undefined
+  const compactions = block.nativeOutput.filter((item) => item?.type === 'compaction'); if (compactions.length !== 1 || typeof compactions[0]?.encrypted_content !== 'string') return undefined
+  const compactionIndex = block.nativeOutput.findIndex((item) => item?.type === 'compaction'); const prefix = compactionIndex >= 0 ? block.nativeOutput.slice(0, compactionIndex) : []
+  if (block.version === NATIVE_BLOCK_VERSION) { const clients = prefix.filter(isRetainedClientItem).length; const assistants = prefix.filter(isRetainedAssistantItem).length; const total = clients + assistants; if (block.retainedInputCount !== undefined && block.retainedInputCount !== total) return undefined; if (block.retainedClientCount !== undefined && block.retainedClientCount !== clients) return undefined; if (block.retainedAssistantCount !== undefined && block.retainedAssistantCount !== assistants) return undefined } else { const clients = prefix.filter(isRetainedClientItem).length; if (block.retainedInputCount !== undefined && block.retainedInputCount !== clients) return undefined }
+  return structuredClone(block)
+}
+export function checkpointStateForMessage(session, message) { const id = compactCheckpointId(message); return id ? stateFromSummaryEvent(compactionSummaryEvent(session, id)) : undefined }
+export function stateRouteCompatible(state, route, ctx) { return routeCompatible(state, route, ctx) }
+function eventMessage(session, seq) { const events = session?.events ?? []; const event = events[seq]?.seq === seq ? events[seq] : events.find((candidate) => candidate?.seq === seq); if (!event) return undefined; if (typeof session.deriveEventMessage === 'function') return session.deriveEventMessage(event) ?? undefined; if (event.type === 'user/message') return event.data; if (event.type === 'assistant/message') return event.data?.message; if (event.type === 'tool/result') return event.data?.message; return undefined }
+function estimateChars(message) { try { return JSON.stringify(message).length } catch { return 0 } }
+function expandedCheckpointMessages(session, compactionId, visited, depth) { if (depth > 16 || visited.has(compactionId)) return []; visited.add(compactionId); const summary = compactionSummaryEvent(session, compactionId); if (!summary) return []; const result = []; for (const seq of summary.data?.shadowedSeqs ?? []) { const message = eventMessage(session, seq); if (!message) continue; const nested = compactCheckpointId(message); if (nested) result.push(...expandedCheckpointMessages(session, nested, visited, depth + 1)); else result.push(structuredClone(message)) } return result }
+export function shadowedMessagesForCheckpoint(session, compactionId) { return expandedCheckpointMessages(session, compactionId, new Set(), 0) }
+function groupMessages(messages) { const groups = []; for (let index = 0; index < messages.length; index += 1) { const message = messages[index]; const toolCalls = message?.role === 'assistant' ? (message.content ?? []).filter((b) => b?.type === 'tool-call').map((b) => String(b.id)) : []; if (toolCalls.length === 0) { groups.push([message]); continue } const group = [message]; const pending = new Set(toolCalls); let cursor = index + 1; while (cursor < messages.length && pending.size > 0) { const next = messages[cursor]; const results = next?.role === 'user' ? (next.content ?? []).filter((b) => b?.type === 'tool-result').map((b) => String(b.toolCallId)) : []; if (results.length === 0) break; group.push(next); for (const id of results) pending.delete(id); cursor += 1 } if (pending.size === 0) index = cursor - 1; groups.push(group) } return groups }
+export function portableMessagesForCheckpoint(session, compactionId, options = {}) { const maxChars = Number.isSafeInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : 80_000; const expanded = shadowedMessagesForCheckpoint(session, compactionId); if (expanded.length === 0) return []; const groups = groupMessages(expanded); const kept = []; let chars = 0; for (let index = groups.length - 1; index >= 0; index -= 1) { const group = groups[index]; const size = group.reduce((sum, message) => sum + estimateChars(message), 0); if (kept.length > 0 && chars + size > maxChars) break; kept.unshift(...group); chars += size } return kept }
+export function rewriteCheckpointsPortable(messages, session, options = {}) { const rewritten = []; let changed = false; for (const message of messages ?? []) { const id = compactCheckpointId(message); if (!id || !checkpointStateForMessage(session, message)) { rewritten.push(message); continue } const portable = portableMessagesForCheckpoint(session, id, options); if (portable.length === 0) { rewritten.push(message); continue } rewritten.push(...portable); changed = true } return changed ? rewritten : messages }

package/lib/responses-replay.js

@@ -0,0 +1,281 @@
+import { fetchSseWithRetry } from './transport.js'
+import { mergeFeatureHeader, responsesGenerationEnvelope } from './compact-v2.js'
+import { responsesTools } from './dsh-responses.js'
+
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+function fail(message, code = 'LCX_RESPONSES_UPSTREAM_ERROR') { const e = new Error(message); e.code = code; return e }
+
+function usageFrom(raw) {
+  if (!isObject(raw)) return undefined
+  const inputTotal = Number(raw.input_tokens ?? 0)
+  const output = Number(raw.output_tokens ?? 0)
+  const details = raw.input_tokens_details ?? raw.input_token_details ?? raw.prompt_tokens_details ?? {}
+  const cacheRead = Number(details.cached_tokens ?? 0)
+  const cacheWrite = Number(details.cache_write_tokens ?? 0)
+  const usage = {
+    inputTokens: Math.max(0, Number.isFinite(inputTotal) ? inputTotal - (Number.isFinite(cacheRead) ? cacheRead : 0) - (Number.isFinite(cacheWrite) ? cacheWrite : 0) : 0),
+    outputTokens: Number.isFinite(output) && output > 0 ? output : 0,
+  }
+  if (Number.isFinite(cacheRead) && cacheRead > 0) usage.cacheReadTokens = cacheRead
+  if (Number.isFinite(cacheWrite) && cacheWrite > 0) usage.cacheWriteTokens = cacheWrite
+  const reasoning = Number(raw.output_tokens_details?.reasoning_tokens ?? raw.output_token_details?.reasoning_tokens ?? 0)
+  if (Number.isFinite(reasoning) && reasoning > 0) usage.reasoningTokens = reasoning
+  return usage
+}
+
+async function* sseEvents(response, options = {}) {
+  if (!response?.body) throw fail('Responses replay returned no SSE body', 'LCX_INVALID_SSE')
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let pending = ''
+  let dataLines = []
+  let bytes = 0
+  const maxBytes = options.maxResponseBytes ?? 8 * 1024 * 1024
+  const decodeEvent = () => {
+    if (dataLines.length === 0) return undefined
+    const data = dataLines.join('\n')
+    dataLines = []
+    if (data === '[DONE]') return undefined
+    try { return JSON.parse(data) } catch (cause) { throw fail(`malformed Responses SSE JSON: ${cause}`, 'LCX_INVALID_SSE') }
+  }
+  try {
+    while (true) {
+      if (options.signal?.aborted) throw options.signal.reason ?? fail('request aborted', 'LCX_ABORTED')
+      const { done, value } = await reader.read()
+      if (done) break
+      bytes += value.byteLength
+      if (bytes > maxBytes) throw fail(`Responses SSE exceeds ${maxBytes} bytes`, 'LCX_RESPONSE_TOO_LARGE')
+      pending += decoder.decode(value, { stream: true })
+      let newline
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        const line = pending.slice(0, newline).replace(/\r$/u, '')
+        pending = pending.slice(newline + 1)
+        if (line === '') {
+          const event = decodeEvent()
+          if (event) yield event
+        } else if (!line.startsWith(':') && line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^ /u, ''))
+      }
+    }
+    pending += decoder.decode()
+    if (pending.startsWith('data:')) dataLines.push(pending.slice(5).replace(/^ /u, ''))
+    const event = decodeEvent()
+    if (event) yield event
+  } finally {
+    await reader.cancel().catch(() => undefined)
+  }
+}
+
+function streamError(event) {
+  const e = fail(`Responses stream ended with ${String(event?.type)}`)
+  if (Number.isInteger(event?.error?.status)) e.status = event.error.status
+  return e
+}
+
+function textSignature(itemId, phase) {
+  if (typeof itemId !== 'string' || itemId.length === 0) return undefined
+  const value = { v: 1, id: itemId }
+  if (phase === 'commentary' || phase === 'final_answer') value.phase = phase
+  return JSON.stringify(value)
+}
+
+function replayBlockFor(item, fallbackKind) {
+  const kind = item?.kind ?? fallbackKind
+  if (kind === 'text') {
+    const signature = textSignature(item?.itemId, item?.phase)
+    return { type: 'text', ...(signature ? { textSignature: signature } : {}) }
+  }
+  if (kind === 'reasoning') {
+    const signature = isObject(item?.rawItem) ? JSON.stringify(item.rawItem) : undefined
+    return { type: 'reasoning', ...(signature ? { thinkingSignature: signature } : {}) }
+  }
+  return { type: 'tool-call' }
+}
+
+function replayStopReason(reason) {
+  if (reason?.kind === 'tool-calls') return 'toolUse'
+  if (reason?.kind === 'max-tokens') return 'length'
+  if (reason?.kind === 'error') return 'error'
+  if (reason?.kind === 'aborted') return 'aborted'
+  return 'stop'
+}
+function dshToolCallId(callId, itemId) {
+  const call = typeof callId === 'string' && callId.length > 0 ? callId : undefined
+  const item = typeof itemId === 'string' && itemId.length > 0 ? itemId : undefined
+  if (call && item) return `${call}|${item}`
+  return call ?? item ?? ''
+}
+
+export function replayBody({ model, input, system, tools, promptCacheKey, promptCacheRetention, reasoningEffort, temperature, maxTokens }) {
+  return {
+    model,
+    input: structuredClone(input),
+    stream: true,
+    store: false,
+    tool_choice: 'auto',
+    parallel_tool_calls: true,
+    ...(system !== undefined ? { instructions: system } : {}),
+    ...(tools !== undefined ? { tools: responsesTools(tools) } : {}),
+    ...(promptCacheKey ? { prompt_cache_key: String(promptCacheKey) } : {}),
+    ...(promptCacheRetention ? { prompt_cache_retention: String(promptCacheRetention) } : {}),
+    ...responsesGenerationEnvelope({ reasoningEffort, temperature, maxTokens }),
+  }
+}
+
+export async function* requestNativeReplay({ baseURL, provider, model, input, system, tools, promptCacheKey, promptCacheRetention, reasoningEffort, temperature, maxTokens, headers, signal, timeoutMs, maxAttempts, maxResponseBytes }) {
+  const response = await fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, '')}/responses`, replayBody({ model, input, system, tools, promptCacheKey, promptCacheRetention, reasoningEffort, temperature, maxTokens }), mergeFeatureHeader(headers), signal, timeoutMs, { maxAttempts, maxResponseBytes })
+  const records = []
+  const byStreamIdentity = new Map()
+  let nextIndex = 0
+  let terminal
+  const identity = (kind, itemId, partIndex) => itemId === undefined ? undefined : `${kind}:${String(itemId)}:${partIndex ?? 0}`
+  const createRecord = (kind, streamIdentity, outputIndex, partIndex) => {
+    const existing = streamIdentity === undefined ? undefined : byStreamIdentity.get(streamIdentity)
+    if (existing) return { record: existing, created: false }
+    const record = { kind, index: nextIndex++, outputIndex, partIndex, streamIdentity, text: '', arguments: '', name: '', callId: undefined, itemId: undefined, terminal: undefined }
+    records.push(record)
+    if (streamIdentity !== undefined) byStreamIdentity.set(streamIdentity, record)
+    return { record, created: true }
+  }
+  for await (const event of sseEvents(response, { signal, maxResponseBytes })) {
+    if (!isObject(event)) continue
+    if (event.type === 'error' || event.type === 'response.failed' || event.type === 'response.incomplete') throw streamError(event)
+    if (event.type === 'response.output_text.delta') {
+      const itemId = typeof event.item_id === 'string' ? event.item_id : undefined
+      const key = identity('text', itemId, event.content_index)
+      const allocated = createRecord('text', key ?? `text:index:${event.output_index ?? ''}:${event.content_index ?? ''}`, event.output_index, event.content_index)
+      const record = allocated.record
+      if (allocated.created) yield { type: 'block-start', index: record.index, blockType: 'text' }
+      if (typeof event.delta === 'string' && event.delta) { record.text += event.delta; yield { type: 'text-delta', index: record.index, text: event.delta } }
+      continue
+    }
+    if (event.type === 'response.reasoning_summary_text.delta' || event.type === 'response.reasoning_text.delta') {
+      const itemId = typeof event.item_id === 'string' ? event.item_id : undefined
+      const key = identity('reasoning', itemId, event.summary_index ?? event.content_index)
+      const allocated = createRecord('reasoning', key ?? `reasoning:index:${event.output_index ?? ''}:${event.summary_index ?? event.content_index ?? ''}`, event.output_index, event.summary_index ?? event.content_index)
+      const record = allocated.record
+      if (allocated.created) yield { type: 'block-start', index: record.index, blockType: 'reasoning' }
+      if (typeof event.delta === 'string' && event.delta) { record.text += event.delta; yield { type: 'reasoning-delta', index: record.index, text: event.delta } }
+      continue
+    }
+    if (event.type === 'response.function_call_arguments.delta') {
+      const itemId = typeof event.item_id === 'string' ? event.item_id : undefined
+      const callId = typeof event.call_id === 'string' ? event.call_id : itemId ?? `call-${event.output_index ?? nextIndex}`
+      const key = identity('tool-call', typeof event.item_id === 'string' ? event.item_id : callId, 0) ?? `tool-call:${callId}`
+      const allocated = createRecord('tool-call', key, event.output_index, 0)
+      const record = allocated.record
+      record.callId = callId
+      record.itemId = itemId
+      if (typeof event.name === 'string') record.name = event.name
+      if (allocated.created) yield { type: 'block-start', index: record.index, blockType: 'tool-call' }
+      const delta = typeof event.delta === 'string' ? event.delta : ''
+      record.arguments += delta
+      yield { type: 'tool-call-delta', index: record.index, id: dshToolCallId(callId, itemId), ...(record.name ? { name: record.name } : {}), argumentsDelta: delta }
+      continue
+    }
+    if (event.type === 'response.output_item.added' && event.item?.type === 'function_call') {
+      const itemId = typeof event.item.id === 'string' ? event.item.id : undefined
+      const callId = typeof event.item.call_id === 'string' ? event.item.call_id : itemId ?? `call-${event.output_index ?? nextIndex}`
+      const key = identity('tool-call', itemId ?? callId, 0) ?? `tool-call:${callId}`
+      const allocated = createRecord('tool-call', key, event.output_index, 0)
+      const record = allocated.record
+      record.callId = callId
+      record.itemId = itemId
+      record.name = typeof event.item.name === 'string' ? event.item.name : record.name
+      if (allocated.created) {
+        yield { type: 'block-start', index: record.index, blockType: 'tool-call' }
+        if (typeof event.item.arguments === 'string' && event.item.arguments) { record.arguments = event.item.arguments; yield { type: 'tool-call-delta', index: record.index, id: dshToolCallId(callId, itemId), ...(record.name ? { name: record.name } : {}), argumentsDelta: event.item.arguments } }
+      }
+      continue
+    }
+    if (event.type === 'response.output_item.done' && event.item?.type === 'function_call') {
+      const itemId = typeof event.item.id === 'string' ? event.item.id : undefined
+      const callId = typeof event.item.call_id === 'string' ? event.item.call_id : itemId ?? `call-${event.output_index ?? nextIndex}`
+      const key = identity('tool-call', itemId ?? callId, 0) ?? `tool-call:${callId}`
+      const allocated = createRecord('tool-call', key, event.output_index, 0)
+      const record = allocated.record
+      record.callId = callId
+      record.itemId = itemId
+      record.name = typeof event.item.name === 'string' ? event.item.name : record.name
+      const completedArguments = typeof event.item.arguments === 'string' ? event.item.arguments : record.arguments
+      if (allocated.created) {
+        yield { type: 'block-start', index: record.index, blockType: 'tool-call' }
+        if (completedArguments) yield { type: 'tool-call-delta', index: record.index, id: dshToolCallId(callId, itemId), ...(record.name ? { name: record.name } : {}), argumentsDelta: completedArguments }
+      }
+      record.arguments = completedArguments
+      continue
+    }
+    if (event.type === 'response.completed') terminal = event.response
+  }
+  if (!isObject(terminal)) throw fail('Responses replay ended without response.completed', 'LCX_RESPONSES_INCOMPLETE')
+  if (terminal.status !== 'completed') throw fail('Responses replay response.completed did not carry completed status', 'LCX_RESPONSES_INCOMPLETE')
+
+  const terminalItems = []
+  for (const [outputIndex, item] of (terminal.output ?? []).entries()) {
+    if (item?.type === 'message') {
+      for (const [contentIndex, part] of (item.content ?? []).entries()) if (part?.type === 'output_text') terminalItems.push({ kind: 'text', outputIndex, partIndex: contentIndex, itemId: item.id, phase: item.phase, text: String(part.text ?? ''), rawItem: item })
+    } else if (item?.type === 'reasoning') {
+      const parts = Array.isArray(item.summary) && item.summary.length ? item.summary : item.content ?? []
+      parts.forEach((part, index) => { if (typeof part?.text === 'string') terminalItems.push({ kind: 'reasoning', outputIndex, partIndex: index, itemId: item.id, text: part.text, rawItem: item }) })
+    } else if (item?.type === 'function_call') {
+      terminalItems.push({ kind: 'tool-call', outputIndex, partIndex: 0, itemId: item.id, callId: item.call_id, name: String(item.name ?? ''), arguments: String(item.arguments ?? ''), rawItem: item })
+    }
+  }
+  const matched = new Set()
+  const matchesRecord = (item) => {
+    const stable = identity(item.kind, item.itemId ?? item.callId, item.partIndex)
+    if (stable) {
+      const exact = records.find((record) => !matched.has(record) && record.kind === item.kind && (record.streamIdentity === stable || (item.kind === 'tool-call' && record.callId === item.callId)))
+      if (exact) return exact
+    }
+    const candidates = records.filter((record) => !matched.has(record) && record.kind === item.kind)
+    if (candidates.length === 1) return candidates[0]
+    const contentMatches = candidates.filter((record) => item.kind === 'tool-call'
+      ? record.callId === item.callId || (item.arguments && record.arguments && (item.arguments.startsWith(record.arguments) || record.arguments.startsWith(item.arguments)))
+      : item.text !== undefined && record.text && (item.text === record.text || item.text.startsWith(record.text) || record.text.startsWith(item.text)))
+    return contentMatches.length === 1 ? contentMatches[0] : undefined
+  }
+  for (const item of terminalItems) {
+    const record = matchesRecord(item)
+    if (!record) continue
+    matched.add(record)
+    record.terminal = item
+  }
+  const replayBlocks = []
+  for (const record of records) {
+    const item = record.terminal
+    replayBlocks[record.index] = replayBlockFor(item, record.kind)
+    if (record.kind === 'text') yield { type: 'block-end', index: record.index, block: { type: 'text', text: item?.text ?? record.text } }
+    else if (record.kind === 'reasoning') yield { type: 'block-end', index: record.index, block: { type: 'reasoning', text: item?.text ?? record.text } }
+    else yield { type: 'block-end', index: record.index, block: { type: 'tool-call', id: dshToolCallId(item?.callId ?? record.callId, item?.itemId ?? record.itemId), name: item?.name ?? record.name, arguments: item?.arguments ?? record.arguments } }
+  }
+  for (const item of terminalItems) {
+    const record = records.find((candidate) => candidate.terminal === item)
+    if (record) continue
+    if (item.kind === 'text' && !item.text) continue
+    const index = nextIndex++
+    replayBlocks[index] = replayBlockFor(item, item.kind)
+    yield { type: 'block-start', index, blockType: item.kind === 'tool-call' ? 'tool-call' : item.kind }
+    if (item.kind === 'text' && item.text) yield { type: 'text-delta', index, text: item.text }
+    if (item.kind === 'reasoning' && item.text) yield { type: 'reasoning-delta', index, text: item.text }
+    if (item.kind === 'tool-call') yield { type: 'tool-call-delta', index, id: dshToolCallId(item.callId, item.itemId), name: item.name, argumentsDelta: item.arguments }
+    yield { type: 'block-end', index, block: item.kind === 'text' ? { type: 'text', text: item.text } : item.kind === 'reasoning' ? { type: 'reasoning', text: item.text } : { type: 'tool-call', id: dshToolCallId(item.callId, item.itemId), name: item.name, arguments: item.arguments } }
+  }
+  const usage = usageFrom(terminal.usage)
+  if (usage) yield { type: 'usage', usage }
+  const reason = terminal.status === 'incomplete'
+    ? { kind: 'max-tokens' }
+    : terminal.error ? { kind: 'error', failure: { message: terminal.error.message ?? 'Responses error', code: 'LCX_RESPONSES_UPSTREAM_ERROR' } }
+      : terminalItems.some((item) => item.kind === 'tool-call') ? { kind: 'tool-calls' } : { kind: 'stop' }
+  const replayState = typeof provider === 'string' && provider.length > 0 && typeof model === 'string' && model.length > 0
+    ? {
+        response: {
+          kind: 'pi-ai', version: 2, api: 'openai-responses', provider, model,
+          ...(typeof terminal.model === 'string' && terminal.model.length > 0 ? { responseModel: terminal.model } : {}),
+          ...(typeof terminal.id === 'string' && terminal.id.length > 0 ? { responseId: terminal.id } : {}),
+          stopReason: replayStopReason(reason),
+        },
+        blocks: Array.from({ length: nextIndex }, (_, index) => replayBlocks[index] ?? { type: records.find((record) => record.index === index)?.kind ?? 'text' }),
+      }
+    : undefined
+  yield { type: 'finish', reason, ...(replayState ? { replayState } : {}) }
+}