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

package/ARCHITECTURE.md

@@ -9,7 +9,7 @@ DSH 0.1.1-rc.2 `compaction-basic` defaults to a `0.8` pressure threshold and, on
 - provider-confirmed context overflow continues to use DSH's original `context-overflow` recovery unchanged;
 - manual `/compact` remains unchanged.
 
-The pressure wrapper is installed on the actual agent-scoped compaction instance when an agent enters `running`, because DSH's own pre-step listener dynamically dispatches `this.compactIfNeeded()` at event time. The wrapper is restored on plugin cleanup.
+Agent presets may isolate `compaction` and `toolResultPruner` inside entry-local Cordis realms. DSH 0.1.1-rc.2 explicitly documents that these preset services are invisible to both the host and ordinary `agent.ctx`; host-side code must address them through `agentPresets.serviceFor(agent, name)`. LCX therefore observes agent lifecycle events globally, resolves each Agent's real preset-local compaction/pruner through that public resolver, and patches the concrete compaction instance. A root `ctx.inject(['compaction'], ...)` hook remains only for non-preset/non-isolated deployments. Concrete Cordis service identity is used for de-duplication. DSH's own pre-step listener dynamically dispatches `this.compactIfNeeded()` at event time, and the wrapper is restored on plugin cleanup.
 
 ## rc.6 search timeout coordination
 
@@ -17,12 +17,16 @@ The pressure wrapper is installed on the actual agent-scoped compaction instance
 
 # Architecture Notes — 0.4 Native Session Refactor / rc.6 Pressure Coordination
 
+## rc.11 Native cache identity
+
+Native compaction and same-route replay reuse the active DSH/Pi conversation cache identity: the clamped session id is the `prompt_cache_key`, provider `cacheRetention` is respected, and `long` may emit `prompt_cache_retention: 24h` when supported. `cacheRetention: none` omits Native prompt-cache/session affinity. Ordinary Hosted Search remains intentionally isolated under `dsh-lcx-search:<route hash>` so search traffic cannot share the main conversation request/cache namespace.
+
 ## Design invariants
 
 1. **DSH owns compaction policy.** LCX never independently decides threshold, compact range, pruning, transaction boundaries or overflow retries.
 2. **Native success performs one compaction model request.** Basic summary is a failure fallback, not a parallel portable-copy generator.
 3. **DSH session log is the new checkpoint source of truth.** Opaque Native V2 state lives in `compaction/summary.rawOutput`; v3 sidecar access is legacy read-only.
