dsh-lcx-codex 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 ## 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
+
+- Native V2 compact 与同路由 replay 现在和 DSH/Pi 普通 Responses 请求复用相同的 session `prompt_cache_key`、缓存 retention 与会话 header，避免压缩边界额外切换 NewAPI/Sub2API 的缓存和账号粘性域；`cacheRetention: none` 时同时省略这些缓存信号。
+- 移除未被插件直接导入或注入的 `@deepseek-ai/dsh-compaction-basic` peer 声明，避免 DSH/pnpm 安装时出现误导性的宿主依赖警告；Basic fallback 继续通过 DSH `llm/stream` 的 `next()` 链调用宿主实现。
+
 ## 0.3.1 - 2026-08-21
 
 ### Fixed

package/README.md

@@ -78,7 +78,7 @@ dsh plugin --profile web add dsh-lcx-codex
 也可以下载 GitHub Release 中的 `.tgz` 安装指定版本：
 
 ```powershell
-dsh plugin --profile web add .\dsh-lcx-codex-0.3.1.tgz
+dsh plugin --profile web add .\dsh-lcx-codex-0.3.2.tgz
 ```
 
 安装后启动 DSH：
@@ -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

@@ -78,7 +78,7 @@ dsh plugin --profile web add dsh-lcx-codex
 You can also install a specific `.tgz` file from a GitHub Release:
 
 ```powershell
-dsh plugin --profile web add .\dsh-lcx-codex-0.3.1.tgz
+dsh plugin --profile web add .\dsh-lcx-codex-0.3.2.tgz
 ```
 
 Start DSH after installation:
@@ -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-v2.js

@@ -156,7 +156,7 @@ export function mergeFeatureHeader(headers) {
   return result
 }
 
-export function buildNativeCompactionBody({ model, input, instructions, promptCacheKey, tools }) {
+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')
@@ -170,6 +170,7 @@ export function buildNativeCompactionBody({ model, input, instructions, promptCa
     ...(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) } : {}),
   }
 }
 
