dsh-lcx-codex 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## Unreleased
 
+## 0.3.3 - 2026-08-21
+
+### Fixed
+
+- Native V2 checkpoint 现在由客户端按 64K token 预算保留最近真实 user messages，再追加 exactly-one compaction item；不再错误假设上游 `response.output` 会返回 retained messages。旧的 compaction-only v3 checkpoint 会从 portable history 安全补全，运行时上下文注入不会进入 replacement history。
+
+### Documentation
+
+- 记录 installed `0.3.2` 的 compact + 三次 replay 缓存实测，并说明 Sub2API Codex OAuth 路径会删除上游不支持的 `prompt_cache_retention`；短缓存过期后的单次冷请求不等于插件改变了稳定前缀。
+- 增加连续 replay 的前缀稳定性回归断言，区分缓存生命周期与 replacement-history 保真问题。
+
 ## 0.3.2 - 2026-08-21
 
 ### Fixed

package/README.md

@@ -130,6 +130,8 @@ node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-
 - Alpha capability：`$DSH_HOME/storages/lcx-codex/web-alpha-capabilities.json`
 - Alpha refs：`$DSH_HOME/storages/lcx-codex/web-alpha-refs.json`
 - 只支持 Native remote-compaction V2，不调用 `/responses/compact`
+- 同路由 replay 会复用 DSH session 的 `prompt_cache_key` 并保持已有请求前缀稳定；短期缓存过期后仍可能出现单次冷请求，不能用会话累计命中率判断插件是否破坏缓存
+- Sub2API 的 Codex OAuth 转换层会删除上游不支持的 `prompt_cache_retention`，因此经该路径设置 `24h` 不会延长缓存；以实际连续请求的 `cached_tokens` 为准
 - Checkpoint 不保存图片原始字节或 data URL
 - Opaque checkpoint 不跨不兼容 provider、model、base URL、session 或 lineage 回放
 - 不包含图片生成功能

package/README_EN.md

@@ -130,6 +130,8 @@ The probe does not print the key or full response bodies. Restart DSH, or disabl
 - Alpha capabilities: `$DSH_HOME/storages/lcx-codex/web-alpha-capabilities.json`
 - Alpha references: `$DSH_HOME/storages/lcx-codex/web-alpha-refs.json`
 - Only Native remote-compaction V2 is supported; `/responses/compact` is never called.
+- Same-route replay reuses the DSH session `prompt_cache_key` and preserves the existing request prefix. A single cold request can still occur after the short-lived upstream cache expires, so the cumulative session hit rate is not evidence that the plugin changed the prefix.
+- Sub2API strips the unsupported `prompt_cache_retention` field on its Codex OAuth path, so requesting `24h` does not extend cache lifetime on that route. Use the `cached_tokens` reported by consecutive real requests as the authoritative signal.
 - Checkpoints never store raw image bytes or data URLs.
 - Opaque checkpoints are not replayed across an incompatible provider, model, base URL, session, or lineage.
 - Image generation is not included.

package/lib/compact.js

@@ -4,8 +4,107 @@ import { offloadDshRequestImages, resolveDshImage, serializeDshResponsesInput }
 const UNSUPPORTED_CHECKPOINT_PATTERN = /\[dsh-lcx-codex-checkpoint:[0-9a-f-]{36}\]/iu
 const PORTABLE_CHECKPOINT_PATTERN = /\[dsh-lcx-codex-v3-checkpoint:([0-9a-f-]{36})\]/giu
 const PORTABLE_HISTORY_TOKEN_BUDGET = 20_000
+export const NATIVE_RETAINED_MESSAGE_TOKEN_BUDGET = 64_000
 export const PORTABLE_HISTORY_BYTE_BUDGET = 2 * 1024 * 1024
 const UNSUPPORTED_IMAGE_PLACEHOLDER = '[image omitted because the target model does not support image input]'