-4. **Opaque state never crosses an incompatible route.** Provider, model, base URL and session ancestry gate native replay.
+4. **Opaque state is same-session only.** Provider, model, base URL and exact `sourceSessionId === currentSessionId` gate Native opaque replay. Verified parent/child ancestry authorizes portable migration only; a fork never sends the parent's opaque checkpoint state.
 5. **Route migration is transparent and transient.** Reconstruct shadowed DSH messages and hand them to the normal adapter; do not persist a second portable history copy.
 6. **Ordinary search has one model tool.** `web_search` is ordinary search; `websearch_gpt_advanced` exists only for parameters absent from `WebSearchRequest`; Alpha remains its own stateful protocol.
 7. **Provider-native wire code is isolated.** Direct `/responses` SSE code is limited to Native V2 compaction/replay and Hosted Search protocol calls.

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 0.4.0 - 2026-08-23
+
+### Stable promotion
+
+- Promote the fully validated `0.4.0-rc.13` runtime to the stable `0.4.0` line with no functional/runtime code changes.
+- Make the rc.13 Native V2 hardening, canonical Responses replay/serialization fixes, session isolation, cache continuity, and concurrency/lifecycle fixes the recommended stable release.
+- Preserve `0.3.4` only as historical stable state; `0.4.0` becomes the default npm `latest` after publication.
+
+### Validation
+
+- Runtime-sensitive source is required to remain content-identical to the already live-tested rc.13 release.
+- Full suite: 58/58 passed; DSH schema validation: 4/4 passed.
+- Real rc.13 DSH acceptance already covers automatic Native pressure Compact, replay/cache re-warm, restart/resume, real GUI `/compact`, parent/child opaque isolation, and dual-session same-preset ServiceMutex failure cleanup.
+- Stable promotion adds no new runtime behavior; publication is a version/documentation promotion only.
+
+## 0.4.0-rc.13 - 2026-08-23
+
+### Fixed
+
+- Restrict opaque Native checkpoint replay to the exact source DSH session. Parent/child ancestry remains valid only for portable migration, so a fork never sends the parent session's opaque Native state.
+- Reconcile Responses replay deltas and terminal output by stable item/call identity instead of `output_index` alone, preventing changed-index duplicate/empty text blocks and keeping terminal-only function calls balanced.
+- Replace the simplified Native message/tool serializer with the public `@earendil-works/pi-ai@0.82.1` OpenAI Responses converters, preserving reasoning/message identities, tool linkage, constrained-tool semantics, deferred-tool transcript semantics, and DSH image boundaries.
+- Match ordinary Pi `openai-responses` system-prompt placement: Native compact/replay now carries the developer/system prelude inside the canonical input prefix rather than introducing a separate top-level `instructions` prefix difference.
+- Restore strict validation of DSH Pi replay-state envelopes before reusing native signatures; mismatched replay metadata degrades to a portable foreign-assistant projection instead of injecting stale provider-native identity.
+- Treat Pi canonical role-only developer/user items as durable retained history and keep image persistence on `dsh_image_attachment` references rather than request image payloads.
+- Use Pi/model or explicitly configured DSH Responses compatibility only; unknown custom routes no longer assume strict tools, grammar tools, or tool-search support.
+- Mirror DSH/OpenAI Responses generation controls into Native compact/replay (`reasoning` + encrypted-reasoning include, temperature, and max output tokens), preventing the real Terra `xhigh` compact path from dropping the envelope used by ordinary Pi requests.
+- Source automatic-compaction generation controls from the matching session request header rather than the Basic compaction summarizer request, so the selected conversation effort (for example Terra `xhigh`) reaches the Native provider request.
+- Declare the DSH `sessions` service as an explicit Cordis runtime injection because checkpoint/replay and automatic-compaction generation parity read the live session/request header.
+- Maintain a deterministic per-session request-header cache from DSH `session/event`; `compaction/start` synchronously refreshes it from the live Session before the Native request, avoiding reliance on async-context propagation for generation parity.
+- Register that cross-session `session/event` observer with Cordis `{ global: true }`, matching DSH system-wide observers so Agent-carrier session events reach the standing plugin scope.
+- Snapshot the exact `agentArg.session.requestHeader()` inside the Native-first pressure wrapper immediately before delegating to Basic compaction; this is the deterministic pressure-path source of generation controls, with the global session-event cache retained only as a secondary path.
+- Seed the request-header cache from already-live sessions at plugin installation, seed newly announced resume/fork sessions, and evict disposed session entries so manual/non-pressure compaction remains restart-safe without retaining stale headers.
+- Match the explicit Remote V2 tool-control contract used by current Codex and mature Responses compaction implementations: Native compact/replay send `tool_choice: "auto"` and `parallel_tool_calls: true` on the plain `openai-responses` route.
+- Preserve only bounded provider machine diagnostics (`code`, `type`, `param`) from `response.failed`; the safe identifiers are included in the generic failure message/log so DSH compaction history can diagnose failures, while provider messages/bodies remain excluded.
+- Persist Pi replay envelope v2 on successful Native replay finish so DSH retains response id/stop reason plus text/reasoning native metadata across post-compact turns.
+- Preserve normal Pi OpenAI function-call identity as `call_id|item_id` for replay deltas and completed tool-call blocks, preventing loss of the provider `fc_*` item id on the next canonical request.
+- Treat the session header `config` as the effective ordinary-request envelope even when DSH marks a value in `adapterDefaults`; those materialized defaults (for example Terra `xhigh` and `maxTokens`) are still sent by normal Pi and therefore must be mirrored by Native compact/replay.
+
+### Validation
+
+- `tests/rc13-regressions.test.mjs`: 15/15 passed.
+- Full local suite: 58/58 passed; DSH schema validation: 4/4 passed; `git diff --check` passed.
+- Installed DSH/NewAPI acceptance passed on Terra xhigh: automatic 90% Native V2 compact, continuous replay/cache re-warm, DSH Web restart/resume, real GUI `/compact` plus continuation, and parent→child fork portable isolation all completed without pre-Native stock prune or cross-session opaque replay.
+- This remains a local release candidate only; no npm/GitHub publication or tag is implied.
+
+## 0.4.0-rc.12 - 2026-08-22
+
+### Fixed
+
+- Serialize every `compactIfNeeded()` call per concrete preset compaction service so same-generation sessions cannot observe each other’s temporary Native-first pruner/config state; queued calls are abortable and plugin cleanup drains active owners before restoring the original method.
+- Align Native `openai-responses` session affinity with the active Pi adapter: default OpenAI-format routes use `session_id` plus `x-client-request-id`, while OpenRouter-format routes use `x-session-id`; explicit affinity headers remain authoritative.
+- Restrict Basic fallback to allowlisted retryable first-checkpoint failures and fail closed once a Native/legacy checkpoint already exists.
+- Require a real `response.completed` terminal event with `status=completed` for Native compaction/replay and reject orphan `function_call_output` items.
+- Set credential-bearing fetches to `redirect: error` and keep provider response bodies/messages out of surfaced/logged transport errors.
+
+## 0.4.0-rc.11 - 2026-08-22
+
+### Fixed
+
+- Restore ERR-051 cache/session affinity semantics that regressed in the rc.8 refactor: Native V2 compaction and same-route replay now use the DSH/Pi conversation session id as the clamped `prompt_cache_key` instead of a route fingerprint, inherit the active provider `cacheRetention`, emit `prompt_cache_retention: 24h` only for supported `long` retention, and omit Native cache affinity when retention is `none`.
+- Keep ordinary Hosted Search on its intentionally separate `dsh-lcx-search:<route hash>` namespace.
+
+## 0.4.0-rc.10 - 2026-08-22
+
+### Fixed
+
+- Fix Native-first pressure coordination for DSH 0.1.1-rc.2 Agent presets by using the public `agentPresets.serviceFor(agent, name)` resolver for preset-local `compaction` and `toolResultPruner` instances. This replaces the rc.9 assumption that ordinary `agent.ctx` lookup could see entry-local isolated services.
+
+## 0.4.0-rc.9 - 2026-08-22
+
+### Fixed
+
+- Restore the Alpha capability/ref-store interfaces consumed by `lib/index.js`; the rc.8 release package could pass its unit tests but fail immediately at module import with missing `AlphaCapabilityStore` / `AlphaRefStore` exports.
+- Add package-entry import regression coverage so CI fails when the server entry point and internal module exports drift out of sync.
+- Restore Native-first pressure coordination for isolated agent presets using DSH 0.1.1-rc.2's public `agentPresets.serviceFor(agent, name)` resolver. Preset-local `compaction` / `toolResultPruner` services are not visible through ordinary host or `agent.ctx` lookup; the plugin now addresses the actual per-Agent instances before applying the 90% Native / 95% emergency policy. A root service-lifecycle hook remains for non-preset deployments.
 ## 0.4.0-rc.8
 
 - Rebase the plugin on DSH `0.1.1-rc.2`; older DSH releases are no longer a supported runtime target.