@@ -273,6 +274,7 @@ export async function requestNativeCompaction({
   input,
   instructions,
   promptCacheKey,
+  promptCacheRetention,
   idempotencyKey,
   tools,
   headers,
@@ -281,7 +283,7 @@ export async function requestNativeCompaction({
   maxAttempts,
   maxResponseBytes,
 }) {
-  const body = buildNativeCompactionBody({ model, input, instructions, promptCacheKey, tools })
+  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)

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

@@ -1,12 +1,14 @@
 import z from '@deepseek-ai/schemastery'
 import { attributionHeaders, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { clampOpenAIPromptCacheKey } from '@earendil-works/pi-ai/api/openai-prompt-cache'
 import { randomUUID } from 'node:crypto'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { CheckpointV3Store, CHECKPOINT_V3_VERSION } from './checkpoint-store-v3.js'
 import {
   baseURLFingerprint,
+  buildNativeReplacementHistory,
   buildPortableHistory,
   assertCheckpointRoute,
   buildPortableResponsesInput,
@@ -14,6 +16,7 @@ import {
   hasPortableCheckpoint,
   hydrateNativeImageReferences,
   inputImageCount,
+  checkpointNativeReplacementHistory,
   latestPortableMarker,
   normalizeCompactionResponse,
   persistNativeImageReferences,
@@ -135,6 +138,7 @@ function normalizeCompactTransport(value) {
 }
 
 function normalizeConfig(input = {}) {
+  const cacheRetention = ['none', 'short', 'long'].includes(input.cacheRetention) ? input.cacheRetention : 'short'
   return {
     provider: input.provider || 'lcx',
     baseURL: String(input.baseURL || 'https://api.lcxbot.com/v1').replace(/\/+$/u, ''),
@@ -142,6 +146,8 @@ function normalizeConfig(input = {}) {
     model: input.model || 'gpt-5.6-sol',
     compactTransport: normalizeCompactTransport(input.compactTransport),
     headers: input.headers && typeof input.headers === 'object' ? { ...input.headers } : {},
+    cacheRetention,
+    supportsLongCacheRetention: input.supportsLongCacheRetention !== false,
     checkpointPath: input.checkpointPath || defaultCheckpointPath(),
     portableCheckpointPath: input.portableCheckpointPath || portableCheckpointPath(input.checkpointPath || defaultCheckpointPath()),
     alphaCapabilityPath: input.alphaCapabilityPath || defaultAlphaCapabilityPath(),
@@ -186,6 +192,8 @@ function resolveResponsesRouteConfig(ctx, options, fallbackConfig) {
     baseURL,
     apiKeyEnv,
     headers: profile.headers ?? fallbackConfig.headers,
+    cacheRetention: profile.cacheRetention ?? fallbackConfig.cacheRetention,
+    supportsLongCacheRetention: profile.compat?.supportsLongCacheRetention ?? fallbackConfig.supportsLongCacheRetention,
     model: options.model,
     compactTransport: profile.compactTransport ?? fallbackConfig.compactTransport,
     timeoutMs: profile.timeoutMs ?? fallbackConfig.timeoutMs,
@@ -301,7 +309,7 @@ async function authenticatedHeaders(ctx, config, sessionId, clientRequestId) {
     ...config.headers,
     ...attributionHeaders(),
     authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
-    'x-client-request-id': clientRequestId ?? randomUUID(),
+    ...(clientRequestId === null ? {} : { 'x-client-request-id': clientRequestId ?? (sessionId ? String(sessionId) : randomUUID()) }),
     ...(sessionId ? { 'session-id': String(sessionId) } : {}),
   }
 }
@@ -361,19 +369,35 @@ function routeWithSessionAncestry(ctx, route) {
   return { ...route, ancestorSessionIds: sessionAncestry(ctx, route.sessionId) }
 }
 
-function promptCacheKey(route) {
-  return route?.sessionId ? routeFingerprint(route) : undefined
+function promptCacheSessionId(route, config) {
+  if (config?.cacheRetention === 'none') return undefined
+  return route?.sessionId ? String(route.sessionId) : undefined
+}
+
+function promptCacheKey(route, config) {
+  const sessionId = promptCacheSessionId(route, config)
+  return sessionId ? clampOpenAIPromptCacheKey(sessionId) : undefined
+}
+
+function promptCacheRetention(config) {
+  return config?.cacheRetention === 'long' && config.supportsLongCacheRetention !== false ? '24h' : undefined
+}
+
+function promptCacheHeaders(ctx, config, route) {
+  const sessionId = promptCacheSessionId(route, config)
+  return authenticatedHeaders(ctx, config, sessionId, sessionId === undefined ? null : undefined)
 }
 
 async function requestRemoteCompaction(options, input, config, signal, ctx, route, preflightHeaders) {
   try {
-    const headers = preflightHeaders ?? await authenticatedHeaders(ctx, config, options.sessionId)
+    const headers = preflightHeaders ?? await promptCacheHeaders(ctx, config, route)
     return await requestNativeCompaction({
       baseURL: config.baseURL,
       model: options.model,
       input,
       instructions: options.system,
-      promptCacheKey: promptCacheKey(route),
+      promptCacheKey: promptCacheKey(route, config),
+      promptCacheRetention: promptCacheRetention(config),
       idempotencyKey: randomUUID(),
       tools: options.tools,
       headers,
@@ -731,7 +755,7 @@ function checkpointReplayRecord(messages, store) {
   return { marker, record }
 }
 
-function nativeReplayBody(options, route, nativeOutput, tailInput) {
+function nativeReplayBody(options, route, config, nativeOutput, tailInput) {
   return {
     model: options.model,
     input: [...structuredClone(nativeOutput), ...structuredClone(tailInput)],
@@ -739,7 +763,8 @@ function nativeReplayBody(options, route, nativeOutput, tailInput) {
     store: false,
     ...(options.tools !== undefined ? { tools: responsesTools(options.tools) } : {}),
     ...(options.system !== undefined ? { instructions: options.system } : {}),
-    ...(promptCacheKey(route) ? { prompt_cache_key: promptCacheKey(route) } : {}),
+    ...(promptCacheKey(route, config) ? { prompt_cache_key: promptCacheKey(route, config) } : {}),
+    ...(promptCacheRetention(config) ? { prompt_cache_retention: promptCacheRetention(config) } : {}),
   }
 }
 
@@ -751,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,
@@ -762,8 +787,8 @@ async function* nativeCheckpointReplayStream(options, config, portableStore, ctx
   try {
     const response = await fetchSse(
       `${config.baseURL}/responses`,
-      nativeReplayBody(options, route, nativeOutput, tailInput),
-      mergeFeatureHeader(await authenticatedHeaders(ctx, config, options.sessionId)),
+      nativeReplayBody(options, route, config, nativeOutput, tailInput),
+      mergeFeatureHeader(await promptCacheHeaders(ctx, config, route)),
       replaySignals.signal,
       config.timeoutMs + 1000,
       { maxResponseBytes: config.maxResponseBytes },
@@ -822,7 +847,7 @@ async function prepareRemoteCompaction(options, config, portableStore, ctx, sess
   const route = currentRoute(options, config)
   const lease = sessionTracker?.capture(route.sessionId)
   lease?.assert('request-start')
-  const headers = await authenticatedHeaders(ctx, config, options.sessionId)
+  const headers = await promptCacheHeaders(ctx, config, route)
   responsesTools(options.tools)
   const llm = ctx?.llm ?? ctx?.get?.('llm')
   const imageSupport = typeof llm?.resolveModelInfo === 'function'
@@ -864,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.1",
+  "version": "0.3.3",
   "description": "DSH web search and Responses native V2 compaction for Sub2API-proxied or NewAPI-relayed GPT models",
   "keywords": [
     "deepseek-harness",
@@ -62,7 +62,6 @@
     "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-compaction-basic": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-credentials": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",