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

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 === '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,191 @@
+import { fetchSseWithRetry } from './transport.js'
+import { mergeFeatureHeader } 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 message = event?.error?.message ?? event?.response?.error?.message ?? `Responses stream ended with ${String(event?.type)}`
+  const e = fail(message)
+  if (Number.isInteger(event?.error?.status)) e.status = event.error.status
+  return e
+}
+
+export function replayBody({ model, input, system, tools, promptCacheKey }) {
+  return {
+    model,
+    input: structuredClone(input),
+    stream: true,
+    store: false,
+    ...(system !== undefined ? { instructions: system } : {}),
+    ...(tools !== undefined ? { tools: responsesTools(tools) } : {}),
+    ...(promptCacheKey ? { prompt_cache_key: String(promptCacheKey) } : {}),
+  }
+}
+
+export async function* requestNativeReplay({ baseURL, model, input, system, tools, promptCacheKey, headers, signal, timeoutMs, maxAttempts, maxResponseBytes }) {
+  const response = await fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, '')}/responses`, replayBody({ model, input, system, tools, promptCacheKey }), mergeFeatureHeader(headers), signal, timeoutMs, { maxAttempts, maxResponseBytes })
+  const textIndexes = new Map()
+  const reasoningIndexes = new Map()
+  const callIndexes = new Map()
+  let nextIndex = 0
+  let terminal
+  let finished = false
+  const allocate = (map, key, blockType) => {
+    if (map.has(key)) return { index: map.get(key), created: false }
+    const index = nextIndex++
+    map.set(key, index)
+    return { index, created: true, blockType }
+  }
+  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 key = `${event.output_index ?? ''}:${event.content_index ?? ''}`
+      const slot = allocate(textIndexes, key, 'text')
+      if (slot.created) yield { type: 'block-start', index: slot.index, blockType: 'text' }
+      if (typeof event.delta === 'string' && event.delta) yield { type: 'text-delta', index: slot.index, text: event.delta }
+      continue
+    }
+    if (event.type === 'response.reasoning_summary_text.delta' || event.type === 'response.reasoning_text.delta') {
+      const key = `${event.output_index ?? ''}:${event.summary_index ?? event.content_index ?? ''}`
+      const slot = allocate(reasoningIndexes, key, 'reasoning')
+      if (slot.created) yield { type: 'block-start', index: slot.index, blockType: 'reasoning' }
+      if (typeof event.delta === 'string' && event.delta) yield { type: 'reasoning-delta', index: slot.index, text: event.delta }
+      continue
+    }
+    if (event.type === 'response.function_call_arguments.delta') {
+      const callId = String(event.call_id ?? event.item_id ?? `call-${event.output_index ?? nextIndex}`)
+      const slot = allocate(callIndexes, callId, 'tool-call')
+      if (slot.created) yield { type: 'block-start', index: slot.index, blockType: 'tool-call' }
+      yield { type: 'tool-call-delta', index: slot.index, id: callId, ...(typeof event.name === 'string' ? { name: event.name } : {}), argumentsDelta: typeof event.delta === 'string' ? event.delta : '' }
+      continue
+    }
+    if (event.type === 'response.output_item.added' && event.item?.type === 'function_call') {
+      const callId = String(event.item.call_id ?? event.item.id ?? `call-${event.output_index ?? nextIndex}`)
+      const slot = allocate(callIndexes, callId, 'tool-call')
+      if (slot.created) {
+        yield { type: 'block-start', index: slot.index, blockType: 'tool-call' }
+        if (typeof event.item.name === 'string' || typeof event.item.arguments === 'string') {
+          yield { type: 'tool-call-delta', index: slot.index, id: callId, ...(typeof event.item.name === 'string' ? { name: event.item.name } : {}), argumentsDelta: typeof event.item.arguments === 'string' ? event.item.arguments : '' }
+        }
+      }
+      continue
+    }
+    if (event.type === 'response.completed' || event.type === 'response.done') {
+      terminal = event.response
+      continue
+    }
+  }
+  if (!isObject(terminal)) throw fail('Responses replay ended without response.completed', 'LCX_RESPONSES_INCOMPLETE')
+
+  // Close all blocks with a best-effort projection from the terminal response.
+  const terminalText = new Map()
+  const terminalReasoning = new Map()
+  const terminalCalls = new Map()
+  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') terminalText.set(`${outputIndex}:${contentIndex}`, String(part.text ?? ''))
+      }
+    } else if (item?.type === 'reasoning') {
+      const parts = Array.isArray(item.summary) && item.summary.length ? item.summary : item.content ?? []
+      parts.forEach((part, idx) => { if (typeof part?.text === 'string') terminalReasoning.set(`${outputIndex}:${idx}`, part.text) })
+    } else if (item?.type === 'function_call') {
+      const callId = String(item.call_id ?? item.id ?? `call-${outputIndex}`)
+      terminalCalls.set(callId, item)
+    }
+  }
+  for (const [key, index] of textIndexes) yield { type: 'block-end', index, block: { type: 'text', text: terminalText.get(key) ?? '' } }
+  for (const [key, index] of reasoningIndexes) yield { type: 'block-end', index, block: { type: 'reasoning', text: terminalReasoning.get(key) ?? '' } }
+  for (const [callId, index] of callIndexes) {
+    const item = terminalCalls.get(callId)
+    yield { type: 'block-end', index, block: { type: 'tool-call', id: callId, name: String(item?.name ?? ''), arguments: String(item?.arguments ?? '') } }
+  }
+
+  // Providers sometimes send no deltas for tiny answers; materialize unseen terminal blocks.
+  for (const [key, text] of terminalText) {
+    if (textIndexes.has(key)) continue
+    const index = nextIndex++
+    yield { type: 'block-start', index, blockType: 'text' }
+    if (text) yield { type: 'text-delta', index, text }
+    yield { type: 'block-end', index, block: { type: 'text', text } }
+  }
+  for (const [callId, item] of terminalCalls) {
+    if (callIndexes.has(callId)) continue
+    const index = nextIndex++
+    yield { type: 'block-start', index, blockType: 'tool-call' }
+    yield { type: 'tool-call-delta', index, id: callId, name: String(item.name ?? ''), argumentsDelta: String(item.arguments ?? '') }
+    yield { type: 'block-end', index, block: { type: 'tool-call', id: callId, name: String(item.name ?? ''), arguments: String(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' } }
+      : terminalCalls.size > 0 ? { kind: 'tool-calls' } : { kind: 'stop' }
+  yield { type: 'finish', reason }
+  finished = true
+  if (!finished) throw fail('Responses replay did not finish')
+}

package/lib/route.js

@@ -0,0 +1,137 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { attributionHeaders, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+export function normalizeBaseURL(value) {
+  return String(value ?? '').trim().replace(/\/+$/u, '')
+}
+
+export function isGptModel(model) {
+  return /(^|[^a-z])gpt(?:[^a-z]|$)/iu.test(String(model ?? ''))
+}
+
+export function baseURLFingerprint(baseURL) {
+  return createHash('sha256').update(normalizeBaseURL(baseURL), 'utf8').digest('hex')
+}
+
+export function routeFingerprint(route, options = {}) {
+  const includeSession = options.includeSession !== false
+  const fields = [route?.provider ?? '', route?.model ?? '', normalizeBaseURL(route?.baseURL), includeSession ? route?.sessionId ?? '' : '']
+  return createHash('sha256').update(fields.join('\u001f'), 'utf8').digest('hex')
+}
+
+export function promptCacheKey(route) {
+  if (!route?.sessionId) return undefined
+  // Stable per conversation + exact upstream route. It deliberately does not
+  // include the current checkpoint, so native compaction/replay keep one cache key.
+  return `dsh-lcx:${routeFingerprint(route)}`
+}
+
+function retryAttempts(policy, fallback = 3) {
+  if (!policy || typeof policy !== 'object') return fallback
+  try {
+    const resolved = resolveRetryPolicy(policy, 'llm-pi-ai provider retryPolicy')
+    if (resolved.mode === 'normal' && Number.isSafeInteger(resolved.maxRetries)) return Math.min(resolved.maxRetries + 1, 6)
+  } catch { /* keep fallback */ }
+  return fallback
+}
+
+export function settingsValue(ctx, namespace) {
+  const settings = ctx?.get?.('settings') ?? ctx?.settings
+  return settings?.get?.(settingsNamespace(namespace))
+}
+
+export function resolveResponsesRouteConfig(ctx, options, fallbackConfig) {
+  if (!isGptModel(options?.model)) return undefined
+  const provider = String(options?.provider ?? '')
+  const section = settingsValue(ctx, 'llm-pi-ai')
+  const profile = section?.providers?.[provider]
+  if (profile === undefined) {
+    if (provider !== fallbackConfig.provider) return undefined
+    return {
+      ...fallbackConfig,
+      provider,
+      model: String(options.model),
+      baseURL: normalizeBaseURL(fallbackConfig.baseURL),
+    }
+  }
+  if (profile.api !== 'openai-responses') return undefined
+  const baseURL = profile.baseURL ?? (provider === fallbackConfig.provider ? fallbackConfig.baseURL : undefined)
+  const apiKeyEnv = profile.apiKeyEnv ?? (provider === fallbackConfig.provider ? fallbackConfig.apiKeyEnv : undefined)
+  if (!baseURL || !apiKeyEnv) return undefined
+  return {
+    ...fallbackConfig,
+    provider,
+    model: String(options.model),
+    baseURL: normalizeBaseURL(baseURL),
+    apiKeyEnv,
+    headers: profile.headers && typeof profile.headers === 'object' ? { ...profile.headers } : { ...(fallbackConfig.headers ?? {}) },
+    timeoutMs: Number.isInteger(profile.timeoutMs) && profile.timeoutMs > 0 ? profile.timeoutMs : fallbackConfig.timeoutMs,
+    maxAttempts: retryAttempts(profile.retryPolicy, fallbackConfig.maxAttempts),
+    maxRequestImageBytes: Number.isSafeInteger(profile.maxRequestImageBytes) && profile.maxRequestImageBytes > 0
+      ? profile.maxRequestImageBytes
+      : fallbackConfig.maxRequestImageBytes,
+    requestImagePixelBudget: Number.isSafeInteger(profile.requestImagePixelBudget) && profile.requestImagePixelBudget > 0
+      ? profile.requestImagePixelBudget
+      : fallbackConfig.requestImagePixelBudget,
+    requestImageMaxBytes: Number.isSafeInteger(profile.requestImageMaxBytes) && profile.requestImageMaxBytes > 0
+      ? profile.requestImageMaxBytes
+      : fallbackConfig.requestImageMaxBytes,
+  }
+}
+
+export async function resolveApiKey(ctx, config) {
+  const credentials = ctx?.get?.('credentials') ?? ctx?.credentials
+  if (credentials?.resolve) {
+    const resolved = await credentials.resolve(config.apiKeyEnv)
+    if (typeof resolved?.value === 'string' && resolved.value.trim()) return resolved.value.trim()
+  }
+  const ambient = String(process.env[config.apiKeyEnv] ?? '').trim()
+  if (ambient) return ambient
+  const error = new Error(`DSH provider credential is unavailable: ${config.apiKeyEnv}`)
+  error.code = 'LCX_CREDENTIAL_UNAVAILABLE'
+  throw error
+}
+
+export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
+  return {
+    ...(config.headers ?? {}),
+    ...attributionHeaders(),
+    authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
+    'x-client-request-id': requestId ?? randomUUID(),
+    ...(sessionId ? { 'session-id': String(sessionId) } : {}),
+  }
+}
+
+export function currentRoute(options, config) {
+  return {
+    provider: String(options?.provider ?? config.provider ?? ''),
+    model: String(options?.model ?? config.model ?? ''),
+    baseURL: normalizeBaseURL(config.baseURL),
+    sessionId: String(options?.sessionId ?? ''),
+  }
+}
+
+export function sessionAncestry(ctx, sessionId) {
+  if (!sessionId) return []
+  const sessions = ctx?.get?.('sessions') ?? ctx?.sessions
+  const result = []
+  const seen = new Set()
+  let current = sessions?.get?.(sessionId)
+  while (current && !seen.has(current.id)) {
+    seen.add(current.id)
+    result.push(String(current.id))
+    const parent = current.header?.parentSession
+    if (!parent) break
+    current = sessions?.get?.(parent)
+  }
+  return result
+}
+
+export function routeCompatible(record, route, ctx) {
+  if (!record || ![4, 5].includes(record.version)) return false
+  if (record.provider !== route.provider || record.model !== route.model) return false
+  if (record.baseURLFingerprint !== baseURLFingerprint(route.baseURL)) return false
+  const ancestry = sessionAncestry(ctx, route.sessionId)
+  return ancestry.includes(record.sourceSessionId)
+}