package/README.md

@@ -209,7 +209,7 @@ dsh plugin --profile web add dsh-lcx-codex@next
 
 ```powershell
 dsh plugin --profile web remove dsh-lcx-codex
-dsh plugin --profile web add .\dsh-lcx-codex-0.4.0-rc.8.tgz
+dsh plugin --profile web add .\dsh-lcx-codex-0.4.0.tgz
 dsh web
 ```
 

package/lib/compact-v2.js

@@ -5,6 +5,10 @@ export const REMOTE_COMPACTION_V2_FEATURE = 'remote_compaction_v2'
 
 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 }
+function safeMachineField(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 96) return undefined
+  return /^[A-Za-z0-9_.:\[\]-]+$/u.test(value) ? value : undefined
+}
 
 export function mergeFeatureHeader(headers = {}) {
   const result = { ...headers }
@@ -15,7 +19,24 @@ export function mergeFeatureHeader(headers = {}) {
   return result
 }
 
-export function buildNativeCompactionBody({ model, input, instructions, tools, promptCacheKey }) {
+export function responsesGenerationEnvelope({ reasoningEffort, temperature, maxTokens } = {}) {
+  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) || maxTokens <= 0) throw fail('Responses maxTokens must be a positive safe integer', 'LCX_COMPACT_INVALID_INPUT')
+    result.max_output_tokens = Math.max(16, maxTokens)
+  }
+  return result
+}
+
+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) => item?.type === 'compaction_trigger')) throw fail('native compaction input already contains compaction_trigger', 'LCX_COMPACT_DUPLICATE_TRIGGER')
   const nativeTools = responsesTools(tools)
