dsh-lcx-codex 0.3.3 → 0.4.0-rc.13

package/ARCHITECTURE.md

@@ -0,0 +1,93 @@
+
+## rc.6 pressure coordination
+
+DSH 0.1.1-rc.2 `compaction-basic` defaults to a `0.8` pressure threshold and, once pressure qualifies, runs `toolResultPruner` before summary compaction. Real long-session traces showed that a large prune can reduce the measured surface below 80%, preventing the Native summarizer from running while still rewriting an old request prefix and invalidating cache. rc.6 coordinates the existing engine instead of replacing it:
+
+- for a compatible GPT Responses route with Native auto-compaction enabled, `compactIfNeeded(..., "pressure")` returns `null` below the configured Native threshold (default 90%), so the stock 80% path does not mutate history;
+- from 90% up to the emergency threshold, the existing engine still owns range selection and the durable transaction, but `toolResultPruner.pruneSession()` is temporarily suppressed for that call; the engine's summary transport therefore reaches the existing `purpose=compaction` Native V2 override first;
+- at the emergency threshold (default 95%) or above, the pruner is no longer suppressed and DSH may shrink oversized tool results before attempting summary compaction;
+- provider-confirmed context overflow continues to use DSH's original `context-overflow` recovery unchanged;
+- manual `/compact` remains unchanged.
+
+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
+
+`dsh-tool-web` stores the cooperative search deadline only in `ToolDefinition.timeoutMs`; timeout metadata is explicitly not sent to the model. rc.6 adjusts the visible `web_search` definition's timeout to 240 seconds by default and restores the original value on cleanup. This avoids the observed 60-second false timeout while leaving the model-visible tool schema byte-stable.
+
+# 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 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.
+
+## Why not subclass `BasicCompactionEngine`
+
+`BasicCompactionEngine.summarize()` is the intended subclass customization hook, but a subclass is a new `ctx.compaction` service provider. The shipped DSH profile already mounts `dsh-compaction-basic`; mounting a second engine would duplicate service ownership/listeners unless the profile explicitly replaces the existing row.
+
+The stock summarizer already routes through `ctx.llm.stream({ purpose: 'compaction' })`. For an out-of-tree optional plugin that must install without rewriting the base profile, narrowly intercepting that purpose is the less invasive integration.
+
+If DSH later adds a public **summarizer provider registry** (distinct from the compaction engine service), LCX should migrate to it.
+
+## Why not inline opaque JSON in checkpoint text
+
+Inlining `encrypted_content` makes the session self-contained, but also exposes a large opaque string to DSH's visible surface/token accounting. Using a non-text block in `compaction/summary.rawOutput` keeps the session self-contained without turning provider state into prompt text.
+
+## Remaining deliberate low-level seams
+
+### Native Responses replay
+
+Generic DSH/Pi messages do not expose an input type for OpenAI `compaction` items. Same-route resume therefore builds the Responses request directly. This is a bounded compatibility adapter, not a second general LLM stack.
+
+### Runtime Web SearchProvider selection
+
+DSH 0.1.1-rc.2 pins `deepseek-official` and has no public live setter. LCX uses an isolated compatibility write to the 0.1.1-rc.2 runtime field so the settings toggle works without restart. A future DSH public setter/configuration hook should replace this shim.
+
+## Cache expectations
+
+- Stable ordinary tool schema improves prefix stability versus exposing two ordinary search tools.
+- Enabling/disabling Advanced or Alpha changes tools and may reset provider prefix cache.
+- Compaction necessarily changes visible history and therefore starts a new post-checkpoint prefix.
+- `prompt_cache_key` remains stable per exact route/session across Native compaction and native replay.
+- Remote-first avoids an otherwise redundant large-prefix local summary call.
+
+## Native V2 retained-history invariant
+
+Current Codex V2 retains selected client messages and appends the opaque compaction item. Real DSH testing showed an additional product-level fidelity problem: a low-salience fact that existed only in an assistant answer can be omitted by the opaque state. LCX rc.5 therefore keeps the Native ordering but adds a bounded assistant-visible protection layer:
+
+```text
+selected user/developer/system message items
++ selected assistant visible output_text items
+→ opaque compaction item
+→ later DSH-retained / post-compaction messages
+```
+
+The fidelity prefix is capped at an estimated 64k tokens total. Up to 24k is reserved for assistant-visible answers; each retained assistant answer is capped at about 3k tokens. Assistant copies deliberately exclude reasoning, response IDs, tool calls, tool outputs, and provider-private state. The opaque item remains the only durable representation of those process details.
+
+The DSH surface still stores only the short checkpoint marker. The retained wire items and opaque compaction state remain log-only in `compaction/summary.rawOutput`, so they do not inflate DSH's visible token-meter surface. They do, intentionally, increase the post-compaction provider request relative to an opaque-only checkpoint; the total explicit retention ceiling prevents this protection from defeating compaction.
+
+Compatibility:
+
+- `0.4.0-rc.3`: v4 checkpoint could contain only the opaque item.
+- `0.4.0-rc.4`: v4 checkpoint retained client messages but not assistant-visible answers.
+- `0.4.0-rc.5`: writes `lcx-native-compaction-v5`; when replaying a v4 checkpoint it reconstructs the shadowed DSH transcript and derives the v5 fidelity prefix before reusing the original opaque state.
+
+
+
+## rc.7 active-Agent Hosted Search routing
+
+DSH intentionally keeps `SearchProvider.search()` small: the provider receives the normalized search request and cancellation signal, not the calling Agent. Ordinary Hosted Search still needs the exact active GPT Responses route, especially when a user switches between Sol/Luna or multiple proxy routes.
+
+rc.7 therefore captures route identity at the model-facing `tools/execute` boundary for `web_search` and propagates it through Node `AsyncLocalStorage` only for the lifetime of that tool execution. `LcxResponsesSearchProvider.search()` resolves the route from that async context and falls back to the plugin-configured route only when no compatible active Agent route exists. No fields are added to the DSH `web_search` schema.
+
+Hosted Search uses a dedicated stable cache namespace (`dsh-lcx-search:<route fingerprint>`) rather than the Native replay namespace (`dsh-lcx:<route fingerprint>`). The two requests have different prefixes and should not be intentionally co-routed under one prompt-cache key.

