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

package/lib/compact-v2.js

@@ -1,307 +1,119 @@
-import { normalizeCompactionResponse } from './compact.js'
-import { fetchSseWithRetry } from './transport.js'
+import { consumeSse, fetchSseWithRetry } from './transport.js'
+import { responsesTools } from './dsh-responses.js'
 
-const REMOTE_COMPACTION_V2_FEATURE = 'remote_compaction_v2'
-const DEFAULT_MAX_SSE_BYTES = 8 * 1024 * 1024
+export const REMOTE_COMPACTION_V2_FEATURE = 'remote_compaction_v2'
 
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
-function protocolError(message, code = 'LCX_COMPACT_INVALID_SSE') {
-  const error = new Error(message)
-  error.code = code
-  return error
-}
-
-function outputItemIdentity(event) {
-  const outputIndex = Number.isInteger(event?.output_index) && event.output_index >= 0
-    ? `index:${event.output_index}`
-    : undefined
-  const itemIds = [event?.item?.id, event?.item_id]
-    .filter((value) => typeof value === 'string' && value.length > 0)
-    .map((value) => `id:${value}`)
-  const uniqueItemIds = [...new Set(itemIds)]
-  if (uniqueItemIds.length > 1) {
-    throw protocolError('Native compaction SSE event contains conflicting item identities')
-  }
-  return { outputIndex, itemId: uniqueItemIds[0] }
-}
-
-function mergeOutputItem(event, items, recordsByIndex, recordsById) {
-  if (!isObject(event?.item)) return
-  const { outputIndex, itemId } = outputItemIdentity(event)
-  const mappedRecords = new Set()
-  if (outputIndex && recordsByIndex.has(outputIndex)) mappedRecords.add(recordsByIndex.get(outputIndex))
-  if (itemId && recordsById.has(itemId)) mappedRecords.add(recordsById.get(itemId))
-  if (mappedRecords.size > 1) {
-    throw protocolError('Native compaction SSE event maps output_index and item id to different items')
-  }
-
-  let record = mappedRecords.values().next().value
-  if (!record && event.type === 'response.output_item.done') {
-    const pending = items.filter((candidate) => !candidate.done &&
-      (!candidate.item.type || !event.item.type || candidate.item.type === event.item.type))
-    if (pending.length === 1) record = pending[0]
-    else if (pending.length > 1) {
-      throw protocolError('Native compaction SSE output item has ambiguous aliases')
-    }
-  }
-  if (!record) {
-    record = { item: {}, outputIndex: undefined, itemId: undefined, done: false }
-    items.push(record)
-  }
-
-  if (outputIndex && record.outputIndex && outputIndex !== record.outputIndex) {
-    throw protocolError('Native compaction SSE output_index changed for one item')
-  }
-  if (itemId && record.itemId && itemId !== record.itemId) {
-    throw protocolError('Native compaction SSE item id changed for one item')
-  }
-  if (outputIndex && recordsByIndex.has(outputIndex) && recordsByIndex.get(outputIndex) !== record) {
-    throw protocolError('Native compaction SSE output_index is reused by different items')
-  }
-  if (itemId && recordsById.has(itemId) && recordsById.get(itemId) !== record) {
-    throw protocolError('Native compaction SSE item id is reused by different items')
-  }
-
-  const previousEncryptedContent = typeof record.item.encrypted_content === 'string' && record.item.encrypted_content.length > 0
-    ? record.item.encrypted_content
-    : undefined
-  Object.assign(record.item, structuredClone(event.item))
-  if ((!record.item.encrypted_content || typeof record.item.encrypted_content !== 'string') && previousEncryptedContent) {
-    record.item.encrypted_content = previousEncryptedContent
-  }
-  if (outputIndex) {
-    record.outputIndex = outputIndex
-    recordsByIndex.set(outputIndex, record)
-  }
-  if (itemId) {
-    record.itemId = itemId
-    recordsById.set(itemId, record)
-  }
-  if (event.type === 'response.output_item.done') record.done = true
-}
-
-function validCompletedOutput(output) {
-  if (!Array.isArray(output)) return false
-  try {
-    normalizeCompactionResponse({ object: 'response.compaction', output })
-    return true
-  } catch {
-    return false
-  }
-}
-
-function usageFrom(response) {
-  const usage = response?.usage
-  if (!isObject(usage)) return undefined
-  const totalInputTokens = Number(usage.input_tokens ?? 0)
-  const outputTokens = Number(usage.output_tokens ?? 0)
-  const cacheReadValue = Number(usage.input_tokens_details?.cached_tokens ?? usage.input_token_details?.cached_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? 0)
-  const cacheWriteValue = Number(usage.input_tokens_details?.cache_write_tokens ?? usage.input_token_details?.cache_write_tokens ?? usage.prompt_tokens_details?.cache_write_tokens ?? 0)
-  const cacheReadTokens = Number.isFinite(cacheReadValue) && cacheReadValue > 0 ? cacheReadValue : 0
-  const cacheWriteTokens = Number.isFinite(cacheWriteValue) && cacheWriteValue > 0 ? cacheWriteValue : 0
-  const inputTokens = Number.isFinite(totalInputTokens)
-    ? Math.max(0, totalInputTokens - cacheReadTokens - cacheWriteTokens)
-    : 0
-  const normalizedOutputTokens = Number.isFinite(outputTokens) && outputTokens > 0 ? outputTokens : 0
-  if (![inputTokens, cacheReadTokens, cacheWriteTokens, normalizedOutputTokens].some((value) => value > 0)) return undefined
-  return {
-    inputTokens,
-    outputTokens: normalizedOutputTokens,
-    ...(cacheReadTokens > 0 ? { cacheReadTokens } : {}),
-    ...(cacheWriteTokens > 0 ? { cacheWriteTokens } : {}),
-    ...(Number.isFinite(usage.output_token_details?.reasoning_tokens) && usage.output_token_details.reasoning_tokens > 0
-      ? { reasoningTokens: Number(usage.output_token_details.reasoning_tokens) }
-      : {}),
-  }
-}
-
-function validToolDeclaration(tool) {
-  if (!isObject(tool)) return false
-  if (tool.type === undefined) return typeof tool.name === 'string' && tool.name.length > 0
-  if (typeof tool.type !== 'string' || tool.type.length === 0) return false
-  if (tool.type === 'function' || tool.type === 'custom') {
-    const name = tool.name ?? tool.function?.name
-    return typeof name === 'string' && name.length > 0
-  }
-  return true
-}
-
-export function responsesTools(tools) {
-  if (tools === undefined) return undefined
-  if (!Array.isArray(tools) || !tools.every(validToolDeclaration)) {
-    throw protocolError('Native compaction tools contain an invalid declaration', 'LCX_COMPACT_INVALID_TOOLS')
-  }
-  return tools.map((tool) => {
-    if (tool.type !== undefined) return structuredClone(tool)
-    return {
-      type: 'function',
-      ...structuredClone(tool),
-      description: typeof tool.description === 'string' ? tool.description : '',
-      parameters: tool.parameters && typeof tool.parameters === 'object' ? structuredClone(tool.parameters) : { type: 'object', properties: {} },
-      strict: false,
-    }
-  })
-}
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+function fail(message, code = 'LCX_COMPACT_INVALID_RESPONSE') { const e = new Error(message); e.code = code; return e }
 