@@ -24,9 +45,13 @@ export function buildNativeCompactionBody({ model, input, instructions, tools, p
     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 }),
   }
 }
 
@@ -67,6 +92,7 @@ function validateOutput(output) {
     }
   }
   for (const id of calls) if (!results.has(id)) throw fail(`native compaction output has orphan function_call ${id}`)
+  for (const id of results) if (!calls.has(id)) throw fail(`native compaction output has orphan function_call_output ${id}`)
   return { output: structuredClone(output), compaction: structuredClone(compact) }
 }
 
@@ -89,14 +115,27 @@ export async function parseNativeCompactionSse(response, options = {}) {
   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
+      const upstream = event.type === 'response.failed' ? event.response?.error : event.error
+      const providerCode = safeMachineField(upstream?.code)
+      const providerType = safeMachineField(upstream?.type)
+      const providerParam = safeMachineField(upstream?.param)
+      const diagnostics = [
+        providerCode ? `providerCode=${providerCode}` : '',
+        providerType ? `providerType=${providerType}` : '',
+        providerParam ? `providerParam=${providerParam}` : '',
+      ].filter(Boolean).join(' ')
+      const e = fail(`native compaction ended with ${event.type}${diagnostics ? ` ${diagnostics}` : ''}`, 'LCX_COMPACT_UPSTREAM_ERROR')
+      if (Number.isInteger(upstream?.status ?? event.error?.status)) e.status = upstream?.status ?? event.error?.status
+      if (providerCode) e.providerCode = providerCode
+      if (providerType) e.providerType = providerType
+      if (providerParam) e.providerParam = providerParam
       throw e
     }
     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
+    if (event.type === 'response.completed') terminal = event.response
   }, options)
   if (!isObject(terminal)) throw fail('native compaction stream ended without response.completed', 'LCX_COMPACT_INCOMPLETE_SSE')
+  if (terminal.status !== 'completed') throw fail('native compaction response.completed did not carry completed status', '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)
@@ -108,8 +147,8 @@ export async function parseNativeCompactionSse(response, options = {}) {
   }
 }
 
-export async function requestNativeCompaction({ baseURL, model, input, instructions, tools, promptCacheKey, idempotencyKey, headers, signal, timeoutMs, maxAttempts, maxResponseBytes }) {
-  const body = buildNativeCompactionBody({ model, input, instructions, tools, promptCacheKey })
+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 })
   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

@@ -1,4 +1,7 @@
 import { offloadRequestImagesWithPolicy } from '@deepseek-ai/dsh-llm'
+import { convertResponsesMessages, convertResponsesTools } from '@earendil-works/pi-ai/api/openai-responses-shared'
+import { createGrammarToolInputProperties } from '@earendil-works/pi-ai/api/constrained-sampling'
+import { getBuiltinModels } from '@earendil-works/pi-ai/providers/all'
 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