+const NATIVE_IMAGE_TOKEN_ESTIMATE = 765
+const CONTEXTUAL_USER_PREFIXES = [
+  '<environment_context>',
+  '<user_instructions>',
+  '<additional_context>',
+  '<skills',
+  '<token_budget>',
+  '<model_switch>',
+]
+
+function nativeContentPartTokens(part) {
+  if (part?.type === 'input_image' || part?.type === 'dsh_image_attachment') return NATIVE_IMAGE_TOKEN_ESTIMATE
+  if (typeof part?.text === 'string') return Math.ceil(part.text.length / 4)
+  return Math.ceil(JSON.stringify(part ?? null).length / 4)
+}
+
+function nativeMessageTokens(item) {
+  return Math.max(1, (item?.content ?? []).reduce((total, part) => total + nativeContentPartTokens(part), 0))
+}
+
+function truncatedNativeText(text, maxTokens) {
+  const maxChars = maxTokens * 4
+  if (maxChars <= 0) return ''
+  if (text.length <= maxChars) return text
+  const omittedTokens = Math.max(1, Math.ceil((text.length - maxChars) / 4))
+  const marker = `[...${omittedTokens} tokens truncated...]`
+  if (maxChars <= marker.length + 2) return text.slice(-maxChars)
+  const sideChars = Math.max(1, Math.floor((maxChars - marker.length) / 2))
+  return `${text.slice(0, sideChars)}${marker}${text.slice(-sideChars)}`
+}
+
+function truncateNativeUserMessage(item, maxTokens) {
+  let remaining = maxTokens
+  const content = []
+  for (const part of item?.content ?? []) {
+    if (remaining <= 0) break
+    const tokens = Math.max(1, nativeContentPartTokens(part))
+    if (tokens <= remaining) {
+      content.push(structuredClone(part))
+      remaining -= tokens
+      continue
+    }
+    if (typeof part?.text === 'string') {
+      const text = truncatedNativeText(part.text, remaining)
+      if (text) content.push({ ...structuredClone(part), text })
+    }
+    remaining = 0
+  }
+  return content.length > 0 ? { ...structuredClone(item), content } : undefined
+}
+
+function isNativeRetainedUserMessage(item) {
+  if (item?.type !== 'message' || item.role !== 'user' || !Array.isArray(item.content)) return false
+  return !item.content.some((part) => {
+    if (part?.type !== 'input_text' || typeof part.text !== 'string') return false
+    const text = part.text.trimStart().toLowerCase()
+    return CONTEXTUAL_USER_PREFIXES.some((prefix) => text.startsWith(prefix))
+  })
+}
+
+export function buildNativeReplacementHistory(input, compaction, options = {}) {
+  if (compaction?.type !== 'compaction' || typeof compaction.encrypted_content !== 'string' || compaction.encrypted_content.length === 0) {
+    const error = new Error('LCX Native replacement history requires one non-empty compaction item')
+    error.code = 'LCX_COMPACT_INVALID_RESPONSE'
+    throw error
+  }
+  let remaining = options.tokenBudget ?? NATIVE_RETAINED_MESSAGE_TOKEN_BUDGET
+  if (!Number.isSafeInteger(remaining) || remaining <= 0) {
+    const error = new Error('LCX Native retained message token budget must be a positive integer')
+    error.code = 'LCX_COMPACT_INVALID_INPUT'
+    throw error
+  }
+  const retained = []
+  const candidates = (input ?? []).filter(isNativeRetainedUserMessage)
+  for (let index = candidates.length - 1; index >= 0 && remaining > 0; index -= 1) {
+    const item = candidates[index]
+    const tokens = nativeMessageTokens(item)
+    if (tokens <= remaining) {
+      retained.push(structuredClone(item))
+      remaining -= tokens
+      continue
+    }
+    const truncated = truncateNativeUserMessage(item, remaining)
+    if (truncated) retained.push(truncated)
+    remaining = 0
+  }
+  retained.reverse()
+  retained.push(structuredClone(compaction))
+  return retained
+}
+
+export function checkpointNativeReplacementHistory(record) {
+  const nativeOutput = Array.isArray(record?.nativeOutput) ? record.nativeOutput : []
+  if (nativeOutput.some(isNativeRetainedUserMessage)) return structuredClone(nativeOutput)
+  const compaction = nativeOutput.find((item) => item?.type === 'compaction') ?? record?.nativeCompaction
+  if (!compaction) return structuredClone(nativeOutput)
+  return buildNativeReplacementHistory(record?.portableHistory ?? [], compaction)
+}
 
 export function portableCheckpointIds(text) {
   return [...String(text ?? '').matchAll(PORTABLE_CHECKPOINT_PATTERN)].map((match) => match[1].toLowerCase())
@@ -461,7 +560,7 @@ export function buildPortableResponsesInput(messages, store, route) {
     throw error
   }
   const prefix = state === 'native-compatible'
-    ? record.nativeOutput
+    ? checkpointNativeReplacementHistory(record)
     : [...portableSummaryItem(record.portableSummary), ...buildPortableHistory(record.portableHistory)]
   const tail = normalInput((messages ?? []).slice(marker.index + 1), { strict: true })
   return [...structuredClone(prefix), ...tail]
@@ -513,7 +612,7 @@ export async function buildPortableResponsesInputWithImages(messages, store, rou
     }
   }
   const prefix = state === 'native-compatible'
