dsh-lcx-codex 0.4.1 → 0.4.2-pre.1

package/ARCHITECTURE.md

@@ -1,3 +1,27 @@
+# GPT Responses full-lifecycle ownership — 0.4.2-pre.1
+
+## Product contract
+
+`LCX OFF` leaves every LLM request on the native DSH adapter path. `LCX ON` is the ownership switch for the selected GPT Responses conversation: LCX owns the final Responses wire from the first ordinary turn through tool loops, Native V2 compaction, native replay, portable model migration, and restart/resume. Users turn LCX off before selecting a non-GPT model; DSH model switching itself remains hot and requires no restart.
+
+## Responsibility boundary
+
+- **DSH** remains the Agent, Session, request assembly, model/settings/credential, tool-execution, attachment, pressure-policy and compaction-transaction owner.
+- **The rc.2 compatibility seam** projects DSH `GenerateOptions` and durable replay content into Pi's provider-neutral `Context`. It exists only because DSH 0.1.1-rc.2 does not publish `toPiContext()` / `toStreamChunks()` as stable package APIs.
+- **Plugin Pi 0.84.3** owns canonical Responses message/tool serialization and stream semantics: reasoning, IDs, custom tools, strict/grammar tools, `additional_tools`, `tool_search`, namespace, cache semantics and event parsing.
+- **LCX** owns the final body, HTTP/SSE wire, safe error normalization, ordinary/compact/replay orchestration, Remote V2 opaque state and checkpoint compatibility.
+
+## Unified request path
+
+`serializeNativeAware()` is the shared history compiler. With no checkpoint it serializes ordinary history; with a compatible checkpoint it injects retained native history plus the opaque compaction item; with an incompatible GPT model/route it reconstructs portable DSH history. All three representations continue through one standard LCX request builder and one LCX transport/parser bridge. Compact is the standard request plus `compaction_trigger` and the Remote V2 feature header; native replay is the standard request plus opaque history. Portable migration never recursively bypasses LCX back to `PiAiAdapter`.
+
+Ordinary and replay requests perform one provider attempt and emit DSH terminal failure chunks using the host taxonomy, leaving visible retries to DSH's `agent/request-error` policy. Native compaction retains its bounded idempotent retry and first-checkpoint Basic fallback. Genuine upstream tool namespace is stored only in adapter-private replay metadata because DSH rc.2's visible ToolCall block has no namespace field.
+
+## Gateway continuity
+
+The stable DSH session id drives Pi-compatible prompt-cache/session-affinity fields. Sub2API v0.1.183 accepts `session_id`, `session-id`, and `x-client-request-id` for Codex account stickiness and repairs recovered custom-tool/tool-search item ID prefixes. Runtime acceptance therefore verifies both LCX wire continuity and gateway account continuity; release prose is not treated as the wire contract.
+
+---
 
 ## rc.6 pressure coordination
 

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.2-pre.1 - candidate under runtime acceptance
+
+### Architecture
+
+- Make the LCX master switch the GPT Responses lifecycle ownership switch: when enabled, the first ordinary Agent turn, tools, Native V2 compaction, native replay and portable GPT-model migration share one LCX final-wire path.
+- Upgrade only the plugin's direct Pi dependency to `0.84.3`; DSH 0.1.1-rc.2 and its host Pi 0.82.x remain isolated and unchanged.
+- Reuse Pi 0.84 canonical Responses serializers and stream semantics for strict/grammar/custom tools, deferred `additional_tools` / `tool_search`, namespace, reasoning, IDs and cache behavior.
+- Add one standard Responses request builder and shared LCX HTTP/SSE transport/parser bridge; remove the old portable recursive bypass back to the DSH adapter.
+- Preserve checkpoint v5, DSH compaction transactions, Native-first pressure coordination, first-checkpoint Basic fallback, restart/resume and Search/#20 architecture.
+- Normalize ordinary/replay failures into DSH terminal taxonomy and keep DSH as the visible retry owner.
+
+### Validation state
+
+- Engineering gates pass on the private work branch; exact commit-bound DSH + Sub2API runtime acceptance remains mandatory before integration, publication or a `VERIFIED` compatibility claim.
+
 ## 0.4.1 - 2026-08-25
 
 ### Stable promotion

package/cordis.patch.yml

@@ -10,6 +10,7 @@
         baseURL: https://api.lcxbot.com/v1
         apiKeyEnv: LCX_API_KEY
         model: gpt-5.6-sol
+        supportsExplicitPromptCacheMode: true
         legacyCheckpointPath: !!js dshHomePath('storages/lcx-codex/checkpoints-v3.json')
         alphaCapabilityPath: !!js dshHomePath('storages/lcx-codex/web-alpha-capabilities.json')
         alphaRefPath: !!js dshHomePath('storages/lcx-codex/web-alpha-refs.json')

package/lib/client.js