@@ -12,14 +15,6 @@ function error(message, 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'
@@ -58,111 +53,195 @@ async function imagePart(block, ctx, options, imageMap) {
   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) }
-    }
+  return { type: 'input_image', detail: 'auto', image_url: imageUrl }
+}
+
+async function piImagePart(block, ctx, options, imageMap) {
+  if (options.imageSupport === 'unsupported') return { type: '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 data = image.data.toString('base64')
+  imageMap.set(`data:${image.mediaType};base64,${data}`, structuredClone(image.ref))
+  return { type: 'image', data, mimeType: image.mediaType }
+}
+
+function parseArguments(value) {
+  if (typeof value !== 'string') return value && typeof value === 'object' ? structuredClone(value) : {}
+  try {
+    const parsed = JSON.parse(value)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch { return {} }
+}
+
+function emptyUsage() {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }
+}
+
+function invalidReplay(message) { return error(`invalid pi-ai replay state: ${message}`, 'LCX_COMPACT_INVALID_REPLAY_STATE') }
+function unsupportedContent(type) { return error(`LCX Compact cannot safely serialize DSH message content type: ${String(type)}`, 'LCX_CHECKPOINT_PORTABLE_UNSUPPORTED_CONTENT') }
+function replayBlockType(type) { if (type === 'text') return 'text'; if (type === 'reasoning') return 'reasoning'; if (type === 'tool-call') return 'tool-call'; return undefined }
+
+export function readDshPiReplayState(value) {
+  if (!isObject(value)) throw invalidReplay('expected a replay envelope')
+  const response = value.response
+  if (!isObject(response)) throw invalidReplay('expected a response object')
+  if (response.kind !== 'pi-ai') throw invalidReplay('unknown state kind')
+  if (response.version !== 2) throw invalidReplay(`unsupported version ${String(response.version)}`)
+  for (const key of ['api', 'provider', 'model']) if (typeof response[key] !== 'string' || response[key].length === 0) throw invalidReplay(`${key} must be a non-empty string`)
+  if (!['stop', 'length', 'toolUse', 'error', 'aborted'].includes(response.stopReason)) throw invalidReplay('unknown stopReason')
+  if (response.responseModel !== undefined && typeof response.responseModel !== 'string') throw invalidReplay('responseModel must be a string')
+  if (response.responseId !== undefined && typeof response.responseId !== 'string') throw invalidReplay('responseId must be a string')
+  if (!Array.isArray(value.blocks)) throw invalidReplay('blocks must be an array')
+  for (const [index, block] of value.blocks.entries()) {
+    if (!isObject(block)) throw invalidReplay(`block ${index} must be an object`)
+    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`)
   }
-  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
+  return { response, blocks: value.blocks }
+}
+
+function foreignAssistant(message) {
+  const source = message?.source?.kind === 'model' ? message.source : undefined
+  const content = []
+  for (const block of message?.content ?? []) {
+    if (block?.type === 'text') content.push({ type: 'text', text: String(block.text ?? '') })
+    else if (block?.type === 'reasoning') content.push({ type: 'thinking', thinking: String(block.text ?? '') })
+    else if (block?.type === 'tool-call') content.push({ type: 'toolCall', id: String(block.id), name: String(block.name), arguments: parseArguments(block.arguments) })
+    else if (block?.type === 'image') throw unsupportedContent('assistant image')
+    else throw unsupportedContent(block?.type)
   }
-  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)) }
+  return { role: 'assistant', content, api: 'dsh-foreign', provider: source?.provider ?? 'dsh-foreign', model: source?.model ?? 'dsh-foreign', usage: emptyUsage(), stopReason: content.some((block) => block.type === 'toolCall') ? 'toolUse' : 'stop', timestamp: 0 }
+}
+
+function replayedAssistant(message, source) {
+  const state = readDshPiReplayState(source.replayState)
+  if (state.response.provider !== source.provider) throw invalidReplay('provider does not match assistant source')
+  if (state.response.model !== source.model) throw invalidReplay('model does not match assistant source')
+  if (state.blocks.length !== (message?.content ?? []).length) throw invalidReplay('block count does not match assistant content')
+  const content = (message.content ?? []).map((block, index) => {
+    const replay = state.blocks[index]
+    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 { 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 }
+}
+
+function toPiAssistant(message, onReplayDegrade) {
+  const source = message?.source
+  if (source?.kind !== 'model' || source.replayState === undefined) return foreignAssistant(message)
+  try { return replayedAssistant(message, source) }
+  catch (cause) {
+    if (cause?.code !== 'LCX_COMPACT_INVALID_REPLAY_STATE') throw cause
+    onReplayDegrade?.(cause.message)
+    return foreignAssistant(message)
+  }
+}
+
+async function piToolContent(blocks, ctx, options, imageMap) {
+  const content = []
+  for (const block of blocks ?? []) {
+    if (block?.type === 'text') content.push({ type: 'text', text: String(block.text ?? '') })
+    else if (block?.type === 'image') content.push(await piImagePart(block, ctx, options, imageMap))
+    else if (block?.type === 'tool-result') content.push(...await piToolContent(block.content, ctx, options, imageMap))
+  }
+  return content.length > 0 ? content : [{ type: 'text', text: '(no output)' }]
+}
+
+async function dshToPiMessages(messages, ctx, options, imageMap) {
+  const result = []
+  for (const message of messages ?? []) {
+    if (message?.role === 'system') continue
+    if (message?.role === 'assistant') { result.push(toPiAssistant(message, options.onReplayDegrade)); continue }
+    if (message?.role !== 'user') continue
+    const ordinary = (message.content ?? []).filter((block) => block?.type === 'text' || block?.type === 'image')
+    if (ordinary.length > 0) {
+      const content = []
+      for (const block of ordinary) content.push(block.type === 'text' ? { type: 'text', text: String(block.text ?? '') } : await piImagePart(block, ctx, options, imageMap))
+      if (content.length > 0) result.push({ role: 'user', content, timestamp: 0 })
     }
-    flush()
-    if (content.length > 0) items.push({ type: 'message', role: 'user', content })
+    for (const block of (message.content ?? []).filter((value) => value?.type === 'tool-result')) result.push({ role: 'toolResult', toolCallId: String(block.toolCallId), toolName: String(block.toolName ?? block.name ?? 'unknown'), content: await piToolContent(block.content, ctx, options, imageMap), addedToolNames: block.addedToolNames ?? message.addedToolNames ?? [], isError: block.isError === true, timestamp: 0 })
   }
-  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 result
+}
+
+function builtinResponsesModel(provider, modelId) {
+  try { return getBuiltinModels(String(provider ?? '')).find((model) => model?.id === modelId && model?.api === 'openai-responses') }
+  catch { return undefined }
+}
+
+function piModel(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')
+  const id = String(explicit?.id ?? route.model ?? 'unknown')
+  const builtin = builtinResponsesModel(provider, id)
+  const compat = { ...(builtin?.compat ?? {}), ...(options.responsesCompat ?? {}), ...(explicit?.compat ?? {}) }
+  const input = options.imageSupport === 'supported' ? ['text', 'image'] : options.imageSupport === 'unsupported' ? ['text'] : (explicit?.input ?? builtin?.input ?? ['text'])
+  return {
+    ...(builtin ?? {}), ...(explicit ?? {}), id, name: String(explicit?.name ?? builtin?.name ?? id), api: 'openai-responses', provider,
+    baseUrl: String(explicit?.baseUrl ?? route.baseURL ?? builtin?.baseUrl ?? ''), reasoning: typeof explicit?.reasoning === 'boolean' ? explicit.reasoning : (builtin?.reasoning ?? true), input,
+    cost: explicit?.cost ?? builtin?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: Number(explicit?.contextWindow ?? builtin?.contextWindow) > 0 ? Number(explicit?.contextWindow ?? builtin?.contextWindow) : 262144,
+    maxTokens: Number(explicit?.maxTokens ?? builtin?.maxTokens) > 0 ? Number(explicit?.maxTokens ?? builtin?.maxTokens) : 32768,
+    ...(Object.keys(compat).length > 0 ? { compat } : {}),
+  }
+}
+
+function splitDeferredTools(context, enabled) {
+  const unique = new Map()
+  for (const tool of context.tools ?? []) if (tool?.name) unique.set(tool.name, tool)
+  if (!enabled) return { immediate: [...unique.values()], deferred: new Map() }
+  const deferredNames = new Set(); const usedNames = new Set()
+  for (const message of context.messages ?? []) {
+    if (message.role === 'assistant') {
+      for (const block of message.content ?? []) if (block.type === 'toolCall') usedNames.add(block.name)
+    } else if (message.role === 'toolResult') {
+      for (const name of message.addedToolNames ?? []) if (!usedNames.has(name)) deferredNames.add(name)
+    }
   }
-  return items
+  const immediate = []; const deferred = new Map()
+  for (const [name, tool] of unique) { if (deferredNames.has(name)) deferred.set(name, tool); else immediate.push(tool) }
+  return { immediate, deferred }
 }
 
 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,
+    imageSupport: options.imageSupport ?? 'unknown', signal: options.signal, route: options.route ?? {}, model: options.model, responsesCompat: options.responsesCompat,
+    systemPrompt: typeof options.systemPrompt === 'string' ? options.systemPrompt : undefined, includeSystemPrompt: options.includeSystemPrompt === true, onReplayDegrade: options.onReplayDegrade,
+    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),
+  const projected = offloadRequestImagesWithPolicy(messages ?? [], { representation: 'base64', maxBytes: normalized.maxRequestImageBytes, byteQuantum: 1, byteLength: ref => Math.min(ref.bytes, normalized.requestImageMaxBytes) })
+  const model = piModel(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 supportsToolSearch = model.compat?.supportsToolSearch ?? false
+  const grammarToolInputProperties = createGrammarToolInputProperties(context.tools, supportsOpenAIGrammarTools)
+  const placement = splitDeferredTools(context, supportsToolSearch)
+  const toolOptions = { supportsStrictMode, supportsOpenAIGrammarTools }
+  const input = convertResponsesMessages(model, context, new Set(['openai', 'openai-codex', 'opencode']), {
+    includeSystemPrompt: normalized.includeSystemPrompt, grammarToolInputProperties, deferredTools: placement.deferred, toolOptions,
   })
-  for (const message of projected) {
-    if (message?.role === 'system') continue
-    input.push(...await messageItems(message, ctx, normalized, imageMap))
-  }
-  return { input, imageMap }
+  const tools = options.tools === undefined ? undefined : convertResponsesTools(placement.immediate, toolOptions)
+  return { input, imageMap, tools }
 }
 
 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,
-    }
-  })
+  if (tools.every((tool) => isObject(tool) && typeof tool.type === 'string')) return structuredClone(tools)
+  for (const tool of tools) if (!isObject(tool) || typeof tool.name !== 'string' || !tool.name) throw error('LCX Responses tool has no name', 'LCX_COMPACT_INVALID_TOOLS')
+  return convertResponsesTools(tools, { supportsStrictMode: false, supportsOpenAIGrammarTools: false })
 }
 
+function isResponsesMessageItem(item) { return isObject(item) && typeof item.role === 'string' && (item.type === undefined || item.type === 'message') }
+
 function mapImageParts(value, mapper) {
   if (!Array.isArray(value)) return value
   return value.map((part) => {
@@ -181,7 +260,7 @@ export function persistNativeImageReferences(output, imageMap) {
     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 (isResponsesMessageItem(item) && 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)
   })
@@ -206,7 +285,7 @@ export async function hydrateNativeImageReferences(output, ctx, options = {}) {
   }
   const result = []
   for (const item of output ?? []) {
-    if (item?.type === 'message' && Array.isArray(item.content)) {
+    if (isResponsesMessageItem(item) && Array.isArray(item.content)) {
       const content = []
       for (const part of item.content) content.push(await hydratePart(part, ctx, normalized))
       result.push({ ...structuredClone(item), content })