-export function mergeFeatureHeader(headers) {
-  const result = { ...(headers ?? {}) }
+export function mergeFeatureHeader(headers = {}) {
+  const result = { ...headers }
   const key = Object.keys(result).find((name) => name.toLowerCase() === 'x-codex-beta-features')
-  const existing = key ? String(result[key] ?? '').trim() : ''
-  const features = existing.split(',').map((value) => value.trim()).filter(Boolean)
-  if (!features.includes(REMOTE_COMPACTION_V2_FEATURE)) features.push(REMOTE_COMPACTION_V2_FEATURE)
-  result[key ?? 'x-codex-beta-features'] = features.join(',')
+  const values = String(key ? result[key] ?? '' : '').split(',').map((x) => x.trim()).filter(Boolean)
+  if (!values.includes(REMOTE_COMPACTION_V2_FEATURE)) values.push(REMOTE_COMPACTION_V2_FEATURE)
+  result[key ?? 'x-codex-beta-features'] = values.join(',')
   return result
 }
 
-export function buildNativeCompactionBody({ model, input, instructions, promptCacheKey, promptCacheRetention, tools }) {
-  if (!Array.isArray(input)) throw protocolError('Native compaction input must be an array', 'LCX_COMPACT_INVALID_INPUT')
-  if (input.some((item) => isObject(item) && item.type === 'compaction_trigger')) {
-    throw protocolError('Native compaction input already contains compaction_trigger', 'LCX_COMPACT_DUPLICATE_TRIGGER')
-  }
+export function buildNativeCompactionBody({ model, input, instructions, tools, promptCacheKey }) {
+  if (!Array.isArray(input)) throw fail('native compaction input must be an array', 'LCX_COMPACT_INVALID_INPUT')
+  if (input.some((item) => item?.type === 'compaction_trigger')) throw fail('native compaction input already contains compaction_trigger', 'LCX_COMPACT_DUPLICATE_TRIGGER')
   const nativeTools = responsesTools(tools)
   return {
     model,
     input: [...structuredClone(input), { type: 'compaction_trigger' }],
     stream: true,
     store: false,
+    ...(instructions !== undefined ? { instructions } : {}),
     ...(nativeTools !== undefined ? { tools: nativeTools } : {}),
-    ...(instructions !== undefined ? { instructions: structuredClone(instructions) } : {}),
-    ...(promptCacheKey !== undefined && promptCacheKey !== null ? { prompt_cache_key: String(promptCacheKey) } : {}),
-    ...(promptCacheRetention !== undefined && promptCacheRetention !== null ? { prompt_cache_retention: String(promptCacheRetention) } : {}),
+    ...(promptCacheKey ? { prompt_cache_key: String(promptCacheKey) } : {}),
   }
 }
 
-function parseSseEvent(dataLines) {
-  if (dataLines.length === 0) return undefined
-  const data = dataLines.join('\n')
-  if (data === '[DONE]') return undefined
-  try {
-    const parsed = JSON.parse(data)
-    if (!isObject(parsed)) throw new Error('SSE event is not an object')
-    return parsed
-  } catch (error) {
-    throw protocolError(`Native compaction returned malformed SSE JSON: ${String(error)}`)
-  }
+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 result = {
+    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) result.cacheReadTokens = cacheRead
+  if (Number.isFinite(cacheWrite) && cacheWrite > 0) result.cacheWriteTokens = cacheWrite
+  const reasoning = Number(raw.output_tokens_details?.reasoning_tokens ?? raw.output_token_details?.reasoning_tokens ?? 0)
+  if (Number.isFinite(reasoning) && reasoning > 0) result.reasoningTokens = reasoning
+  return Object.values(result).some((v) => Number(v) > 0) ? result : undefined
 }
 
-export async function parseNativeCompactionSse(response, options = {}) {
-  if (!response?.body) throw protocolError('Native compaction response did not include an SSE body', 'LCX_INVALID_SSE')
-  const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_SSE_BYTES
-  const reader = response.body.getReader()
-  const decoder = new TextDecoder()
-  const eventItems = []
-  const recordsByIndex = new Map()
-  const recordsById = new Map()
-  let completedResponse
-  let completedOutput
-  let pending = ''
-  let dataLines = []
-  let bytes = 0
-  let sawTerminal = false
-
-  const dispatch = () => {
-    const event = parseSseEvent(dataLines)
-    dataLines = []
-    if (!event) return
-    if (event.type === 'error' || event.type === 'response.failed' || event.type === 'response.incomplete') {
-      const message = event.error?.message ?? event.response?.error?.message ?? `Native compaction ended with ${String(event.type)}`
-      throw protocolError(message, 'LCX_COMPACT_UPSTREAM_ERROR')
-    }
-    if (event.type === 'response.output_item.added' || event.type === 'response.output_item.done') {
-      mergeOutputItem(event, eventItems, recordsByIndex, recordsById)
-    }
-    if (event.type === 'response.completed') {
-      sawTerminal = true
-      completedResponse = isObject(event.response) ? event.response : {}
-      completedOutput = Array.isArray(completedResponse.output) ? structuredClone(completedResponse.output) : undefined
+function validateOutput(output) {
+  if (!Array.isArray(output) || output.length === 0) throw fail('native compaction output is empty')
+  const compactions = output.filter((item) => isObject(item) && item.type === 'compaction')
+  if (compactions.length !== 1) throw fail(`native compaction must return exactly one compaction item, got ${compactions.length}`)
+  const compact = compactions[0]
+  if (typeof compact.encrypted_content !== 'string' || compact.encrypted_content.length === 0) throw fail('native compaction item has no encrypted_content')
+  const calls = new Set()
+  const results = new Set()
+  for (const item of output) {
+    if (!isObject(item) || typeof item.type !== 'string') throw fail('native compaction output contains a malformed item')
+    if (item.type === 'function_call') {
+      if (typeof item.call_id !== 'string' || !item.call_id || calls.has(item.call_id)) throw fail('native compaction output contains an invalid function_call')
+      calls.add(item.call_id)
+    } else if (item.type === 'function_call_output') {
+      if (typeof item.call_id !== 'string' || !item.call_id || results.has(item.call_id)) throw fail('native compaction output contains an invalid function_call_output')
+      results.add(item.call_id)
     }
   }
+  for (const id of calls) if (!results.has(id)) throw fail(`native compaction output has orphan function_call ${id}`)
+  return { output: structuredClone(output), compaction: structuredClone(compact) }
+}
 
-  try {
-    while (true) {
-      if (options.signal?.aborted) throw options.signal.reason ?? new Error('request aborted')
-      const result = await reader.read()
-      if (result.done) break
-      bytes += result.value.byteLength
-      if (bytes > maxBytes) throw protocolError(`Native compaction SSE response exceeds ${maxBytes} bytes`, 'LCX_RESPONSE_TOO_LARGE')
-      pending += decoder.decode(result.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 === '') dispatch()
-        else if (!line.startsWith(':')) {
-          if (line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^ /u, ''))
-        }
-      }
-    }
-    pending += decoder.decode()
-    if (pending.length > 0) {
-      const line = pending.replace(/\r$/u, '')
-      if (line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^ /u, ''))
+export async function parseNativeCompactionSse(response, options = {}) {
+  const byIndex = new Map()
+  const byId = new Map()
+  let terminal
+  const mergeItem = (event) => {
+    if (!isObject(event?.item)) return
+    const index = Number.isInteger(event.output_index) ? event.output_index : undefined
+    const id = typeof event.item.id === 'string' ? event.item.id : typeof event.item_id === 'string' ? event.item_id : undefined
+    let record = (index !== undefined ? byIndex.get(index) : undefined) ?? (id ? byId.get(id) : undefined)
+    if (!record) record = {}
+    const encrypted = record.encrypted_content
+    Object.assign(record, structuredClone(event.item))
+    if (typeof record.encrypted_content !== 'string' && typeof encrypted === 'string') record.encrypted_content = encrypted
+    if (index !== undefined) byIndex.set(index, record)
+    if (id) byId.set(id, record)
+  }
+  await consumeSse(response, (event) => {
+    if (!isObject(event)) return
+    if (event.type === 'error' || event.type === 'response.failed' || event.type === 'response.incomplete') {
+      const e = fail(event.error?.message ?? event.response?.error?.message ?? `native compaction ended with ${event.type}`, 'LCX_COMPACT_UPSTREAM_ERROR')
+      e.status = event.error?.status
+      throw e
     }
-    dispatch()
-  } finally {
-    await reader.cancel().catch(() => undefined)
-  }
-
-  if (!sawTerminal || !completedResponse) {
-    throw protocolError('Native compaction SSE ended without response.completed', 'LCX_COMPACT_INCOMPLETE_SSE')
-  }
-
-  if (completedResponse.object !== undefined && !['response.compaction', 'response'].includes(completedResponse.object)) {
-    throw protocolError(`Native compaction returned unexpected response object: ${String(completedResponse.object)}`, 'LCX_COMPACT_INVALID_RESPONSE')
-  }
-  const mergedEventOutput = eventItems.map((record) => record.item)
-  const output = validCompletedOutput(completedOutput) ? completedOutput : mergedEventOutput
-  const normalized = normalizeCompactionResponse({
-    object: completedResponse.object ?? 'response.compaction',
-    id: typeof completedResponse.id === 'string' ? completedResponse.id : undefined,
-    output,
-  })
+    if (event.type === 'response.output_item.added' || event.type === 'response.output_item.done') mergeItem(event)
+    if (event.type === 'response.completed' || event.type === 'response.done') terminal = event.response
+  }, options)
+  if (!isObject(terminal)) throw fail('native compaction stream ended without response.completed', 'LCX_COMPACT_INCOMPLETE_SSE')
+  const eventItems = [...new Set([...byIndex.values(), ...byId.values()])]
+  const output = Array.isArray(terminal.output) && terminal.output.length > 0 ? terminal.output : eventItems
+  const normalized = validateOutput(output)
   return {
+    object: terminal.object ?? 'response.compaction',
+    ...(typeof terminal.id === 'string' ? { id: terminal.id } : {}),
     ...normalized,
-    usage: usageFrom(completedResponse),
+    usage: usageFrom(terminal.usage),
   }
 }
 
-export async function requestNativeCompaction({
-  baseURL,
-  model,
-  input,
-  instructions,
-  promptCacheKey,
-  promptCacheRetention,
-  idempotencyKey,
-  tools,
-  headers,
-  signal,
-  timeoutMs,
-  maxAttempts,
-  maxResponseBytes,
-}) {
-  const body = buildNativeCompactionBody({ model, input, instructions, promptCacheKey, promptCacheRetention, tools })
-  const requestHeaders = { ...(headers ?? {}) }
-  if (idempotencyKey !== undefined && idempotencyKey !== null && !Object.keys(requestHeaders).some((name) => name.toLowerCase() === 'idempotency-key')) {
-    requestHeaders['idempotency-key'] = String(idempotencyKey)
-  }
-  const featureHeaders = mergeFeatureHeader(requestHeaders)
-  return fetchSseWithRetry(
-    `${String(baseURL).replace(/\/+$/u, '')}/responses`,
-    body,
-    featureHeaders,
-    signal,
-    timeoutMs,
-    {
-      maxAttempts,
-      maxResponseBytes,
-      consume: (response, consumeOptions = {}) => parseNativeCompactionSse(response, {
-        signal: consumeOptions.requestSignal ?? signal,
-        maxResponseBytes,
-      }),
-    },
-  )
+export async function requestNativeCompaction({ baseURL, model, input, instructions, tools, promptCacheKey, idempotencyKey, headers, signal, timeoutMs, maxAttempts, maxResponseBytes }) {
+  const body = buildNativeCompactionBody({ model, input, instructions, tools, promptCacheKey })
+  const requestHeaders = mergeFeatureHeader({ ...headers, ...(idempotencyKey ? { 'idempotency-key': String(idempotencyKey) } : {}) })
+  return fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, '')}/responses`, body, requestHeaders, signal, timeoutMs, {
+    maxAttempts,
+    maxResponseBytes,
+    consume: (response, consumeOptions) => parseNativeCompactionSse(response, { signal: consumeOptions.requestSignal ?? signal, maxResponseBytes }),
+  })
 }

package/lib/dsh-responses.js

@@ -0,0 +1,220 @@
+import { offloadRequestImagesWithPolicy } from '@deepseek-ai/dsh-llm'
+const DEFAULT_MAX_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024
+const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 2048 * 2048
+const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024
+export { DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_REQUEST_IMAGE_MAX_BYTES }
+
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+
+function error(message, code) {
+  const value = new Error(message)
+  value.code = code
+  return value
+}
+
+function textOf(blocks) {
+  return (Array.isArray(blocks) ? blocks : []).filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('')
+}
+
+function hasImage(blocks) {
+  return (Array.isArray(blocks) ? blocks : []).some((block) => block?.type === 'image' || (block?.type === 'tool-result' && hasImage(block.content)))
+}
+
+export async function resolveModelImageSupport(ctx, route, signal) {
+  const llm = ctx?.get?.('llm') ?? ctx?.llm
+  if (typeof llm?.resolveModelInfo !== 'function') return 'unknown'
+  try {
+    const info = await llm.resolveModelInfo(route.provider, route.model, signal)
+    const modalities = info?.inputModalities
+    if (!Array.isArray(modalities)) return 'unknown'
+    return modalities.includes('image') ? 'supported' : 'unsupported'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function attachmentResolver(ctx, options) {
+  const attachments = ctx?.get?.('attachments') ?? ctx?.attachments
+  return async (block, signal) => {
+    if (typeof attachments?.readImageRequest !== 'function') {
+      throw error('LCX requires the DSH 0.1.1-rc.2 request-image attachment API', 'LCX_COMPACT_IMAGE_API_UNAVAILABLE')
+    }
+    const request = await attachments.readImageRequest(block?.attachment, {
+      maxPixels: options.requestImagePixelBudget,
+      maxBytes: options.requestImageMaxBytes,
+    }, signal)
+    const data = request?.data
+    const mediaType = request?.mediaType ?? block?.attachment?.mediaType
+    if (!(data instanceof Uint8Array) && !Buffer.isBuffer(data)) throw error('DSH attachment returned no request-image bytes', 'LCX_COMPACT_IMAGE_UNAVAILABLE')
+    if (typeof mediaType !== 'string' || !mediaType.startsWith('image/')) throw error('DSH attachment returned an invalid request-image media type', 'LCX_COMPACT_IMAGE_UNAVAILABLE')
+    return { data: Buffer.from(data), mediaType, ref: request?.attachment ?? block.attachment }
+  }
+}
+
+async function imagePart(block, ctx, options, imageMap) {
+  if (options.imageSupport === 'unsupported') return { type: 'input_text', text: '[image omitted because the target model does not support image input]' }
+  const image = await attachmentResolver(ctx, options)(block, options.signal)
+  const encodedBytes = Math.ceil(image.data.byteLength / 3) * 4
+  if (encodedBytes > options.maxRequestImageBytes) throw error('one image exceeds the configured LCX request image bound', 'LCX_COMPACT_IMAGE_TOO_LARGE')
+  const imageUrl = `data:${image.mediaType};base64,${image.data.toString('base64')}`
+  imageMap.set(imageUrl, structuredClone(image.ref))
+  return { type: 'input_image', image_url: imageUrl }
+}
+
+async function toolResultOutput(block, ctx, options, imageMap) {
+  if (!hasImage(block?.content)) return textOf(block?.content) || '(no output)'
+  const parts = []
+  let pending = ''
+  const flush = () => { if (pending) parts.push({ type: 'input_text', text: pending }); pending = '' }
+  for (const part of block.content ?? []) {
+    if (part?.type === 'text') pending += part.text
+    else if (part?.type === 'image') { flush(); parts.push(await imagePart(part, ctx, options, imageMap)) }
+    else if (part?.type === 'tool-result') {
+      const nested = await toolResultOutput(part, ctx, options, imageMap)
+      if (typeof nested === 'string') pending += nested === '(no output)' ? '' : nested
+      else { flush(); parts.push(...nested) }
+    }
+  }
+  flush()
+  return parts.some((part) => part.type === 'input_image') ? parts : parts.map((part) => part.text ?? '').join('') || '(no output)'
+}
+
+async function messageItems(message, ctx, options, imageMap) {
+  const blocks = Array.isArray(message?.content) ? message.content : []
+  const items = []
+  if (message?.role === 'assistant') {
+    const text = textOf(blocks)
+    if (text) items.push({ type: 'message', role: 'assistant', content: [{ type: 'output_text', text }] })
+    for (const call of blocks.filter((block) => block?.type === 'tool-call')) {
+      items.push({
+        type: 'function_call',
+        call_id: String(call.id),
+        name: String(call.name),
+        arguments: typeof call.arguments === 'string' ? call.arguments : JSON.stringify(call.arguments ?? {}),
+      })
+    }
+    return items
+  }
+  if (message?.role !== 'user') return items
+
+  const ordinary = blocks.filter((block) => block?.type === 'text' || block?.type === 'image')
+  if (ordinary.length > 0) {
+    const content = []
+    let pending = ''
+    const flush = () => { if (pending) content.push({ type: 'input_text', text: pending }); pending = '' }
+    for (const block of ordinary) {
+      if (block.type === 'text') pending += block.text
+      else { flush(); content.push(await imagePart(block, ctx, options, imageMap)) }
+    }
+    flush()
+    if (content.length > 0) items.push({ type: 'message', role: 'user', content })
+  }
+  for (const result of blocks.filter((block) => block?.type === 'tool-result')) {
+    items.push({
+      type: 'function_call_output',
+      call_id: String(result.toolCallId),
+      output: await toolResultOutput(result, ctx, options, imageMap),
+    })
+  }
+  return items
+}
+
+export async function serializeDshMessages(messages, ctx, options = {}) {
+  const imageMap = new Map()
+  const input = []
+  const normalized = {
+    imageSupport: options.imageSupport ?? 'unknown',
+    signal: options.signal,
+    maxRequestImageBytes: Number.isSafeInteger(options.maxRequestImageBytes) && options.maxRequestImageBytes > 0
+      ? options.maxRequestImageBytes
+      : DEFAULT_MAX_REQUEST_IMAGE_BYTES,
+    requestImagePixelBudget: Number.isSafeInteger(options.requestImagePixelBudget) && options.requestImagePixelBudget > 0
+      ? options.requestImagePixelBudget
+      : DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+    requestImageMaxBytes: Number.isSafeInteger(options.requestImageMaxBytes) && options.requestImageMaxBytes > 0
+      ? options.requestImageMaxBytes
+      : DEFAULT_REQUEST_IMAGE_MAX_BYTES,
+  }
+  const projected = offloadRequestImagesWithPolicy(messages ?? [], {
+    representation: 'base64',
+    maxBytes: normalized.maxRequestImageBytes,
+    byteQuantum: 1,
+    byteLength: ref => Math.min(ref.bytes, normalized.requestImageMaxBytes),
+  })
+  for (const message of projected) {
+    if (message?.role === 'system') continue
+    input.push(...await messageItems(message, ctx, normalized, imageMap))
+  }
+  return { input, imageMap }
+}
+
+export function responsesTools(tools) {
+  if (tools === undefined) return undefined
+  if (!Array.isArray(tools)) throw error('LCX Responses tools must be an array', 'LCX_COMPACT_INVALID_TOOLS')
+  return tools.map((tool) => {
+    if (!isObject(tool) || typeof tool.name !== 'string' || !tool.name) throw error('LCX Responses tool has no name', 'LCX_COMPACT_INVALID_TOOLS')
+    return {
+      type: 'function',
+      name: tool.name,
+      description: typeof tool.description === 'string' ? tool.description : '',
+      parameters: isObject(tool.parameters) ? structuredClone(tool.parameters) : { type: 'object', properties: {} },
+      strict: false,
+    }
+  })
+}
+
+function mapImageParts(value, mapper) {
+  if (!Array.isArray(value)) return value
+  return value.map((part) => {
+    if (part?.type === 'input_image' || part?.type === 'dsh_image_attachment') return mapper(part)
+    if (part?.type === 'function_call_output' && Array.isArray(part.output)) return { ...structuredClone(part), output: mapImageParts(part.output, mapper) }
+    return structuredClone(part)
+  })
+}
+
+export function persistNativeImageReferences(output, imageMap) {
+  const map = imageMap instanceof Map ? imageMap : new Map()
+  const persist = (part) => {
+    if (part.type !== 'input_image' || typeof part.image_url !== 'string') throw error('native compact returned an invalid image item', 'LCX_COMPACT_INVALID_RESPONSE')
+    const ref = map.get(part.image_url)
+    if (!ref) throw error('native compact returned an untracked image item', 'LCX_COMPACT_INVALID_RESPONSE')
+    return { type: 'dsh_image_attachment', attachment: structuredClone(ref) }
+  }
+  return (output ?? []).map((item) => {
+    if (item?.type === 'message' && Array.isArray(item.content)) return { ...structuredClone(item), content: mapImageParts(item.content, persist) }
+    if (item?.type === 'function_call_output' && Array.isArray(item.output)) return { ...structuredClone(item), output: mapImageParts(item.output, persist) }
+    return structuredClone(item)
+  })
+}
+
+async function hydratePart(part, ctx, options) {
+  if (part?.type !== 'dsh_image_attachment') return structuredClone(part)
+  if (options.imageSupport === 'unsupported') return { type: 'input_text', text: '[image omitted because the target model does not support image input]' }
+  const block = { type: 'image', attachment: part.attachment }
+  const map = options.imageMap instanceof Map ? options.imageMap : new Map()
+  return imagePart(block, ctx, options, map)
+}
+
+export async function hydrateNativeImageReferences(output, ctx, options = {}) {
+  const normalized = {
+    imageSupport: options.imageSupport ?? 'unknown',
+    signal: options.signal,
+    maxRequestImageBytes: options.maxRequestImageBytes ?? DEFAULT_MAX_REQUEST_IMAGE_BYTES,
+    requestImagePixelBudget: options.requestImagePixelBudget ?? DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+    requestImageMaxBytes: options.requestImageMaxBytes ?? DEFAULT_REQUEST_IMAGE_MAX_BYTES,
+    imageMap: options.imageMap,
+  }
+  const result = []
+  for (const item of output ?? []) {
+    if (item?.type === 'message' && Array.isArray(item.content)) {
+      const content = []
+      for (const part of item.content) content.push(await hydratePart(part, ctx, normalized))
+      result.push({ ...structuredClone(item), content })
+    } else if (item?.type === 'function_call_output' && Array.isArray(item.output)) {
+      const value = []
+      for (const part of item.output) value.push(await hydratePart(part, ctx, normalized))
+      result.push({ ...structuredClone(item), output: value })
+    } else result.push(structuredClone(item))
+  }
+  return result
+}