package/CHANGELOG.md

@@ -1,65 +1,167 @@
 # Changelog
 
-本项目遵循语义化版本。未通过真实验收的能力只记录在Unreleased，不作为已发布功能。
+## 0.4.0-rc.13 - 2026-08-23
 
-## Unreleased
+### Fixed
 
-## 0.3.3 - 2026-08-21
+- 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
 
-- Native V2 checkpoint 现在由客户端按 64K token 预算保留最近真实 user messages，再追加 exactly-one compaction item；不再错误假设上游 `response.output` 会返回 retained messages。旧的 compaction-only v3 checkpoint 会从 portable history 安全补全，运行时上下文注入不会进入 replacement history。
+- 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
 
-### Documentation
+### Fixed
 
-- 记录 installed `0.3.2` 的 compact + 三次 replay 缓存实测，并说明 Sub2API Codex OAuth 路径会删除上游不支持的 `prompt_cache_retention`；短缓存过期后的单次冷请求不等于插件改变了稳定前缀。
-- 增加连续 replay 的前缀稳定性回归断言，区分缓存生命周期与 replacement-history 保真问题。
+- 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.3.2 - 2026-08-21
+## 0.4.0-rc.10 - 2026-08-22
 
 ### Fixed
 
-- Native V2 compact 与同路由 replay 现在和 DSH/Pi 普通 Responses 请求复用相同的 session `prompt_cache_key`、缓存 retention 与会话 header，避免压缩边界额外切换 NewAPI/Sub2API 的缓存和账号粘性域；`cacheRetention: none` 时同时省略这些缓存信号。
-- 移除未被插件直接导入或注入的 `@deepseek-ai/dsh-compaction-basic` peer 声明，避免 DSH/pnpm 安装时出现误导性的宿主依赖警告；Basic fallback 继续通过 DSH `llm/stream` 的 `next()` 链调用宿主实现。
+- 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.3.1 - 2026-08-21
+## 0.4.0-rc.9 - 2026-08-22
 
 ### Fixed
 
