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

package/README_EN.md

@@ -1,164 +1,194 @@
-# dsh-lcx-codex
+<div align="center">
 
-[Chinese](README.md) | **English**
+<img src="https://raw.githubusercontent.com/kk3ya03-star/dsh-lcx-codex/main/assets/dsh-lcx-codex-banner.jpg" alt="DSH-LCX-CODEX" width="100%" />
 
-[![npm version](https://img.shields.io/npm/v/dsh-lcx-codex.svg)](https://www.npmjs.com/package/dsh-lcx-codex)
-[![license](https://img.shields.io/npm/l/dsh-lcx-codex.svg)](LICENSE)
+# DSH-LCX-CODEX
 
-A community-maintained DSH plugin that lets any DSH primary model call Hosted or Alpha Search through a separately configured GPT Responses route, and adds Native V2 remote compaction for compatible GPT primary models.
+**OpenAI Responses / Codex-native capabilities for DeepSeek Harness.**
 
-> [!IMPORTANT]
-> Alpha Search currently has five supported deployment paths: a direct Sub2API connection, or one of four NewAPI channel types: `Sub2API`, `New API`, `ChatGPT Subscription (Codex)`, and `Advanced Custom`. A regular `OpenAI` channel does not support `/v1/alpha/search` and is rejected by NewAPI.
+[![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)
+![DSH](https://img.shields.io/badge/DSH-0.1.1--rc.2-4ea8ff)
+![License](https://img.shields.io/badge/license-MIT-1677ff)
 
-This list comes from NewAPI's current [`AlphaSearchHelper`](https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relay/alpha_search_handler.go). Other NewAPI versions may differ, so the capability probe remains authoritative for a specific deployment.
+[简体中文](README.md) · **English**
 
-`LCX` is only the plugin name. It is not a service provider or protocol. The plugin supports GPT models served through:
+</div>
 
-- A direct Sub2API reverse proxy.
-- A NewAPI relay, meaning a third-party relay whose upstream channel connects to Sub2API.
+---
 
-```mermaid
-flowchart LR
-    accTitle: dsh-lcx-codex architecture
-    accDescr: Hosted and Alpha can be called by any DSH primary model through a configured GPT openai-responses route. Enabling Hosted selects the plugin DSH search provider; disabling it restores the previous provider. Native V2 Compact applies only to the active compatible GPT route.
+`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.
 
-    dsh_session([Any DSH primary model]) --> search_route[Use active compatible GPT route<br/>or configured GPT fallback route]
-    gpt_session([Compatible GPT primary model]) --> compact_route[Reuse active provider, model, baseURL, and credential]
+> `LCX` is only the project name. This project is not affiliated with OpenAI, DeepSeek, Sub2API or NewAPI.
 
-    subgraph plugin_capabilities ["dsh-lcx-codex"]
-        hosted_search[Hosted Search<br/>POST /responses + web_search]
-        alpha_gate{Alpha capability matches?}
-        alpha_search[Alpha Search<br/>POST /alpha/search]
-        alpha_disabled([Alpha is not registered])
-        native_compact[Native V2 Compact<br/>stream + compaction_trigger]
-    end
+- **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.
 
-    search_route --> hosted_search
-    search_route --> alpha_gate
-    compact_route --> native_compact
-    alpha_gate -->|Yes| alpha_search
-    alpha_gate -->|No| alpha_disabled
+## Features
+
+| 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 |
+
+## rc.8: DSH 0.1.1-rc.2 native alignment
 
-    hosted_search --> transport[Controlled authentication, timeout, retry, and response size]
-    alpha_search --> transport
-    native_compact --> transport
+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.
 
-    transport --> deployment{Deployment path}
-    deployment -->|Direct| sub2api[Sub2API]
-    deployment -->|Relay| newapi[Compatible NewAPI channel]
-    sub2api --> upstream([OpenAI Responses/Codex-compatible upstream])
-    newapi --> upstream
+Search routing still crosses DSH's `tools/execute` → SearchProvider boundary without changing the model-visible `web_search` schema:
 
-    upstream -.->|Compaction output| checkpoint[(Checkpoint v3)]
-    checkpoint -->|Same route| opaque_replay[Opaque native replay]
-    checkpoint -->|Route or model changed| portable_migration[Portable migration]
-    opaque_replay --> transport
-    portable_migration --> transport
+```text
+Agent: lcx / gpt-5.6-luna
+        └─ DSH web_search
+             └─ Hosted Search: lcx / gpt-5.6-luna
 ```
 
-This project is not affiliated with OpenAI and is not an official OpenAI plugin or OAuth client.
+The settings-page model is now a **fallback** used only when no active Agent route is available.
 
-## Features
+Hosted Search also receives its own stable cache namespace:
 
-| Feature | Tool or protocol | Behavior |
-|---|---|---|
-| Hosted Web Search | `websearch_gpt` | Callable by any primary model; uses a GPT Responses route for `/responses` with `web_search` and returns text, direct sources, and citations |
-| Alpha Search | `websearch_alpha` | Callable by any primary model; uses a verified GPT route for `/alpha/search` search, image, open/find/click, PDF screenshot, finance, weather, sports, and time actions |
-| Native V2 Compact | `/responses` with `compaction_trigger` | Stores checkpoint v3 and supports same-route replay, model migration, fork/tree sessions, restart recovery, and image attachments |
+```text
+conversation replay: dsh-lcx:<route hash>
+hosted search:       dsh-lcx-search:<route hash>
+```
 
-Alpha is enabled only when a capability record matches the search backend endpoint, provider, model, and schema. Hosted and Alpha are separate protocols and never silently fall back to each other. Enabling Hosted temporarily selects the plugin search provider, so the previous provider no longer handles search; disabling Hosted or removing the plugin restores the provider selected before activation.
+A search row with a low cache hit in NewAPI therefore does not imply conversation truncation.
 
-## Installation
+## Native V2 Compaction
 
-Install from npm:
+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:
 
-```powershell
-dsh plugin --profile web add dsh-lcx-codex
+```text
+DSH compaction transaction
+        └─ purpose=compaction
+              └─ /responses + compaction_trigger
 ```
 
-You can also install a specific `.tgz` file from a GitHub Release:
+Native success means zero basic-summary request. Basic summary runs only if Native fails and fallback is enabled.
 
-```powershell
-dsh plugin --profile web add .\dsh-lcx-codex-0.3.4.tgz
+## Conversation fidelity layer
+
+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:
+
+```text
+bounded client-visible history
++ bounded assistant-visible final answers
++ opaque Native V2 compaction item
 ```
 
-Start DSH after installation:
+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.
 
-```powershell
-dsh web
+The goal is not byte-for-byte replay. It is **drop process noise, retain conversation facts**.
+
+## Automatic compaction
+
+```text
+0% -------------------- 90% ----- 95% ----- 100%
+        normal             Native   emergency   hard cap
+                           V2       DSH prune
 ```
 
-Open `Settings -> Plugins -> LCX / Codex capabilities` and enable Hosted, Alpha, or Native Compact as needed. The plugin is disabled by default.
+Default behavior:
 
-## Requirements
+- 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.
+
+## Cache behavior
+
+A provider cache miss is not the same thing as DSH deleting history.
+
+Observed real-world pattern:
+
+```text
+turn N:   ~155k uncached, cacheRead 0
+turn N+1: ~1k new input, ~155k cacheRead
+```
+
+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.
+
+## Search modes
+
+### Ordinary `web_search`
+
+Recommended default. It follows the current Agent GPT Responses route.
 
-- Node.js 20 or later
-- DSH `0.1.0-rc.8` or a compatible release
-- A primary model already added to DSH and working in a normal conversation; the caller of Hosted or Alpha does not need to be GPT
-- A working GPT `openai-responses` provider for the Hosted/Alpha search backend; Native Compact requires the active primary model itself to use such a route
+### `websearch_gpt_advanced`
 
-Hosted and Alpha reuse the active route when the primary model already uses a compatible GPT Responses route; otherwise they use the GPT Responses route selected in the plugin settings. Native Compact only reuses the active GPT primary model's provider, model, Responses URL, credential reference, headers, and retry policy. Credentials are resolved by the DSH credentials service, so normal operation does not require a second `LCX_API_KEY` configuration.
+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.
 
-The provider, endpoint, and model fields in the plugin UI define the search fallback route and preserve compatibility with the older direct-route configuration. Hosted and Alpha use this GPT route when the active primary model is not on a compatible GPT route. An existing DSH provider configuration takes precedence.
+### `websearch_alpha`
 
-## Alpha Probe
+Stateful Codex/Alpha-style `search/open/find/click/screenshot`; registered only after a matching capability probe.
 
-Alpha capability is classified as `native`, `command-capable`, `emulated-search-only`, `unsupported`, or `unknown`. An HTTP 200 response alone does not prove that an action is native.
+## Installation
 
-The probe is a standalone Node.js script outside the DSH runtime, so it cannot use the DSH credentials service. It requires a local key file; normal plugin operation does not.
+Stable channel:
 
 ```powershell
-$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $env:USERPROFILE '.dsh' }
-$env:LCX_API_KEY_FILE = 'C:\path\to\local-key.txt'
-$env:LCX_MODEL = 'the-exact-model-name'
-node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-alpha.mjs')
+dsh plugin --profile web add dsh-lcx-codex
 ```
 
-To also probe image, finance, weather, sports, and time actions:
+Pre-release channel (current rc.8):
 
 ```powershell
-$env:LCX_ALPHA_PROBE_STRUCTURED = '1'
-node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-alpha.mjs')
+dsh plugin --profile web add dsh-lcx-codex@next
 ```
 
-The probe does not print the key or full response bodies. Restart DSH, or disable and re-enable Alpha, after the probe completes.
-
-## Data and Limits
+Local RC:
 
-- The search network target prefers the active compatible DSH `openai-responses` provider and otherwise uses the GPT provider selected in the plugin settings. It is not fixed to LCX or any other domain, and the plugin only calls `/responses` and `/alpha/search` under that address.
-- The credential name comes from the selected GPT provider's `apiKeyEnv` and is resolved by the DSH credentials service. The plugin does not store API keys.
-- Enabling Hosted temporarily changes `ctx.web.searchProviderId` to the plugin search provider; disabling Hosted or removing the plugin restores the provider selected before activation.
-- Checkpoints: `$DSH_HOME/storages/lcx-codex/checkpoints-v3.json`
-- Alpha capabilities: `$DSH_HOME/storages/lcx-codex/web-alpha-capabilities.json`
-- Alpha references: `$DSH_HOME/storages/lcx-codex/web-alpha-refs.json`
-- Only Native remote-compaction V2 is supported; `/responses/compact` is never called.
-- Same-route replay reuses the DSH session `prompt_cache_key` and preserves the existing request prefix. A single cold request can still occur after the short-lived upstream cache expires, so the cumulative session hit rate is not evidence that the plugin changed the prefix.
-- Sub2API strips the unsupported `prompt_cache_retention` field on its Codex OAuth path, so requesting `24h` does not extend cache lifetime on that route. Use the `cached_tokens` reported by consecutive real requests as the authoritative signal.
-- Checkpoints never store raw image bytes or data URLs.
-- Opaque checkpoints are not replayed across an incompatible provider, model, base URL, session, or lineage.
-- Image generation is not included.
+```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
+```
 
-Never commit API keys, OAuth tokens, Authorization headers, account IDs, session cookies, or runtime sidecars to GitHub.
+Do not delete existing sessions or `$DSH_HOME/storages/lcx-codex/` just to upgrade. The legacy v3 sidecar remains read-only compatibility state.
 
-## Update and Removal
+## Recommended settings
 
-```powershell
-dsh plugin --profile web update dsh-lcx-codex
-dsh plugin --profile web remove dsh-lcx-codex
+```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
 ```
 
-Removal does not delete `$DSH_HOME/storages/lcx-codex/`. Do not delete a checkpoint sidecar by itself while a session still references its marker.
+## Requirements
+
+- 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
+
+Typical paths include direct Sub2API and NewAPI-relayed Responses routes.
+
+## Release channels
+
+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.
 
 ## Development
 
-```powershell
-npm install
+```bash
 npm test
 npm run test:schema
+npm pack --ignore-scripts
 ```
 
-Real E2E tests and the Alpha probe must read test credentials only from ignored local files or environment variables.
+See [ARCHITECTURE.md](ARCHITECTURE.md) and [CHANGELOG.md](CHANGELOG.md) for implementation details.
 
 ## License
 
-[MIT](LICENSE)
+MIT

package/cordis.patch.yml

@@ -1,5 +1,7 @@
-# Adds optional search and compaction for Sub2API-proxied or NewAPI-relayed GPT
-# models without touching existing profiles or presets.
+# Optional Responses/Codex capabilities for GPT routes already configured in llm-pi-ai.
+# This does not replace DSH's compaction service. Native V2 is installed as the
+# documented purpose=compaction llm/stream override, leaving compaction policy,
+# range selection, pruning, transactions and /compact owned by DSH.
 - insert:
     - id: lcx-codex
       name: dsh-lcx-codex
@@ -8,11 +10,15 @@
         baseURL: https://api.lcxbot.com/v1
         apiKeyEnv: LCX_API_KEY
         model: gpt-5.6-sol
-        compactTransport: native-v2
-        checkpointPath: !!js dshHomePath('storages/lcx-codex/checkpoints-v3.json')
+        legacyCheckpointPath: !!js dshHomePath('storages/lcx-codex/checkpoints-v3.json')
         alphaCapabilityPath: !!js dshHomePath('storages/lcx-codex/web-alpha-capabilities.json')
         alphaRefPath: !!js dshHomePath('storages/lcx-codex/web-alpha-refs.json')
         webSearchProvider: lcx-responses
         webMaxResults: 8
         timeoutMs: 300000
         maxAttempts: 3
+        requestImagePixelBudget: 4194304
+        requestImageMaxBytes: 1048576
+        webSearchTimeoutMs: 240000
+        autoCompactionThresholdPercent: 90
+        emergencyPruneThresholdPercent: 95