@@ -32,8 +32,9 @@ window.__ModuleLoader__.load({
     const copy = {
       zh: {
         title: 'Responses / Codex 能力',
-        desc: '复用现有 GPT Responses 路由；普通搜索走 DSH web_search，Native V2 压缩采用 90% 主动压缩 + 95% 紧急保护。',
-        enabled: '启用插件',
+        desc: 'LCX 开启后从第一轮普通请求开始接管当前 GPT Responses 会话，并统一管理普通请求、工具、Native V2 压缩和续接。',
+        enabled: '启用 LCX（接管当前 GPT Responses 会话）',
+        enabledHelp: '切换 Claude、Gemini、DeepSeek 等非 GPT 模型前先关闭 LCX；模型切换本身不需要重启 DSH。',
         web: '使用 GPT Hosted Search 作为 DSH web_search 后端',
         webHelp: '不会新增第二个普通搜索工具；普通 web_search 自动跟随当前 Agent 的 GPT Responses 模型。',
         searchTimeout: 'web_search 超时（秒）',
@@ -42,8 +43,6 @@ window.__ModuleLoader__.load({
         advancedHelp: '只在需要域名过滤、位置、search context、图片等原生 Hosted 参数时使用；默认关闭以保持工具 schema 稳定。',
         alpha: '启用 Alpha command（websearch_alpha）',
         alphaHelp: '仅 capability probe 对当前 endpoint/provider/model/schema 验证通过后才真正注册。',
-        compact: '启用 Native V2 远程压缩',
-        compactHelp: 'DSH 仍负责范围、事务和 /compact；Native state 保存在 DSH session log。',
         autoCompact: '启用 Native-first 自动压缩',
         autoCompactHelp: '到主动阈值前不让 DSH 的 80% tool-result prune 改写历史；到主动阈值后优先 Native V2。',
         autoThreshold: 'Native 自动压缩阈值（%）',
@@ -52,14 +51,15 @@ window.__ModuleLoader__.load({
         emergencyThresholdHelp: '建议 95%。达到这里才允许 DSH tool-result-pruner 先救场；必须高于 Native 阈值。',
         fallback: 'Native 失败后回退 DSH basic compaction',
         fallbackHelp: 'Remote-first：只有 Native 请求失败才调用 basic summary，不并行双跑。',
-        endpoint: '回退 Responses 地址',
-        model: '回退 GPT 模型',
+        endpoint: 'Responses 地址',
+        model: 'GPT 模型',
         save: '保存', discard: '放弃修改', saving: '保存中…',
       },
       en: {
         title: 'Responses / Codex capabilities',
-        desc: 'Reuse existing GPT Responses routes; Native V2 uses a 90% proactive threshold with 95% emergency protection.',
-        enabled: 'Enable plugin',
+        desc: 'When enabled, LCX owns the selected GPT Responses conversation from the first ordinary turn through tools, Native V2 compaction and continuation.',
+        enabled: 'Enable LCX (own current GPT Responses conversation)',
+        enabledHelp: 'Turn LCX off before switching to Claude, Gemini, DeepSeek, or another non-GPT model. Model switching itself does not require a DSH restart.',
         web: 'Use GPT Hosted Search as DSH web_search backend',
         webHelp: 'Keeps DSH web_search as the single ordinary search tool and follows the active Agent GPT Responses model.',
         searchTimeout: 'web_search timeout (seconds)',
@@ -68,8 +68,6 @@ window.__ModuleLoader__.load({
         advancedHelp: 'Only for native Hosted controls such as domains, location, context size and image search; off by default for stable tool schemas.',
         alpha: 'Enable Alpha command (websearch_alpha)',
         alphaHelp: 'Registered only after a matching capability probe.',
-        compact: 'Enable Native V2 remote compaction',
-        compactHelp: 'DSH still owns range/transactions and /compact; native state is persisted in the DSH session log.',
         autoCompact: 'Enable Native-first automatic compaction',
         autoCompactHelp: 'Suppresses the stock 80% tool-result prune before the proactive threshold, then prefers Native V2.',
         autoThreshold: 'Native auto-compaction threshold (%)',
@@ -78,7 +76,7 @@ window.__ModuleLoader__.load({
         emergencyThresholdHelp: 'Default 95%. DSH tool-result pruning is allowed only in this emergency zone; must exceed the Native threshold.',
         fallback: 'Fall back to DSH basic compaction on Native failure',
         fallbackHelp: 'Remote-first: basic summary runs only after Native failure, never in parallel.',
-        endpoint: 'Fallback Responses endpoint', model: 'Fallback GPT model',
+        endpoint: 'Responses endpoint', model: 'GPT model',
         save: 'Save', discard: 'Discard', saving: 'Saving…',
       },
     }
@@ -96,7 +94,7 @@ window.__ModuleLoader__.load({
       field(name) { return this.draftValue()[name] }
       projection() {
         const s = this.snapshot()
-        const bools = ['enabled','webSearch','advancedHostedSearch','alphaSearch','remoteCompaction','fallbackToBasicCompaction','autoCompaction']
+        const bools = ['enabled','webSearch','advancedHostedSearch','alphaSearch','fallbackToBasicCompaction','autoCompaction']
         return {
           available: s.status === 'ready', writable: s.writable, dirty: this.dirty, saving: this.saving,
           ...Object.fromEntries(bools.map((f) => [f, { value: f === 'fallbackToBasicCompaction' || f === 'autoCompaction' ? this.field(f) !== false : Boolean(this.field(f)) }])),
@@ -139,18 +137,17 @@ window.__ModuleLoader__.load({
         React.createElement('button', { className:'lcx-head', type:'button', onClick:()=>setOpen(!open) }, React.createElement('strong',null,t.title), React.createElement('span',null,open?'⌃':'⌄')),
         open ? React.createElement('div', { className:'lcx-body' },
           React.createElement('p', { className:'lcx-help' }, t.desc),
-          React.createElement(Row, { id:'lcx-enabled', label:t.enabled, checked:s.enabled.value, disabled, onChange:v=>props.edit('enabled',v) }),
+          React.createElement(Row, { id:'lcx-enabled', label:t.enabled, help:t.enabledHelp, checked:s.enabled.value, disabled, onChange:v=>props.edit('enabled',v) }),
           React.createElement(Row, { id:'lcx-web', label:t.web, help:t.webHelp, checked:s.webSearch.value, disabled:disabled||!s.enabled.value, onChange:v=>props.edit('webSearch',v) }),
           React.createElement('div', { className:'lcx-fields' },
             React.createElement(Field, { label:t.searchTimeout, help:t.searchTimeoutHelp, type:'number', min:30, max:600, step:30, value:s.webSearchTimeoutSeconds, disabled:disabled||!s.enabled.value||!s.webSearch.value, onChange:numeric('webSearchTimeoutSeconds') })),
           React.createElement(Row, { id:'lcx-advanced', label:t.advanced, help:t.advancedHelp, checked:s.advancedHostedSearch.value, disabled:disabled||!s.enabled.value||!s.webSearch.value, onChange:v=>props.edit('advancedHostedSearch',v) }),
           React.createElement(Row, { id:'lcx-alpha', label:t.alpha, help:t.alphaHelp, checked:s.alphaSearch.value, disabled:disabled||!s.enabled.value, onChange:v=>props.edit('alphaSearch',v) }),
-          React.createElement(Row, { id:'lcx-compact', label:t.compact, help:t.compactHelp, checked:s.remoteCompaction.value, disabled:disabled||!s.enabled.value, onChange:v=>props.edit('remoteCompaction',v) }),
-          React.createElement(Row, { id:'lcx-auto-compact', label:t.autoCompact, help:t.autoCompactHelp, checked:s.autoCompaction.value, disabled:disabled||!s.enabled.value||!s.remoteCompaction.value, onChange:v=>props.edit('autoCompaction',v) }),
+          React.createElement(Row, { id:'lcx-auto-compact', label:t.autoCompact, help:t.autoCompactHelp, checked:s.autoCompaction.value, disabled:disabled||!s.enabled.value, onChange:v=>props.edit('autoCompaction',v) }),
           React.createElement('div', { className:'lcx-fields' },
-            React.createElement(Field, { label:t.autoThreshold, help:t.autoThresholdHelp, type:'number', min:85, max:95, step:1, value:s.autoCompactionThresholdPercent, disabled:disabled||!s.enabled.value||!s.remoteCompaction.value||!s.autoCompaction.value, onChange:numeric('autoCompactionThresholdPercent') }),
-            React.createElement(Field, { label:t.emergencyThreshold, help:t.emergencyThresholdHelp, type:'number', min:90, max:99, step:1, value:s.emergencyPruneThresholdPercent, disabled:disabled||!s.enabled.value||!s.remoteCompaction.value||!s.autoCompaction.value, onChange:numeric('emergencyPruneThresholdPercent') })),
-          React.createElement(Row, { id:'lcx-fallback', label:t.fallback, help:t.fallbackHelp, checked:s.fallbackToBasicCompaction.value, disabled:disabled||!s.enabled.value||!s.remoteCompaction.value, onChange:v=>props.edit('fallbackToBasicCompaction',v) }),
+            React.createElement(Field, { label:t.autoThreshold, help:t.autoThresholdHelp, type:'number', min:85, max:95, step:1, value:s.autoCompactionThresholdPercent, disabled:disabled||!s.enabled.value||!s.autoCompaction.value, onChange:numeric('autoCompactionThresholdPercent') }),
+            React.createElement(Field, { label:t.emergencyThreshold, help:t.emergencyThresholdHelp, type:'number', min:90, max:99, step:1, value:s.emergencyPruneThresholdPercent, disabled:disabled||!s.enabled.value||!s.autoCompaction.value, onChange:numeric('emergencyPruneThresholdPercent') })),
+          React.createElement(Row, { id:'lcx-fallback', label:t.fallback, help:t.fallbackHelp, checked:s.fallbackToBasicCompaction.value, disabled:disabled||!s.enabled.value, onChange:v=>props.edit('fallbackToBasicCompaction',v) }),
           React.createElement('div', { className:'lcx-fields' },
             React.createElement(Field, { label:t.endpoint, value:s.baseURL, disabled, onChange:e=>props.edit('baseURL',e.target.value) }),
             React.createElement(Field, { label:t.model, value:s.model, disabled, onChange:e=>props.edit('model',e.target.value) })),

package/lib/compact-v2.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { consumeSse, fetchSseWithRetry } from './transport.js'
-import { responsesTools } from './dsh-responses.js'
+import { buildCompactionResponsesBody, responsesGenerationEnvelope as standardGenerationEnvelope } from './responses-request.js'
 
 /** @typedef {Record<string, unknown>} UnknownRecord */
 /** @typedef {Record<string, string>} HeaderMap */
@@ -16,11 +16,13 @@ import { responsesTools } from './dsh-responses.js'
 /**
  * @typedef {object} NativeCompactionBodyOptions
  * @property {string} model
+ * @property {unknown} [modelDescriptor]
  * @property {unknown[]} input
  * @property {string} [instructions]
  * @property {unknown} [tools]
  * @property {string} [promptCacheKey]
  * @property {string} [promptCacheRetention]
+ * @property {'none' | 'short' | 'long'} [cacheRetention]
  * @property {unknown} [reasoningEffort]
  * @property {unknown} [temperature]
  * @property {unknown} [maxTokens]
@@ -37,6 +39,7 @@ import { responsesTools } from './dsh-responses.js'
  * @property {unknown[]} [tools]
  * @property {string} [prompt_cache_key]
  * @property {string} [prompt_cache_retention]
+ * @property {{ mode?: 'explicit', ttl?: '30m' }} [prompt_cache_options]
  * @property {{ effort: string, summary: 'auto' }} [reasoning]
  * @property {string[]} [include]
  * @property {number} [temperature]
@@ -97,46 +100,27 @@ export function mergeFeatureHeader(headers = {}) {
  * @param {GenerationControls} [controls]
  * @returns {GenerationEnvelope}
  */
-export function responsesGenerationEnvelope({ reasoningEffort, temperature, maxTokens } = {}) {
-  /** @type {GenerationEnvelope} */
-  const result = {}
-  if (reasoningEffort !== undefined && reasoningEffort !== 'off') {
-    result.reasoning = { effort: String(reasoningEffort), summary: 'auto' }
-    result.include = ['reasoning.encrypted_content']
-  }
-  if (temperature !== undefined) {
-    if (!Number.isFinite(temperature)) throw fail('Responses temperature must be finite', 'LCX_COMPACT_INVALID_INPUT')
-    result.temperature = Number(temperature)
-  }
-  if (maxTokens !== undefined) {
-    if (!Number.isSafeInteger(maxTokens) || /** @type {number} */ (maxTokens) <= 0) throw fail('Responses maxTokens must be a positive safe integer', 'LCX_COMPACT_INVALID_INPUT')
-    result.max_output_tokens = Math.max(16, /** @type {number} */ (maxTokens))
-  }
-  return result
+export function responsesGenerationEnvelope(controls = {}) {
+  return standardGenerationEnvelope(controls)
 }
 
 /**
  * @param {NativeCompactionBodyOptions} options
  * @returns {NativeCompactionBody}
  */
-export function buildNativeCompactionBody({ model, input, instructions, tools, promptCacheKey, promptCacheRetention, reasoningEffort, temperature, maxTokens }) {
-  if (!Array.isArray(input)) throw fail('native compaction input must be an array', 'LCX_COMPACT_INVALID_INPUT')
-  if (input.some((item) => /** @type {UnknownRecord | undefined} */ (item)?.type === 'compaction_trigger')) throw fail('native compaction input already contains compaction_trigger', 'LCX_COMPACT_DUPLICATE_TRIGGER')
-  /** @type {unknown[] | undefined} */
-  const nativeTools = responsesTools(tools)
-  return {
-    model,
-    input: [...structuredClone(input), { type: 'compaction_trigger' }],
-    stream: true,
-    store: false,
-    tool_choice: 'auto',
-    parallel_tool_calls: true,
-    ...(instructions !== undefined ? { instructions } : {}),
-    ...(nativeTools !== undefined ? { tools: nativeTools } : {}),
-    ...(promptCacheKey ? { prompt_cache_key: String(promptCacheKey) } : {}),
-    ...(promptCacheRetention ? { prompt_cache_retention: String(promptCacheRetention) } : {}),
-    ...responsesGenerationEnvelope({ reasoningEffort, temperature, maxTokens }),
-  }
+export function buildNativeCompactionBody({ model, modelDescriptor, input, instructions, tools, promptCacheKey, promptCacheRetention, cacheRetention, reasoningEffort, temperature, maxTokens }) {
+  return /** @type {NativeCompactionBody} */ (/** @type {unknown} */ (buildCompactionResponsesBody({
+    model: /** @type {any} */ (modelDescriptor ?? model),
+    input,
+    instructions,
+    tools,
+    promptCacheKey,
+    promptCacheRetention,
+    cacheRetention: cacheRetention ?? (promptCacheKey ? (promptCacheRetention ? 'long' : 'short') : 'none'),
+    reasoningEffort,
+    temperature,
+    maxTokens,
+  })))
 }
 
 /**
@@ -260,8 +244,8 @@ export async function parseNativeCompactionSse(response, options = {}) {
 /**
  * @param {NativeCompactionRequestOptions} options
  */
-export async function requestNativeCompaction({ baseURL, model, input, instructions, tools, promptCacheKey, promptCacheRetention, reasoningEffort, temperature, maxTokens, idempotencyKey, headers, signal, timeoutMs, maxAttempts, maxResponseBytes }) {
-  const body = buildNativeCompactionBody({ model, input, instructions, tools, promptCacheKey, promptCacheRetention, reasoningEffort, temperature, maxTokens })
+export async function requestNativeCompaction({ baseURL, model, modelDescriptor, input, instructions, tools, promptCacheKey, promptCacheRetention, cacheRetention, reasoningEffort, temperature, maxTokens, idempotencyKey, headers, signal, timeoutMs, maxAttempts, maxResponseBytes }) {
+  const body = buildNativeCompactionBody({ model, modelDescriptor, input, instructions, tools, promptCacheKey, promptCacheRetention, cacheRetention, reasoningEffort, temperature, maxTokens })
   const requestHeaders = mergeFeatureHeader({ ...headers, ...(idempotencyKey ? { 'idempotency-key': String(idempotencyKey) } : {}) })
   return fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, '')}/responses`, body, requestHeaders, signal, timeoutMs, {
     maxAttempts,

package/lib/dsh-responses.js

@@ -98,6 +98,7 @@ export function readDshPiReplayState(value) {
     if (!['text', 'reasoning', 'tool-call'].includes(block.type)) throw invalidReplay(`block ${index} has an unknown type`)
     for (const signature of ['textSignature', 'thinkingSignature', 'thoughtSignature']) if (block[signature] !== undefined && typeof block[signature] !== 'string') throw invalidReplay(`block ${index} ${signature} must be a string`)
     if (block.redacted !== undefined && typeof block.redacted !== 'boolean') throw invalidReplay(`block ${index} redacted must be boolean`)
+    if (block.namespace !== undefined && typeof block.namespace !== 'string') throw invalidReplay(`block ${index} namespace must be a string`)
   }
   return { response, blocks: value.blocks }
 }
@@ -125,7 +126,7 @@ function replayedAssistant(message, source) {
     if (replayBlockType(block?.type) !== replay?.type) throw invalidReplay(`block ${index} does not match assistant content`)
     if (block.type === 'text') return { type: 'text', text: String(block.text ?? ''), ...(replay.textSignature === undefined ? {} : { textSignature: replay.textSignature }) }
     if (block.type === 'reasoning') return { type: 'thinking', thinking: String(block.text ?? ''), ...(replay.thinkingSignature === undefined ? {} : { thinkingSignature: replay.thinkingSignature }), ...(replay.redacted === undefined ? {} : { redacted: replay.redacted }) }
-    return { type: 'toolCall', id: String(block.id), name: String(block.name), arguments: parseArguments(block.arguments), ...(replay.thoughtSignature === undefined ? {} : { thoughtSignature: replay.thoughtSignature }) }
+    return { type: 'toolCall', id: String(block.id), name: String(block.name), arguments: parseArguments(block.arguments), ...(replay.thoughtSignature === undefined ? {} : { thoughtSignature: replay.thoughtSignature }), ...(replay.namespace === undefined ? {} : { namespace: replay.namespace }) }
   })
   return { role: 'assistant', content, api: state.response.api, provider: state.response.provider, model: state.response.model, ...(state.response.responseModel === undefined ? {} : { responseModel: state.response.responseModel }), ...(state.response.responseId === undefined ? {} : { responseId: state.response.responseId }), usage: emptyUsage(), stopReason: state.response.stopReason, timestamp: 0 }
 }
@@ -173,7 +174,7 @@ function builtinResponsesModel(provider, modelId) {
   catch { return undefined }
 }
 
-function piModel(options) {
+export function resolvePiResponsesModel(options) {
   const route = options.route ?? {}
   const explicit = options.model && typeof options.model === 'object' ? options.model : undefined
   const provider = String(explicit?.provider ?? route.provider ?? 'dsh-lcx-codex')
@@ -217,19 +218,25 @@ export async function serializeDshMessages(messages, ctx, options = {}) {
     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) })
-  const model = piModel(normalized)
+  const model = resolvePiResponsesModel(normalized)
   const context = { systemPrompt: normalized.systemPrompt, messages: await dshToPiMessages(projected, ctx, normalized, imageMap), tools: options.tools ?? [] }
   const supportsStrictMode = model.compat?.supportsStrictMode ?? false
   const supportsOpenAIGrammarTools = model.compat?.supportsOpenAIGrammarTools ?? false
+  const supportsAdditionalTools = model.compat?.supportsAdditionalTools ?? false
   const supportsToolSearch = model.compat?.supportsToolSearch ?? false
+  const deferredToolsMode = supportsAdditionalTools ? 'additional-tools' : supportsToolSearch ? 'tool-search' : undefined
   const grammarToolInputProperties = createGrammarToolInputProperties(context.tools, supportsOpenAIGrammarTools)
-  const placement = splitDeferredTools(context, supportsToolSearch)
+  const placement = splitDeferredTools(context, deferredToolsMode !== undefined)
   const toolOptions = { supportsStrictMode, supportsOpenAIGrammarTools }
   const input = convertResponsesMessages(model, context, new Set(['openai', 'openai-codex', 'opencode']), {
-    includeSystemPrompt: normalized.includeSystemPrompt, grammarToolInputProperties, deferredTools: placement.deferred, toolOptions,
+    includeSystemPrompt: normalized.includeSystemPrompt,
+    grammarToolInputProperties,
+    deferredTools: placement.deferred,
+    deferredToolsMode,
+    toolOptions,
   })
   const tools = options.tools === undefined ? undefined : convertResponsesTools(placement.immediate, toolOptions)
-  return { input, imageMap, tools }
+  return { input, imageMap, tools, model, grammarToolInputProperties, deferredToolsMode }
 }
 
 export function responsesTools(tools) {

package/lib/index.js

@@ -49,8 +49,9 @@ import {
   resolveModelImageSupport,
   serializeDshMessages,
 } from './dsh-responses.js'
-import { requestNativeCompaction } from './compact-v2.js'
-import { requestNativeReplay } from './responses-replay.js'
+import { mergeFeatureHeader, requestNativeCompaction } from './compact-v2.js'
+import { buildResponsesBody } from './responses-request.js'
+import { managedFailureChunk, streamResponsesRequest } from './responses-stream.js'
 import {
   checkpointStateForMessage,
   compactCheckpointId,
@@ -94,7 +95,6 @@ const SETTINGS_NS = settingsNamespace('lcx-codex')
 const ADVANCED_HOSTED_TOOL = 'websearch_gpt_advanced'
 const ALPHA_TOOL = 'websearch_alpha'
 const COMPACTION_DIRECTIVE = 'You are now acting as a compaction engine'
-const bypassReplayOptions = new WeakSet()
 const hostedSearchRouteContext = new AsyncLocalStorage()
 
 function dshHome() { return process.env.DSH_HOME ?? join(homedir(), '.dsh') }
@@ -107,6 +107,7 @@ export const Config = z.object({
   baseURL: z.string().default('https://api.lcxbot.com/v1'),
   apiKeyEnv: z.string().default('LCX_API_KEY'),
   model: z.string().default('gpt-5.6-sol'),
+  supportsExplicitPromptCacheMode: z.boolean().default(false),
   legacyCheckpointPath: z.string().default(''),
   checkpointPath: z.string().default(''),
   alphaCapabilityPath: z.string().default(''),
@@ -155,6 +156,7 @@ function normalizeConfig(input = {}) {
     baseURL: String(input.baseURL || 'https://api.lcxbot.com/v1').replace(/\/+$/u, ''),
     apiKeyEnv: input.apiKeyEnv || 'LCX_API_KEY',
     model: input.model || 'gpt-5.6-sol',
+    supportsExplicitPromptCacheMode: input.supportsExplicitPromptCacheMode === true,
     headers: input.headers && typeof input.headers === 'object' ? { ...input.headers } : {},
     legacyCheckpointPath: legacy,
     alphaCapabilityPath: input.alphaCapabilityPath || defaultAlphaCapabilityPath(),
@@ -370,15 +372,16 @@ function mergeMap(target, source) { for (const [key, value] of source ?? []) tar
 async function serializeNativeAware(messages, route, routeConfig, ctx, options = {}) {
   const session = sessionFor(ctx, route.sessionId)
   const imageSupport = await resolveModelImageSupport(ctx, route, options.signal)
-  const input = []; const imageMap = new Map(); let nativeTools
+  const input = []; const imageMap = new Map(); let nativeTools; let nativeModel; let grammarToolInputProperties
   let normal = []
   const serializeOptions = (imageMapOverride, extra = {}) => requestImageOptions(routeConfig, imageSupport, options.signal, imageMapOverride, { route, tools: options.tools, responsesCompat: routeConfig.responsesCompat, ...extra })
   const prelude = await serializeDshMessages([], ctx, serializeOptions(undefined, { systemPrompt: options.system, includeSystemPrompt: true }))
-  input.push(...prelude.input); nativeTools = prelude.tools
+  const ephemeralPreludeItemCount = prelude.input.length
+  input.push(...prelude.input); nativeTools = prelude.tools; nativeModel = prelude.model; grammarToolInputProperties = prelude.grammarToolInputProperties
   const flush = async () => {
     if (!normal.length) return
     const serialized = await serializeDshMessages(normal, ctx, serializeOptions())
-    nativeTools = serialized.tools ?? nativeTools
+    nativeTools = serialized.tools ?? nativeTools; nativeModel = serialized.model ?? nativeModel; grammarToolInputProperties = serialized.grammarToolInputProperties ?? grammarToolInputProperties
     input.push(...serialized.input); mergeMap(imageMap, serialized.imageMap); normal = []
   }
   for (const message of messages ?? []) {
@@ -439,7 +442,8 @@ async function serializeNativeAware(messages, route, routeConfig, ctx, options =
     normal.push(message)
   }
   await flush()
-  return { input, imageMap, imageSupport, tools: nativeTools }
+  if (!nativeModel) throw Object.assign(new Error('LCX could not resolve the Pi Responses model descriptor'), { code: 'LCX_RESPONSES_MODEL_UNAVAILABLE' })
+  return { input, ephemeralPreludeItemCount, imageMap, imageSupport, tools: nativeTools, model: nativeModel, grammarToolInputProperties }
 }
 
 function fallbackEligible(error, signal) {
@@ -461,10 +465,12 @@ async function* remoteCompactionStream(options, routeConfig, state, ctx, next, r
     const result = await requestNativeCompaction({
       baseURL: routeConfig.baseURL,
       model: route.model,
+      modelDescriptor: prepared.model,
       input: prepared.input,
       tools: prepared.tools ?? options.tools,
       promptCacheKey: promptCacheKey(route, routeConfig),
       promptCacheRetention: promptCacheRetention(routeConfig),
+      cacheRetention: routeConfig.cacheRetention,
       reasoningEffort: generation.reasoningEffort,
       temperature: generation.temperature,
       maxTokens: generation.maxTokens,
@@ -477,7 +483,7 @@ async function* remoteCompactionStream(options, routeConfig, state, ctx, next, r
     })
     const session = sessionFor(ctx, route.sessionId)
     const block = createNativeCheckpointBlock({
-      session, route, result, input: prepared.input, imageMap: prepared.imageMap,
+      session, route, result, input: prepared.input, ephemeralPreludeItemCount: prepared.ephemeralPreludeItemCount, imageMap: prepared.imageMap,
       retentionOptions: {
         tokenBudget: routeConfig.nativeRetentionTokenBudget,
         assistantTokenReserve: routeConfig.assistantRetentionTokenReserve,
@@ -522,6 +528,11 @@ function pressurePolicy(state, config) {
   return { auto, emergency: Math.min(99, emergency) }
 }
 
+export function compactionPressureBand(totalTokens, contextWindow, policy) {
+  const ratioPercent = totalTokens / contextWindow * 100
+  return { ratioPercent, band: ratioPercent < policy.auto ? 'below' : ratioPercent < policy.emergency ? 'native' : 'emergency' }
+}
+
 function adjustedCompactionConfig(config, target, thresholdRatio) {
   if (!config || typeof config !== 'object') return config
   const modelPolicies = Array.isArray(config.modelPolicies)
@@ -549,7 +560,7 @@ function patchCompactionPressureService(compactionValue, state, getConfig, ctx,
       return original.call(this, agentArg, trigger, activeSignal)
     }
     return record.mutex.run(activeSignal, async () => {
-      if (trigger !== 'pressure' || !state.enabled || !state.remoteCompaction || !state.autoCompaction) return callOriginal()
+      if (trigger !== 'pressure' || !state.enabled || !state.autoCompaction) return callOriginal()
       const config = getConfig()
       const target = routedTargetForAgent(agentArg, config)
       if (!target || !resolveResponsesRouteConfig(ctx, target, config)) return callOriginal()
@@ -561,11 +572,12 @@ function patchCompactionPressureService(compactionValue, state, getConfig, ctx,
       if (!Number.isFinite(contextWindow) || contextWindow <= 0) return callOriginal()
       const totalTokens = Number(tokenMeter.measure(agentArg.session)?.totalTokens ?? 0)
       const { auto, emergency } = pressurePolicy(state, config)
-      const ratioPercent = totalTokens / contextWindow * 100
-      if (ratioPercent < auto) return null
+      const pressure = compactionPressureBand(totalTokens, contextWindow, { auto, emergency })
+      const ratioPercent = pressure.ratioPercent
+      if (pressure.band === 'below') return null
       const prunerState = toolResultPrunerState(resolveAgentService(ctx, agentArg, 'toolResultPruner') ?? resolveContextService(this?.ctx, 'toolResultPruner'))
       const configState = compactionConfigState(this)
-      const nativeFirst = ratioPercent < emergency
+      const nativeFirst = pressure.band === 'native'
       const noOpPrune = () => ({ pruned: [], charsRemoved: 0 })
       const prunerPatch = nativeFirst ? patchToolResultPruner(prunerState, noOpPrune) : undefined
       const configPatch = patchCompactionConfig(configState, originalConfig => adjustedCompactionConfig(originalConfig, target, auto / 100))
@@ -604,29 +616,51 @@ function visibleWebSearchTimeout(state, getConfig) {
 function messagesContainNativeCheckpoint(messages, session) { return Boolean(session && (messages ?? []).some((message) => checkpointStateForMessage(session, message))) }
 function messagesContainLegacyCheckpoint(messages) { return (messages ?? []).some((message) => Boolean(legacyCheckpointId(message))) }
 
-async function* recursiveLlmStream(ctx, options, messages) {
-  const llm = contextService(ctx, 'llm')
-  if (!llm?.stream) throw Object.assign(new Error('LCX portable replay requires ctx.llm.stream'), { code: 'LCX_CHECKPOINT_REPLAY_UNAVAILABLE' })
-  const rewritten = { ...options, messages }
-  bypassReplayOptions.add(rewritten)
-  const stream = await llm.stream(rewritten)
-  for await (const chunk of stream) yield chunk
+function inputHasNativeState(input) {
+  return (input ?? []).some((item) => item?.type === 'compaction')
 }
 
-async function* replayCheckpointStream(options, routeConfig, ctx) {
+async function* managedResponsesStream(options, routeConfig, ctx) {
   const route = currentRoute(options, routeConfig)
-  const session = sessionFor(ctx, route.sessionId)
-  if (!session) throw Object.assign(new Error('Native checkpoint replay requires the live DSH session'), { code: 'LCX_SESSION_UNAVAILABLE' })
-  const incompatibleV4 = (options.messages ?? []).some((message) => { const state = checkpointStateForMessage(session, message); return state && !stateRouteCompatible(state, route, ctx) })
-  if (incompatibleV4) {
-    const portable = rewriteCheckpointsPortable(options.messages, session, { maxChars: routeConfig.portableReplayMaxChars })
-    yield* recursiveLlmStream(ctx, options, portable)
-    return
+  try {
+    if (options.stop !== undefined) throw Object.assign(new Error('LCX Responses does not support GenerateOptions.stop'), { code: 'LCX_RESPONSES_UNSUPPORTED_OPTION' })
+    const prepared = await serializeNativeAware(options.messages, route, routeConfig, ctx, { signal: options.signal, system: options.system, tools: options.tools })
+    const cacheSessionId = promptCacheSessionId(route, routeConfig)
+    const headers = await authenticatedHeaders(ctx, routeConfig, cacheSessionId, cacheSessionId === undefined ? null : undefined)
+    const body = buildResponsesBody({
+      model: prepared.model,
+      input: prepared.input,
+      tools: prepared.tools ?? options.tools,
+      sessionId: cacheSessionId,
+      promptCacheKey: promptCacheKey(route, routeConfig),
+      promptCacheRetention: promptCacheRetention(routeConfig),
+      cacheRetention: routeConfig.cacheRetention,
+      reasoningEffort: options.reasoningEffort,
+      temperature: options.temperature,
+      maxTokens: options.maxTokens,
+    })
+    const nativeReplay = inputHasNativeState(prepared.input)
+    if (nativeReplay) { body.tool_choice = 'auto'; body.parallel_tool_calls = true }
+    yield* streamResponsesRequest({
+      baseURL: routeConfig.baseURL,
+      provider: route.provider,
+      model: route.model,
+      piModel: prepared.model,
+      body,
+      grammarToolInputProperties: prepared.grammarToolInputProperties,
+      headers: nativeReplay ? mergeFeatureHeader(headers) : headers,
+      signal: options.signal,
+      timeoutMs: routeConfig.timeoutMs,
+      maxAttempts: 1,
+      maxResponseBytes: routeConfig.maxResponseBytes,
+    })
+  } catch (error) {
+    yield managedFailureChunk(error, options.signal)
   }
-  const prepared = await serializeNativeAware(options.messages, route, routeConfig, ctx, { signal: options.signal, system: options.system, tools: options.tools })
-  const cacheSessionId = promptCacheSessionId(route, routeConfig)
-  const headers = await authenticatedHeaders(ctx, routeConfig, cacheSessionId, cacheSessionId === undefined ? null : undefined)
-  yield* requestNativeReplay({ baseURL: routeConfig.baseURL, provider: route.provider, model: route.model, input: prepared.input, tools: prepared.tools ?? options.tools, promptCacheKey: promptCacheKey(route, routeConfig), promptCacheRetention: promptCacheRetention(routeConfig), reasoningEffort: options.reasoningEffort, temperature: options.temperature, maxTokens: options.maxTokens, headers, signal: options.signal, timeoutMs: routeConfig.timeoutMs, maxAttempts: routeConfig.maxAttempts, maxResponseBytes: routeConfig.maxResponseBytes })
+}
+
+async function* unavailableManagedRouteStream(options) {
+  yield managedFailureChunk(Object.assign(new Error('LCX is enabled but the selected DSH route cannot be resolved as an authenticated OpenAI Responses wire route'), { code: 'LCX_RESPONSES_ROUTE_UNAVAILABLE' }), options.signal)
 }
 
 function installInjected(ctx, configInput = {}) {
@@ -733,22 +767,14 @@ function installInjected(ctx, configInput = {}) {
   }, { global: true })
 
   ctx.on('llm/stream', (options, next) => {
-    if (bypassReplayOptions.delete(options)) return next()
-    if (!state.enabled || !state.remoteCompaction || options.purpose === 'session-title') return next()
+    if (!state.enabled || options.purpose === 'session-title') return next()
     const routeConfig = resolveResponsesRouteConfig(ctx, options, runtimeConfig)
     if (options.purpose === 'compaction') {
-      if (!routeConfig) return next()
+      if (!routeConfig) return unavailableManagedRouteStream(options)
       return remoteCompactionStream(options, routeConfig, state, ctx, next, requestHeaders)
     }
-    const session = sessionFor(ctx, String(options.sessionId ?? ''))
-    const hasNative = messagesContainNativeCheckpoint(options.messages, session)
-    const hasLegacy = messagesContainLegacyCheckpoint(options.messages)
-    if (!hasNative && !hasLegacy) return next()
-    if (!routeConfig) {
-      if (hasNative && session) return recursiveLlmStream(ctx, options, rewriteCheckpointsPortable(options.messages, session, { maxChars: runtimeConfig.portableReplayMaxChars }))
-      return next()
-    }
-    return replayCheckpointStream(options, routeConfig, ctx)
+    if (!routeConfig) return unavailableManagedRouteStream(options)
+    return managedResponsesStream(options, routeConfig, ctx)
   })
 
   ctx.effect?.(() => async () => {

package/lib/native-checkpoint.js

@@ -63,7 +63,7 @@ import { estimateBudgetItem, portableBudgetError, portableTokenCeiling } from '.
  * @property {unknown} [retainedAssistantCount]
  */
 /** @typedef {{ compaction: CompactionItem }} NativeCompactionResult */
-/** @typedef {{ session: NativeSession, route: RouteIdentity, result: NativeCompactionResult, input?: unknown[], imageMap?: unknown, retentionOptions?: RetentionOptions }} CreateCheckpointOptions */
+/** @typedef {{ session: NativeSession, route: RouteIdentity, result: NativeCompactionResult, input?: unknown[], ephemeralPreludeItemCount?: number, imageMap?: unknown, retentionOptions?: RetentionOptions }} CreateCheckpointOptions */
 /** @typedef {Error & { code?: string }} LcxError */
 
 export const NATIVE_BLOCK_TYPE = 'lcx-native-compaction-v5'
@@ -99,6 +99,8 @@ function assistantTextParts(item) { if (!isObject(item) || item.type !== 'messag
 function isRetainedAssistantItem(item) { return assistantTextParts(item).length > 0 }
 /** @param {unknown} item */
 function assistantText(item) { return assistantTextParts(item).map((part) => part.text).join('') }
+/** @param {unknown} item */
+function retainedAssistantPhase(item) { const phase = isObject(item) ? item.phase : undefined; return phase === 'commentary' || phase === 'final_answer' ? phase : undefined }
 
 /**
  * @param {unknown} item
@@ -107,16 +109,22 @@ function assistantText(item) { return assistantTextParts(item).map((part) => par
  */
 function truncateVisibleAssistantItem(item, maxTokens = ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP) {
   const text = assistantText(item); if (!text) return undefined
-  /** @param {string} retained */
-  const candidate = (retained) => ({ type: 'message', role: 'assistant', content: [{ type: 'output_text', text: retained }] })
-  const full = candidate(text)
+  const phase = retainedAssistantPhase(item)
+  const providerId = isObject(item) && typeof item.id === 'string' && item.id ? item.id : undefined
+  /** @param {string} retained @param {boolean} preserveProviderId */
+  const candidate = (retained, preserveProviderId) => ({
+    type: 'message', role: 'assistant', content: [{ type: 'output_text', text: retained }],
+    ...(phase ? { phase } : {}),
+    ...(preserveProviderId && providerId ? { id: providerId } : {}),
+  })
+  const full = candidate(text, true)
   if ((estimatedItemTokens(full) ?? Infinity) <= maxTokens) return full
   const marker = '\n…[LCX retained answer truncated]…\n'
   /** @param {number} count */
   const shortened = (count) => {
     const available = Math.max(0, count - marker.length)
     const head = Math.floor(available * 0.72); const tail = available - head
-    return candidate(`${text.slice(0, head)}${marker}${text.slice(Math.max(head, text.length - tail))}`)
+    return candidate(`${text.slice(0, head)}${marker}${text.slice(Math.max(head, text.length - tail))}`, false)
   }
   let low = 0; let high = text.length; let best
   while (low <= high) {
@@ -184,7 +192,7 @@ export function activeCompactionId(session) { if (!session?.events) return undef
  * @param {CreateCheckpointOptions} options
  * @returns {NativeCheckpointV5}
  */
-export function createNativeCheckpointBlock({ session, route, result, input = [], imageMap, retentionOptions = {} }) {
+export function createNativeCheckpointBlock({ session, route, result, input = [], ephemeralPreludeItemCount = 0, imageMap, retentionOptions = {} }) {
   const compactionId = activeCompactionId(session)
   if (!compactionId) {
     /** @type {LcxError} */
@@ -192,7 +200,10 @@ export function createNativeCheckpointBlock({ session, route, result, input = []
     error.code = 'LCX_COMPACTION_ID_UNAVAILABLE'
     throw error
   }
-  const retention = retainedConversationPlan(input, retentionOptions)
+  if (!Number.isSafeInteger(ephemeralPreludeItemCount) || ephemeralPreludeItemCount < 0 || ephemeralPreludeItemCount > input.length) {
+    throw Object.assign(new Error('Native compaction prelude provenance is invalid'), { code: 'LCX_COMPACTION_PRELUDE_PROVENANCE_INVALID' })
+  }
+  const retention = retainedConversationPlan(input.slice(ephemeralPreludeItemCount), retentionOptions)
   /** @type {NativeOutputItem[]} */
   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() }