-- 删除未被 DSH 官方识别、且错误写死旧域名与 `LCX_API_KEY` 的 `dshhub` 权限块；README 改为声明网络目标和凭据由当前 `openai-responses` provider 动态决定。
-- 添加 npm 与 DSH 社区检索使用的标准关键词，其中包括 `dsh-plugin` GitHub topic 对应关键词。
-- 新增独立英文用户文档 `README_EN.md`，并与中文 README 互相链接。
+- 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
 
-## 0.3.0 - 2026-08-21
+- Rebase the plugin on DSH `0.1.1-rc.2`; older DSH releases are no longer a supported runtime target.
+- Native V2 compaction image replay now uses DSH `attachments.readImageRequest()` with the active `llm-pi-ai` route's request-image pixel/byte policy instead of reading normalized master bytes directly.
+- Native image requests use DSH's deterministic `offloadRequestImagesWithPolicy()` projection before serialization, matching the current request-size behavior for long image-heavy sessions.
+- Keep rc.7 active-Agent Hosted Search routing, isolated search cache namespace, 240s search timeout, rc.5 conversation-fidelity checkpointing, and rc.6 90% Native-first / 95% emergency pressure policy unchanged.
+- CI installs against current declared DSH packages instead of enforcing the stale rc.8 lockfile.
 
-### Changed
+## 0.4.0-rc.7 - 2026-08-22
 
-- 收紧 npm/DSH 安装包，只保留运行时代码、Alpha 运维探针、许可证和用户文档；开发测试与 schema 校验脚本继续保留在源码仓库。
-- README 和包元数据明确 `LCX` 只是插件名称；支持 Sub2API 反代或 NewAPI 中转的 GPT 模型，不隶属于 OpenAI；Alpha 能力继续按部署 fingerprint 与可信 provenance 分类，不作全局 native 承诺。
-- 明确 Alpha 经过 NewAPI 时渠道类型必须为 `Sub2API`，不能使用普通 `OpenAI` 渠道。
-- README 改为面向用户的中文文档，提供经 DSH/pnpm 帮助核对的 GitHub URL、Release 包、更新和卸载命令；本地 `link:` 安装明确归入源码开发流程。
+### Fixed
 
-### Added
+- Ordinary DSH `web_search` now follows the active Agent `provider/model` instead of always using the plugin fallback GPT model. A Luna conversation now searches with Luna; a Sol conversation searches with Sol.
+- Added an AsyncLocalStorage route bridge at the DSH `tools/execute` boundary so the provider-only `ctx.web.search()` seam can receive Agent route context without changing the model-visible `web_search` schema.
+- Hosted Search now uses a separate stable `dsh-lcx-search:<route hash>` `prompt_cache_key`, avoiding intentional cache-key sharing with Native conversation replay.
+- The settings UI now labels the configured Responses endpoint/model as **fallback** values, matching their actual rc.7 role.
 
-- Hosted Search 完整结构化参数与 citation/source/image 输出。
-- 独立 `websearch_alpha`，支持 search、image、open/find/click、PDF screenshot、finance、weather、sports 和 time；capability/ref sidecar 按 route 与 session 隔离。
-- Native V2 checkpoint v3、同路由 replay、Sol/Luna portable migration、fork/tree/restart generation lease 与 durable-image migration。
+### Kept from rc.6
 
