dsh-lcx-codex 0.4.0 → 0.4.1

package/README_EN.md

@@ -1,194 +1,213 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/kk3ya03-star/dsh-lcx-codex/main/assets/dsh-lcx-codex-banner.jpg" alt="DSH-LCX-CODEX" width="100%" />
+<img src="assets/dsh-lcx-codex-banner-en.png" alt="dsh-lcx-codex — GPT Hosted Search, Codex-style Web Actions, and Native V2 Compaction for DSH" width="100%" />
 
-# DSH-LCX-CODEX
-
-**OpenAI Responses / Codex-native capabilities for DeepSeek Harness.**
-
-[![npm](https://img.shields.io/npm/v/dsh-lcx-codex?color=1677ff&label=npm)](https://www.npmjs.com/package/dsh-lcx-codex)
-![Node](https://img.shields.io/badge/Node-%3E%3D20-1677ff)
+[![npm](https://img.shields.io/npm/v/dsh-lcx-codex?color=1677ff&label=npm%20latest)](https://www.npmjs.com/package/dsh-lcx-codex)
+[![CI](https://github.com/kk3ya03-star/dsh-lcx-codex/actions/workflows/publish.yml/badge.svg)](https://github.com/kk3ya03-star/dsh-lcx-codex/actions/workflows/publish.yml)
 ![DSH](https://img.shields.io/badge/DSH-0.1.1--rc.2-4ea8ff)
-![License](https://img.shields.io/badge/license-MIT-1677ff)
+![Node](https://img.shields.io/badge/Node-%3E%3D20-2f855a)
+![License](https://img.shields.io/badge/license-MIT-6b7280)
 
-[简体中文](README.md) · **English**
+[简体中文](README.md) · **English** · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md)
 
 </div>
 
----
+> **DSH remains the host. LCX adds missing native capabilities to GPT Responses routes without modifying DSH core or replacing Agent / Session / Web / Compaction.**
 
-`dsh-lcx-codex` is a community DSH plugin for GPT routes already configured through `llm-pi-ai / openai-responses`. It keeps DSH's Agent, Web, Session and Compaction ownership intact and fills the provider-native gaps.
+## Current stable release
 
-> `LCX` is only the project name. This project is not affiliated with OpenAI, DeepSeek, Sub2API or NewAPI.
+`0.4.1` is the current stable release. It is a **zero-functional-change stable promotion** of `0.4.1-pre.1`, which already passed full Installed Candidate and Cross-feature QA.
 
-- **Current DSH image pipeline**: Native V2 reuses `readImageRequest()` and the active route image budgets, so compaction and ordinary GPT requests see the same deterministic image variants.
+```powershell
+dsh plugin --profile web add dsh-lcx-codex
+dsh web
+```
 
-## Features
+npm `latest` points to `0.4.1`. Historical `prelatest=0.4.1-pre.1` uses the same accepted runtime baseline; new users should install `latest`.
 
-| Capability | What it does | Default |
-|---|---|---:|
-| **DSH `web_search` → GPT Hosted Search** | Uses DSH's existing ordinary search tool; rc.7+ follows the active Agent GPT Responses model | opt-in |
-| **Advanced Hosted Search** | Native domain/location/context/image search controls | off |
-| **Alpha Search** | Stateful `search/open/find/click/screenshot`-style commands, capability-gated | off |
-| **Native Remote Compaction V2** | Uses Responses `compaction_trigger` and provider-native opaque state | opt-in |
-| **Conversation fidelity retention** | Bounded user + assistant-visible history protects low-salience facts | built-in |
-| **Session-native checkpoints** | Durable state lives in the DSH append-only session log | built-in |
-| **Native-first auto compaction** | 90% Native V2, 95% emergency DSH pruning; configurable | opt-in |
-| **Long web timeout** | DSH `web_search` deadline defaults to 240s, configurable 30–600s | built-in |
+## What it solves
 
-## rc.8: DSH 0.1.1-rc.2 native alignment
+If DSH already has a working GPT `openai-responses` route, `dsh-lcx-codex` fills Responses capability gaps while preserving DSH entry points and lifecycle ownership.
 
-rc.8 targets **DSH 0.1.1-rc.2** directly. Ordinary Hosted Search still follows the active Agent route, while Native V2 image serialization now uses DSH's `readImageRequest()` request-version pipeline instead of reading attachment master bytes.
+| Scenario | Existing DSH surface | With LCX |
+|---|---|---|
+| Ordinary web search | DSH `web_search` | Keep the same `web_search`; LCX maps its SearchProvider to GPT Hosted Search |
+| Advanced Hosted controls | Ordinary search stays simple | Optional `websearch_gpt_advanced` for domain filters, approximate location, search context, image search, and related controls |
+| Stateful page / PDF browsing | DSH keeps Web lifecycle ownership | Optional Codex / Alpha actions: `search → open → find/click → screenshot` |
+| Long-session compaction | DSH keeps pressure, transactions, and recovery | Prefer Responses Native V2 checkpoints at the existing compaction seam |
 
-Search routing still crosses DSH's `tools/execute` → SearchProvider boundary without changing the model-visible `web_search` schema:
+**The goal is not to build another Agent stack. It is to let a DSH GPT route use the native capabilities it should already have access to.**
 
-```text
-Agent: lcx / gpt-5.6-luna
-        └─ DSH web_search
-             └─ Hosted Search: lcx / gpt-5.6-luna
-```
+## Core capabilities
 
-The settings-page model is now a **fallback** used only when no active Agent route is available.
+### GPT Hosted Search
 
-Hosted Search also receives its own stable cache namespace:
+The model still sees DSH's ordinary `web_search`; LCX changes the SearchProvider path instead of registering a duplicate ordinary-search tool. Enable `websearch_gpt_advanced` only when you need additional Hosted Search controls.
 
-```text
-conversation replay: dsh-lcx:<route hash>
-hosted search:       dsh-lcx-search:<route hash>
-```
+### Codex-style Web Actions
 
-A search row with a low cache hit in NewAPI therefore does not imply conversation truncation.
-
-## Native V2 Compaction
-
-DSH continues to own pressure, range selection, pruning, durable replacement, `/compact`, and overflow recovery. The plugin replaces only the `purpose: compaction` summarizer transport with Native V2:
+`websearch_alpha` supports stateful browsing:
 
 ```text
-DSH compaction transaction
-        └─ purpose=compaction
-              └─ /responses + compaction_trigger
+search → open → find / click → screenshot
 ```
 
-Native success means zero basic-summary request. Basic summary runs only if Native fails and fallback is enabled.
+It is off by default and registered only when the current endpoint / provider / model / schema passes capability checks. Unknown deployments fail closed.
+
+`0.4.1` includes the URL/stateful-continuation and capability fail-closed fixes that were accepted on the prerelease line.
 
-## Conversation fidelity layer
+### Native V2 Compaction
 
-Provider-native opaque compaction is intentionally lossy. Real long-session tests showed that assistant-only details can disappear even when the opaque checkpoint itself is valid. The current checkpoint therefore keeps:
+LCX does not create a second compaction engine. DSH still owns pressure, compactable ranges, `/compact`, durable session transactions, pruning, and overflow recovery. LCX requests Responses Native V2 through the existing compaction seam.
 
 ```text
-bounded client-visible history
-+ bounded assistant-visible final answers
-+ opaque Native V2 compaction item
+0% ─────────────────── 90% ───── 95% ───── 100%
+       normal            Native      emergency   hard cap
+                         V2          DSH prune
 ```
 
-The explicit prefix is bounded at roughly 64k estimated tokens, with up to about 24k reserved for assistant answers and about 3k per retained assistant answer. Reasoning, raw tool traces, large search payloads and telemetry are not copied back into the prompt.
+- **90%**: prefer Native V2.
+- **95%**: allow emergency DSH pruning.
+- provider-confirmed context overflow: keep DSH's original recovery.
+- manual `/compact`: keep the native DSH transaction.
 
-The goal is not byte-for-byte replay. It is **drop process noise, retain conversation facts**.
+Native opaque state stays source-session bound. Forks and model/route migrations use portable migration rather than sending a parent's opaque state across sessions; restart/resume rebuilds from the DSH session log.
 
-## Automatic compaction
+## What changed from 0.4.0
 
-```text
-0% -------------------- 90% ----- 95% ----- 100%
-        normal             Native   emergency   hard cap
-                           V2       DSH prune
-```
+`0.4.1` promotes the already accepted `0.4.1-pre.1` changes to stable:
 
-Default behavior:
+- Alpha URL/stateful continuation and fail-closed capability fixes;
+- DSH compatibility-seam isolation;
+- typed protocol core for route / Native V2 / checkpoint handling;
+- unified conservative token budgeting for Native retention and portable migration;
+- installed settings namespace / configuration-card lifecycle fix;
+- Installed Candidate + Cross-feature QA.
 
-- below 90%: suppress stock 80% pressure pruning for compatible Native sessions;
-- 90–95%: Native V2 first;
-- 95%+: DSH's replay-safe tool-result pruning may run as an emergency guard;
-- provider-confirmed context overflow keeps DSH's normal recovery path;
-- manual `/compact` is unaffected.
+The stable promotion itself adds no new runtime behavior.
 
-## Cache behavior
+## Get started
 
-A provider cache miss is not the same thing as DSH deleting history.
+### Install stable
 
-Observed real-world pattern:
-
-```text
-turn N:   ~155k uncached, cacheRead 0
-turn N+1: ~1k new input, ~155k cacheRead
+```powershell
+dsh plugin --profile web add dsh-lcx-codex
+dsh web
 ```
 
-That means the full context was resent and cached again. Prefix-changing operations include compaction, emergency pruning, route/model changes, and other DSH surface replacement. Restart/idle/provider cache TTL may also force a cold request independently of this plugin.
+Pin the exact version if needed:
 
-## Search modes
+```powershell
+dsh plugin --profile web add dsh-lcx-codex@0.4.1
+```
 
-### Ordinary `web_search`
+Use the official DSH plugin remove/add path when upgrading. Do not delete user sessions or `$DSH_HOME/storages/lcx-codex/` just to change versions.
 
-Recommended default. It follows the current Agent GPT Responses route.
+### Suggested first-run settings
 
-### `websearch_gpt_advanced`
+| Setting | Suggested value |
+|---|---:|
+| Enable plugin | **On** |
+| Use GPT Hosted Search | On when needed |
+| Advanced Hosted Search | Off until needed |
+| Alpha Search | Off until route capability is confirmed |
+| Native V2 remote compaction | On only when upstream supports it |
+| Native-first auto compaction | On when using Native V2 |
 
-Opt in only for Hosted-only parameters such as domain filters, approximate location, search-context size and image search. Keeping it disabled avoids unnecessary tool-catalog churn.
+Requirements: Node.js `>=20`, a working GPT `openai-responses` route in DSH, and actual upstream support for the capabilities you enable.
 
-### `websearch_alpha`
+## Verify observable behavior
 
-Stateful Codex/Alpha-style `search/open/find/click/screenshot`; registered only after a matching capability probe.
+| Capability | Expected behavior |
+|---|---|
+| GPT Hosted Search | Ordinary entry remains DSH `web_search`; the request follows the active GPT Responses route |
+| Advanced Hosted | `websearch_gpt_advanced` appears only when enabled |
+| Alpha Web Actions | `websearch_alpha` appears only after capability validation |
+| Native V2 | Compaction follows the provider-native checkpoint path; Basic Compaction is not mislabeled as Native V2 |
 
-## Installation
+## Which search tool should I use?
 
-Stable channel:
+| Goal | Entry | Best for |
+|---|---|---|
+| Ordinary web lookup | DSH `web_search` | General search, research, and retrieval |
+| Control Hosted Search parameters | `websearch_gpt_advanced` | Domain allow/block, approximate location, search context, image search, and related controls |
+| Browse pages or PDFs statefully | `websearch_alpha` | `search/open/find/click/screenshot` and structured Web actions |
 
-```powershell
-dsh plugin --profile web add dsh-lcx-codex
+## How it fits into DSH
+
+```text
+DSH Agent / Session / Web
+├─ web_search ──────────> LCX SearchProvider ──> GPT Hosted Search
+├─ Advanced / Alpha ────> LCX Web tools ───────> GPT Web actions
+└─ compact / replay ────> LCX Native bridge ───> Responses Native V2
 ```
 
-Pre-release channel (current rc.8):
+**DSH is the host; LCX is a compatibility extension.** It reuses the active DSH route's `baseURL`, configured authentication reference, headers, model, and retry policy rather than maintaining a second account configuration.
 
-```powershell
-dsh plugin --profile web add dsh-lcx-codex@next
-```
+See [ARCHITECTURE.md](ARCHITECTURE.md) for checkpoint, replay, Pi serialization, cache identity, fork safety, and pressure-coordination details.
 
-Local RC:
+## Compatibility
 
-```powershell
-dsh plugin --profile web remove dsh-lcx-codex
-dsh plugin --profile web add .\dsh-lcx-codex-0.4.0-rc.8.tgz
-dsh web
-```
+Current formally stable stack:
 
-Do not delete existing sessions or `$DSH_HOME/storages/lcx-codex/` just to upgrade. The legacy v3 sidecar remains read-only compatibility state.
+| Plugin | DSH | DSH host Pi | Plugin Pi | Status |
+|---|---|---|---|---|
+| `0.4.1` | `0.1.1-rc.2` | `0.82.1` | `0.82.1` | **VERIFIED STABLE** |
 
-## Recommended settings
+`0.4.1` uses the fully QA-passed `0.4.1-pre.1` runtime, and the stable promotion is zero-functional-change. New DSH releases are **not** assumed compatible without seam review and risk-appropriate testing.
 
-```text
-Enable plugin                         on
-GPT Hosted Search                     on
-Advanced Hosted Search               off
-Alpha Search                         off
-Native V2 remote compaction          on
-Native-first auto compaction         on
-Native threshold                     90%
-Emergency DSH prune                  95%
-web_search timeout                   240s
-```
+<details>
+<summary><strong>Recommended settings</strong></summary>
+
+| Setting | Recommended | Notes |
+|---|---:|---|
+| Enable plugin | On | Enables LCX |
+| Use GPT Hosted Search | As needed | Routes DSH `web_search` through GPT Hosted Search |
+| Advanced Hosted Search | Off | Enable only for advanced Hosted parameters |
+| Alpha Search | Off | Enable after capability verification |
+| Native V2 remote compaction | On* | *When the upstream route actually supports Native V2 |
+| Native-first auto compaction | On | Enables automatic pressure coordination |
+| Native threshold | 90% | Prefer Native V2 from 90% |
+| Emergency DSH prune | 95% | Allow emergency prune from 95% |
+| `web_search` timeout | 240 s | Avoid false timeout on longer searches |
 
-## Requirements
+</details>
 
-- Node.js >= 20
-- DSH 0.1.1-rc.2
-- a working GPT `openai-responses` route in DSH
-- an upstream that actually supports the enabled Hosted Search / Native V2 / Alpha capabilities
+<details>
+<summary><strong>Common cases</strong></summary>
 
-Typical paths include direct Sub2API and NewAPI-relayed Responses routes.
+**`web_search` is not using GPT Hosted Search**  
+Make sure the plugin and Hosted Search are enabled and that the active Agent resolves to a compatible GPT `openai-responses` route.
 
-## Release channels
+**`websearch_alpha` is missing**  
+That is expected fail-closed behavior. Alpha is registered only after a trusted capability probe succeeds for the current route/schema.
 
-Stable releases use npm's `latest` tag. `0.4.0-rc.*` builds publish to npm's `next` tag. GitHub tags must match `package.json`; Trusted Publishing runs tests before publishing.
+**Native V2 is not taking effect**  
+Verify that the current GPT Responses endpoint actually supports `remote_compaction_v2`. The plugin does not present ordinary Basic Compaction as a successful Native V2 run.
 
-## Development
+**Installed but no configuration card is visible**  
+Make sure you are on `0.4.1` or later and restart/refresh DSH Web. `0.4.1` includes the installed settings lifecycle fix.
+
+</details>
+
+<details>
+<summary><strong>Development</strong></summary>
 
 ```bash
+npm run typecheck
 npm test
 npm run test:schema
 npm pack --ignore-scripts
 ```
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) and [CHANGELOG.md](CHANGELOG.md) for implementation details.
+- Design: [ARCHITECTURE.md](ARCHITECTURE.md)
+- Releases: [CHANGELOG.md](CHANGELOG.md)
+- npm: [`dsh-lcx-codex`](https://www.npmjs.com/package/dsh-lcx-codex)
+
+</details>
 
 ## License
 
 MIT
+
+> `LCX` is only the project name. This is a community project and is not affiliated with OpenAI, DeepSeek, Sub2API, or NewAPI.

package/lib/compact-v2.js

@@ -1,15 +1,89 @@
+// @ts-check
+
 import { consumeSse, fetchSseWithRetry } from './transport.js'
 import { responsesTools } from './dsh-responses.js'
 
+/** @typedef {Record<string, unknown>} UnknownRecord */
+/** @typedef {Record<string, string>} HeaderMap */
+/** @typedef {Error & { code?: string, status?: number, providerCode?: string, providerType?: string, providerParam?: string }} LcxError */
+/** @typedef {{ type: 'compaction', encrypted_content: string }} CompactionItem */
+/** @typedef {{ type: 'function_call', call_id: string }} FunctionCallItem */
+/** @typedef {{ type: 'function_call_output', call_id: string }} FunctionCallOutputItem */
+/** @typedef {CompactionItem | FunctionCallItem | FunctionCallOutputItem | { type: string }} ValidatedOutputItem */
+/** @typedef {{ inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number, reasoningTokens?: number }} CanonicalUsage */
+/** @typedef {{ reasoningEffort?: unknown, temperature?: unknown, maxTokens?: unknown }} GenerationControls */
+/** @typedef {{ reasoning?: { effort: string, summary: 'auto' }, include?: string[], temperature?: number, max_output_tokens?: number }} GenerationEnvelope */
+/**
+ * @typedef {object} NativeCompactionBodyOptions
+ * @property {string} model
+ * @property {unknown[]} input
+ * @property {string} [instructions]
+ * @property {unknown} [tools]
+ * @property {string} [promptCacheKey]
+ * @property {string} [promptCacheRetention]
+ * @property {unknown} [reasoningEffort]
+ * @property {unknown} [temperature]
+ * @property {unknown} [maxTokens]
+ */
+/**
+ * @typedef {object} NativeCompactionBody
+ * @property {string} model
+ * @property {unknown[]} input
+ * @property {true} stream
+ * @property {false} store
+ * @property {'auto'} tool_choice
+ * @property {true} parallel_tool_calls
+ * @property {string} [instructions]
+ * @property {unknown[]} [tools]
+ * @property {string} [prompt_cache_key]
+ * @property {string} [prompt_cache_retention]
+ * @property {{ effort: string, summary: 'auto' }} [reasoning]
+ * @property {string[]} [include]
+ * @property {number} [temperature]
+ * @property {number} [max_output_tokens]
+ */
+/**
+ * @typedef {NativeCompactionBodyOptions & {
+ *   baseURL: string,
+ *   idempotencyKey?: string,
+ *   headers?: HeaderMap,
+ *   signal?: AbortSignal,
+ *   timeoutMs?: number,
+ *   maxAttempts?: number,
+ *   maxResponseBytes?: number
+ * }} NativeCompactionRequestOptions
+ */
+/** @typedef {{ signal?: AbortSignal, maxResponseBytes?: number }} SseParseOptions */
+/** @typedef {{ object: unknown, id?: string, output: ValidatedOutputItem[], compaction: CompactionItem, usage?: CanonicalUsage }} NativeCompactionResult */
+
 export const REMOTE_COMPACTION_V2_FEATURE = 'remote_compaction_v2'
 
+/**
+ * @param {unknown} value
+ * @returns {value is UnknownRecord}
+ */
 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 }
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {LcxError}
+ */
+function fail(message, code = 'LCX_COMPACT_INVALID_RESPONSE') {
+  /** @type {LcxError} */
+  const e = new Error(message)
+  e.code = code
+  return e
+}
+/** @param {unknown} value */
 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
 }
 
+/**
+ * @param {HeaderMap} [headers]
+ * @returns {HeaderMap}
+ */
 export function mergeFeatureHeader(headers = {}) {
   const result = { ...headers }
   const key = Object.keys(result).find((name) => name.toLowerCase() === 'x-codex-beta-features')
@@ -19,7 +93,12 @@ export function mergeFeatureHeader(headers = {}) {
   return result
 }
 
+/**
+ * @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' }
@@ -30,15 +109,20 @@ export function responsesGenerationEnvelope({ reasoningEffort, temperature, maxT
     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)
+    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
 }
 
+/**
+ * @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) => item?.type === 'compaction_trigger')) throw fail('native compaction input already contains compaction_trigger', 'LCX_COMPACT_DUPLICATE_TRIGGER')
+  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,
@@ -55,31 +139,43 @@ export function buildNativeCompactionBody({ model, input, instructions, tools, p
   }
 }
 
+/**
+ * Provider usage stays unknown until the object guard and numeric normalization.
+ * @param {unknown} raw
+ * @returns {CanonicalUsage | undefined}
+ */
 function usageFrom(raw) {
   if (!isObject(raw)) return undefined
   const inputTotal = Number(raw.input_tokens ?? 0)
   const output = Number(raw.output_tokens ?? 0)
-  const details = raw.input_tokens_details ?? raw.input_token_details ?? raw.prompt_tokens_details ?? {}
+  const details = /** @type {UnknownRecord} */ (raw.input_tokens_details ?? raw.input_token_details ?? raw.prompt_tokens_details ?? {})
   const cacheRead = Number(details.cached_tokens ?? 0)
   const cacheWrite = Number(details.cache_write_tokens ?? 0)
+  /** @type {CanonicalUsage} */
   const result = {
     inputTokens: Math.max(0, Number.isFinite(inputTotal) ? inputTotal - (Number.isFinite(cacheRead) ? cacheRead : 0) - (Number.isFinite(cacheWrite) ? cacheWrite : 0) : 0),
     outputTokens: Number.isFinite(output) && output > 0 ? output : 0,
   }
   if (Number.isFinite(cacheRead) && cacheRead > 0) result.cacheReadTokens = cacheRead
   if (Number.isFinite(cacheWrite) && cacheWrite > 0) result.cacheWriteTokens = cacheWrite
-  const reasoning = Number(raw.output_tokens_details?.reasoning_tokens ?? raw.output_token_details?.reasoning_tokens ?? 0)
+  const reasoning = Number(/** @type {UnknownRecord | undefined} */ (raw.output_tokens_details)?.reasoning_tokens ?? /** @type {UnknownRecord | undefined} */ (raw.output_token_details)?.reasoning_tokens ?? 0)
   if (Number.isFinite(reasoning) && reasoning > 0) result.reasoningTokens = reasoning
   return Object.values(result).some((v) => Number(v) > 0) ? result : undefined
 }
 
+/**
+ * @param {unknown} output
+ * @returns {{ output: ValidatedOutputItem[], compaction: CompactionItem }}
+ */
 function validateOutput(output) {
   if (!Array.isArray(output) || output.length === 0) throw fail('native compaction output is empty')
   const compactions = output.filter((item) => isObject(item) && item.type === 'compaction')
   if (compactions.length !== 1) throw fail(`native compaction must return exactly one compaction item, got ${compactions.length}`)
   const compact = compactions[0]
   if (typeof compact.encrypted_content !== 'string' || compact.encrypted_content.length === 0) throw fail('native compaction item has no encrypted_content')
+  /** @type {Set<string>} */
   const calls = new Set()
+  /** @type {Set<string>} */
   const results = new Set()
   for (const item of output) {
     if (!isObject(item) || typeof item.type !== 'string') throw fail('native compaction output contains a malformed item')
@@ -93,16 +189,29 @@ 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) }
+  return {
+    output: /** @type {ValidatedOutputItem[]} */ (structuredClone(output)),
+    compaction: /** @type {CompactionItem} */ (structuredClone(compact)),
+  }
 }
 
+/**
+ * Provider SSE events enter as unknown; response.completed remains authoritative.
+ * @param {Response} response
+ * @param {SseParseOptions} [options]
+ * @returns {Promise<NativeCompactionResult>}
+ */
 export async function parseNativeCompactionSse(response, options = {}) {
+  /** @type {Map<number, UnknownRecord>} */
   const byIndex = new Map()
+  /** @type {Map<string, UnknownRecord>} */
   const byId = new Map()
+  /** @type {UnknownRecord | undefined} */
   let terminal
+  /** @param {UnknownRecord} event */
   const mergeItem = (event) => {
     if (!isObject(event?.item)) return
-    const index = Number.isInteger(event.output_index) ? event.output_index : undefined
+    const index = Number.isInteger(event.output_index) ? /** @type {number} */ (event.output_index) : undefined
     const id = typeof event.item.id === 'string' ? event.item.id : typeof event.item_id === 'string' ? event.item_id : undefined
     let record = (index !== undefined ? byIndex.get(index) : undefined) ?? (id ? byId.get(id) : undefined)
     if (!record) record = {}
@@ -112,27 +221,28 @@ export async function parseNativeCompactionSse(response, options = {}) {
     if (index !== undefined) byIndex.set(index, record)
     if (id) byId.set(id, record)
   }
-  await consumeSse(response, (event) => {
+  await consumeSse(response, (/** @type {unknown} */ event) => {
     if (!isObject(event)) return
     if (event.type === 'error' || event.type === 'response.failed' || event.type === 'response.incomplete') {
-      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 upstream = event.type === 'response.failed' ? /** @type {{ error?: unknown } | undefined} */ (event.response)?.error : event.error
+      const providerCode = safeMachineField(/** @type {UnknownRecord | undefined} */ (upstream)?.code)
+      const providerType = safeMachineField(/** @type {UnknownRecord | undefined} */ (upstream)?.type)
+      const providerParam = safeMachineField(/** @type {UnknownRecord | undefined} */ (upstream)?.param)
       const diagnostics = [
         providerCode ? `providerCode=${providerCode}` : '',
         providerType ? `providerType=${providerType}` : '',
         providerParam ? `providerParam=${providerParam}` : '',
       ].filter(Boolean).join(' ')
+      /** @type {LcxError} */
       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 (Number.isInteger(/** @type {UnknownRecord | undefined} */ (upstream)?.status ?? /** @type {UnknownRecord | undefined} */ (event.error)?.status)) e.status = /** @type {number} */ (/** @type {UnknownRecord | undefined} */ (upstream)?.status ?? /** @type {UnknownRecord | undefined} */ (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') terminal = event.response
+    if (event.type === 'response.completed') terminal = /** @type {UnknownRecord} */ (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')
@@ -147,12 +257,15 @@ 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 })
   const requestHeaders = mergeFeatureHeader({ ...headers, ...(idempotencyKey ? { 'idempotency-key': String(idempotencyKey) } : {}) })
   return fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, '')}/responses`, body, requestHeaders, signal, timeoutMs, {
     maxAttempts,
     maxResponseBytes,
-    consume: (response, consumeOptions) => parseNativeCompactionSse(response, { signal: consumeOptions.requestSignal ?? signal, maxResponseBytes }),
+    consume: (/** @type {Response} */ response, /** @type {{ requestSignal?: AbortSignal }} */ consumeOptions) => parseNativeCompactionSse(response, { signal: consumeOptions.requestSignal ?? signal, maxResponseBytes }),
   })
 }