-    ? await hydrateNativeImageReferences(record.nativeOutput, options)
+    ? await hydrateNativeImageReferences(checkpointNativeReplacementHistory(record), options)
     : [...portableSummaryItem(record.portableSummary), ...portableHistory]
   const tail = state === 'native-compatible'
     ? await serializeDshResponsesInput(requestMessages.slice(marker.index + 1), { ...options, imageSupport, route })

package/lib/index.js

@@ -8,6 +8,7 @@ import { join } from 'node:path'
 import { CheckpointV3Store, CHECKPOINT_V3_VERSION } from './checkpoint-store-v3.js'
 import {
   baseURLFingerprint,
+  buildNativeReplacementHistory,
   buildPortableHistory,
   assertCheckpointRoute,
   buildPortableResponsesInput,
@@ -15,6 +16,7 @@ import {
   hasPortableCheckpoint,
   hydrateNativeImageReferences,
   inputImageCount,
+  checkpointNativeReplacementHistory,
   latestPortableMarker,
   normalizeCompactionResponse,
   persistNativeImageReferences,
@@ -774,7 +776,7 @@ async function* nativeCheckpointReplayStream(options, config, portableStore, ctx
     ? await resolveModelImageSupport(llm, route, options.signal)
     : 'supported'
   const imageOptions = { resolveImage: attachmentImageResolver(ctx), imageSupport, signal: options.signal, maxRequestImageBytes: config.maxRequestImageBytes }
-  const nativeOutput = await hydrateNativeImageReferences(record.nativeOutput, imageOptions)
+  const nativeOutput = await hydrateNativeImageReferences(checkpointNativeReplacementHistory(record), imageOptions)
   const tailInput = await buildPortableResponsesInputWithImages(
     (options.messages ?? []).slice(marker.index + 1),
     portableStore,
@@ -887,7 +889,8 @@ function portableMarkerTextWithSummary(id, model, usage, summary) {
 async function commitRemoteCompaction(prepared, result, portableStore, config, summary, usage) {
   const { history, route, lease, input, imageReferences } = prepared
   lease?.assert('commit')
-  const persistedNativeOutput = persistNativeImageReferences(result.output, imageReferences)
+  const replacementHistory = buildNativeReplacementHistory(input, result.compaction)
+  const persistedNativeOutput = persistNativeImageReferences(replacementHistory, imageReferences)
   const persistedPortableInput = persistNativeImageReferences(input, imageReferences)
   const id = randomUUID()
   const parent = latestPortableMarker(history)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lcx-codex",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "DSH web search and Responses native V2 compaction for Sub2API-proxied or NewAPI-relayed GPT models",
   "keywords": [
     "deepseek-harness",