-### Fixed
+- 240-second default DSH `web_search` deadline.
+- Native-first automatic pressure policy: 90% Native V2, 95% emergency DSH prune.
+- rc.5 conversation-fidelity checkpoints and restart-safe DSH session-log persistence.
+
+### Docs / release
+
+- Reworked the README around the current architecture and real cache observations.
+- Added a blue/white DSH-LCX-CODEX hero banner for GitHub/npm.
+- GitHub trusted publishing is wired through `.github/workflows/publish.yml`: pre-release tags publish to npm dist-tag `next`; stable tags publish to `latest`.
+
+## 0.4.0-rc.6
+
+- Added Native-first automatic pressure coordination for GPT Responses sessions: below the configured Native threshold the plugin suppresses DSH's stock 80% pressure compaction/prune path; at the default 90% threshold it lets compaction proceed while temporarily suppressing tool-result pruning so Native V2 runs first.
+- Added a separate emergency prune threshold (default 95%). At or above this zone, DSH's replay-safe tool-result pruner is allowed to run before compaction as overflow protection.
+- Added adjustable `web_search` tool deadline, default 240 seconds (30–600s). This mutates only DSH's non-model-visible `ToolDefinition.timeoutMs`, so the model tool schema and prompt-cache prefix do not change.
+- Added Settings UI controls for automatic compaction, Native threshold, emergency prune threshold, and web search timeout.
+- Kept the rc.5 checkpoint/fidelity format unchanged (`lcx-native-compaction-v5`); rc.6 is a pressure/timeout coordination release, not another checkpoint migration.
+
+## 0.4.0-rc.5
+
+- Adds a bounded conversation-fidelity layer after real DSH testing showed assistant-only facts could be lost by opaque Native V2 compaction.
+- New `lcx-native-compaction-v5` checkpoints retain selected user/developer/system messages plus user-visible assistant final answers before the opaque compaction item.
+- Keeps explicit retained history within an estimated 64k-token ceiling; defaults reserve at most 24k for assistant answers and cap one retained answer at about 3k tokens.
+- Does not copy reasoning, tool calls/results, raw search payloads, or telemetry into the fidelity prefix.
+- Repairs rc.3/rc.4 v4 checkpoints from append-only `shadowedSeqs`, including assistant-visible answers when the original DSH events still exist.
+- Stores only the single opaque compaction output item, ignoring unrelated terminal output items from nonstandard proxies.
+- Route compatibility now accepts both native checkpoint versions 4 and 5.
+- Adds regression coverage for the exact assistant-only anchor failure (`Cobalt-Sparrow-604` / `81736`) and the 64k retention ceiling.
+
+## 0.4.0-rc.4
+
+- Fixes a Native V2 replay fidelity bug found by real DSH session-log testing.
+- Native checkpoints now persist the retained client-authored Responses messages before the opaque `compaction` item, matching current OpenAI Codex remote-compaction V2 replacement-history semantics.
+- Existing rc.3 opaque-only v4 checkpoints are repaired on replay by reconstructing the missing shadowed user history from the DSH append-only session log.
+- Adds replay/retention regression coverage and an explicit Native success diagnostic.
+- Keeps the rc.3 search-provider, remote-first fallback, and session-log-native checkpoint architecture unchanged.
+
+## 0.4.0-rc.3
+
+- Fix Cordis external-package loading: all `ctx.web`/`ctx.llm` service access now occurs inside an explicit `ctx.inject(['llm', 'web'], ...)` scope.
+- This fixes `cannot get property "web" without inject` when DSH loads the plugin from a profile-installed `.tgz`.
+- No protocol or checkpoint-format changes from rc.2.
+
+## 0.4.0-rc.2 - 2026-08-21
+
+- Packaging-only fix over rc.1: remove unnecessary `@deepseek-ai/dsh-compaction-basic` and `@deepseek-ai/dsh-web` peer declarations.
+- The plugin consumes DSH runtime services through injected `ctx.*` seams and does not import or mount either package directly.
+- Avoids misleading pnpm "missing peer" warnings and, importantly, avoids encouraging users to install a second compaction backend.
+
+## 0.4.0-rc.1 - 2026-08-21
+
+### Architecture
+
+- Keep DSH `compaction-basic` as the sole compaction service owner; use only its documented/interceptable `purpose=compaction` `llm/stream` summarizer seam.
+- Replace parallel local+remote compaction with remote-first fallback.
+- Persist new Native V2 opaque state in DSH `compaction/summary.rawOutput` using `lcx-native-compaction-v4`; the model-visible replacement stays short.
+- Remove new-checkpoint writes to the v3 JSON sidecar. The v3 sidecar is now read-only compatibility for old sessions.
+- Reconstruct portable history for route migration from DSH append-only `shadowedSeqs` instead of duplicating every checkpoint's portable history.
+- Preserve same-route fork replay through DSH session ancestry.
+- Centralize the remaining direct Responses-native transport in `compact-v2.js` and `responses-replay.js`.
+
+### Search
+
+- Make `ctx.web` / DSH `web_search` the ordinary Hosted Search entry point.
+- Remove the ambiguous ordinary `websearch_gpt` tool.
+- Add opt-in `websearch_gpt_advanced` for Hosted-only controls that DSH `WebSearchRequest` cannot express.
+- Keep `websearch_alpha` independent and capability-gated.
+- Isolate the DSH rc.8 runtime SearchProvider-selection compatibility shim.
+
+### Reliability
+
+- Rehydrate DSH image attachment references when replaying legacy v3 checkpoints.
+- Resolve startup settings into runtime route config immediately instead of waiting for the first settings change.
+- Do not assume `events[seq]` is always the event whose `event.seq === seq`; use a safe fallback lookup.
+- Add protocol, session persistence, migration and architecture regression tests.
+
+### Compatibility
+
+- Node.js >= 20.
+- Target DSH `0.1.1-rc.2` only.
+- Existing 0.3.x v3 marker sessions remain best-effort readable through the old sidecar.
+
+## 0.3.1
 
-- Hosted Search 与 Alpha Search 现在和 Native V2 Compact 一样，复用 DSH 已添加的 `openai-responses` provider 路由、凭据引用、headers 与 retry policy；不再要求用户为插件重复配置 `LCX_API_KEY`。
-- README 将插件运行时凭据与运行在 DSH 外的 Alpha 探针/E2E 测试凭据明确分开。
-- README 改为简短的用户手册，以 npm 安装为主；Alpha 提示前置，并按 NewAPI 当前源码区分 4 种中转渠道类型与 Sub2API 直连，共 5 种部署路径。
-- Native replay and portable migration no longer depend on the nonexistent `GenerateOptions.branchId`; fork safety uses public session ancestry and derived marker history while preserving existing v3 fingerprint compatibility.
-- README 的本地 link 安装示例不再包含开发机绝对路径。
-- Alpha 从 rc.8 公共 `session.requestContext()` 读取 active route，避免模型切换后的 capability 误判。
-- Alpha 对 HTTP 200 内的函数调用语义错误 fail closed，并修正 sports action 的 wire 字段。
-- Responses SSE 去重、usage、工具配对、并发 sidecar、Windows ACL、图片 offload/hydrate 和 remote/local summary 边界。
-
-## 0.2.0
-
-- Hosted Responses query-only Web Search。
-- Native Remote Compaction V2，拒绝legacy transport。
-- checkpoint v3、同route replay和第一批portable model migration。
-- 图片同route attachment hydrate，portable image migration保持fail closed。
-- 协议、大小、超时、重试、redirect和日志脱敏基础测试。
+- Previous Hosted/Alpha Search and Native V2 checkpoint-v3 implementation.