dsh-lcx-codex 0.4.2 → 0.4.3-pre.13

package/README.md

@@ -1,277 +1,128 @@
-# dsh-lcx-codex
+<div align="center">
 
-[![npm](https://img.shields.io/npm/v/dsh-lcx-codex?label=stable&color=1677ff)](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)
-![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-2f855a)
-![Plugin Pi](https://img.shields.io/badge/plugin%20Pi-0.84.3-111827)
-![License](https://img.shields.io/badge/license-MIT-6b7280)
+<img src="https://raw.githubusercontent.com/kk3ya03-star/dsh-lcx-codex/main/assets/dsh-lcx-codex-banner.svg" alt="LCX Codex" width="100%" />
 
-**简体中文** · [English](README_EN.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) · [Releases](https://github.com/kk3ya03-star/dsh-lcx-codex/releases)
+# LCX Codex
 
-> **让 DSH 的 GPT Responses 会话从第一轮普通请求开始，到工具调用、Native V2 Compact / Replay、重启恢复和 GPT 模型切换，始终保持同一个最终 Responses wire owner。**
+**让 DeepSeek Harness 里的 GPT 与 Grok 更适合长任务、联网搜索和连续工作。**
 
-`dsh-lcx-codex` 不替换 DSH。DSH 仍负责 Agent、Session、模型选择、工具执行、附件和 compaction policy；当 **LCX ON** 时，LCX 接管当前 GPT Responses 会话的最终 request / SSE wire。
+[![npm prerelease](https://img.shields.io/npm/v/dsh-lcx-codex/prelatest?label=prelatest)](https://www.npmjs.com/package/dsh-lcx-codex)
+[![DSH](https://img.shields.io/badge/DSH-0.1.5--rc.1-16803c)](#安装)
+[![License](https://img.shields.io/badge/license-MIT-555)](LICENSE)
 
-## 当前稳定版
+**简体中文** · [English](README_EN.md) · [更新日志](CHANGELOG.md) · [问题反馈](https://github.com/kk3ya03-star/dsh-lcx-codex/issues)
 
-**`0.4.2`** 是当前稳定版，也是已完成真实 DSH + Sub2API 验收的 `0.4.2-pre.1` 的 **zero-functional-change stable promotion**。
+</div>
 
-```powershell
-dsh plugin --profile web add dsh-lcx-codex
-dsh web
-```
-
-- npm dist-tag：`latest`
-- DSH：`0.1.1-rc.2`
-- Plugin Pi：`0.84.3`
-- Node.js：`^22.19.0 || >=24.0.0`
-
-`0.4.2-pre.1` 保留为历史 prerelease；新用户直接安装 `latest` 即可。
-
-## 产品约定
-
-```text
-LCX OFF
-= 完全使用 DSH 原生 LLM 流程
-
-LCX ON
-= 当前 GPT Responses 会话从 ordinary turn 1 开始
-  由 LCX 持有最终 Responses request / SSE wire
-```
-
-切换 Claude、Gemini、DeepSeek 等非 GPT 模型前先关闭 LCX；模型切换本身不需要重启 DSH。
-
-## 为什么需要 LCX
-
-DSH 原本已经拥有 Agent、Session、Tools 和 compaction lifecycle。LCX 解决的是 GPT Responses provider-native 路径的最后一层一致性：ordinary、tools、Native Compact、Replay、restart/resume 和 GPT route migration 不再在同一个会话中切换最终 wire owner。
-
-```text
-                        DSH
-              Agent / Session / Tools
-                         │
-                 llm / stream seam
-                         │
-              ┌──────────┴──────────┐
-              │                     │
-           LCX OFF               LCX ON
-              │                     │
-       native DSH adapter      LCX Responses Core
-                                    │
-                         ordinary turn 1
-                                    ↓
-                                 tools
-                                    ↓
-                         Native V2 Compact
-                                    ↓
-                                Replay
-                                    ↓
-                           Restart / Resume
-                                    ↓
-                         GPT Model Migration
-```
+LCX Codex 是 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness)（DSH）的社区插件。
 
-Compact 因此只改变 history representation，不再同时改变 request owner。
+它不会替代 DSH，也不需要你重新配置模型、接口或 API Key。模型、凭据、会话和工具仍由 DSH 管理；LCX 只在需要时为 GPT 和 Grok 增加额外能力。
 
-## 核心能力
+## 你可以用它做什么
 
-### 1. Full GPT Responses lifecycle ownership
+| 能力 | 适合场景 |
+| --- | --- |
+| GPT 联网搜索 | 让 GPT 直接通过 DSH 的 `web_search` 查询网页。 |
+| GPT 高级搜索 | 搜图片、限定网站、加入位置等额外搜索条件。 |
+| Grok 原生 Web / X Search | 直接使用 xAI Responses 的 Web Search 和 X Search。 |
+| 长对话压缩 | GPT 长任务接近上下文上限时自动尝试远程压缩，并继续当前会话。 |
+| 搜索媒体预览 | 在回答下方直接预览可用的图片和视频链接。 |
+| Alpha 网页操作 | 实验性连续网页阅读能力，适合需要进一步打开、查找页面内容的任务。 |
 
-LCX ON 后，ordinary、tool continuation、Native Compact、Native Replay、restart/resume 和 portable GPT migration 使用同一套 LCX Responses request builder / transport owner。
+其他模型继续使用 DSH 原生路径，不会因为安装 LCX 而被接管。
 
-DSH 仍是 canonical session/history owner；LCX 不创建第二套会话数据库，也不替换 DSH Tool Executor。
+## 安装
 
-### 2. GPT-5.6 Prompt Cache
-
-`0.4.2` 使用 GPT-5.6 当前 cache-options 路径，并保持同一会话的稳定 cache identity：
-
-- 默认使用 implicit caching；
-- 当前支持 route 发送 `prompt_cache_options.ttl = 30m`；
-- 普通连续 turn / tool-heavy workload 可以复用已 warm 前缀；
-- Native Compact 会按设计建立新的 history/cache epoch，旧未压缩前缀不会被承诺继续复用；
-- 真实长会话中，稳定 topology 下 warm request 多次观察到接近完整前缀复用。
-
-缓存命中由 provider、模型、请求前缀、工具 schema 和会话状态共同决定，不是固定性能承诺。
-
-一个已确认的边界：运行中激活 skill 若改变顶层 tool schema，会发生一次 cache reset；新 tool topology 稳定后下一请求即可重新 warm。当前支持 route 会拒绝 content-level `prompt_cache_breakpoint`，而 DSH `0.1.1-rc.2` 也没有可靠的 dynamic-tool provenance，因此 `0.4.2` 保留一次安全 reset，而不靠猜测重写工具历史。
-
-### 3. Native V2 Compact + Replay
-
-DSH 仍决定 **何时压缩、压缩范围、事务与 recovery**；LCX 只负责 provider-native Responses V2 wire。
-
-默认 pressure coordination：
-
-```text
-0% ─────────────────── 90% ───── 95% ───── 100%
-       normal            Native      emergency   hard cap
-                         V2          DSH prune
-```
+当前预发布版：**`dsh-lcx-codex@0.4.3-pre.13`**
 
-- `90%`：优先 Native V2；
-- `95%`：允许 DSH emergency tool-result prune；
-- provider-confirmed overflow：继续交给 DSH recovery；
-- manual `/compact`：仍使用 DSH 原生 compaction transaction。
+兼容环境：
 
-Native checkpoint v5 会持久化 provider-native compaction state 与必要的可移植保留历史；同 session / compatible route 可 Native replay，不兼容 route 不会错误复用 opaque state。
-
-### 4. Restart / Resume + GPT 热切换
-
-同一个 DSH session 可以跨越：
-
-```text
-Terra
-  → Compact
-  → Replay
-  → Restart DSH
-  → Resume same session
-  → Switch to Sol
-  → Continue
-```
-
-compatible route/model 可恢复 Native opaque state；不兼容的 GPT model / route 会丢弃不安全 opaque state并重建 portable history，但仍保持 LCX Responses transport ownership。
-
-### 5. Hosted Search + Stateful Web Actions
-
-普通联网搜索仍使用 DSH 原生 `web_search`。LCX 可以把 SearchProvider 映射到当前 GPT Hosted Search，而不是再给模型暴露第二个普通搜索工具。
-
-| 需求 | 使用入口 |
-|---|---|
-| 普通联网搜索 | DSH `web_search` |
-| Hosted Search 高级参数 | `websearch_gpt_advanced` |
-| 连续网页 / PDF 操作 | `websearch_alpha` |
+- DSH `0.1.5-rc.1` 起的 `0.1.5` 系列（当前完整验证基线：`0.1.5-rc.1`）
+- Node.js `^22.19.0 || >=24.0.0`
 
-Alpha 支持：
+安装：
 
-```text
-search → open → find / click → screenshot
+```sh
+dsh plugin --profile web add dsh-lcx-codex@0.4.3-pre.13
+dsh web
 ```
 
-Alpha 默认关闭；只有当前 endpoint / provider / model / schema 通过 capability probe 后才注册。未知部署 fail-closed。
-
-### 6. Pi 0.84.3 隔离升级
-
-插件独立使用 `@earendil-works/pi-ai 0.84.3`，不 override DSH host：
+后续预发布更新可以使用：
 
-```text
-DSH 0.1.1-rc.2
-└─ host Pi 0.82.1      ← 不改
-
-dsh-lcx-codex 0.4.2
-└─ plugin Pi 0.84.3    ← 插件隔离依赖
+```sh
+dsh plugin --profile web add dsh-lcx-codex@prelatest
 ```
 
-Pi 负责 canonical Responses message/tool serialization、reasoning、IDs、strict/grammar/custom tools、`additional_tools`、`tool_search`、namespace 和 stream semantics；LCX 不维护第二套通用 provider framework。
+不指定版本或 dist-tag 时会安装稳定版。当前稳定版仍为 `0.4.2`，旧版用户可查看[稳定版文档](https://github.com/kk3ya03-star/dsh-lcx-codex/blob/v0.4.2/README.md)。
 
-## 30 秒配置
+本版已在官方 DSH `0.1.5-rc.1` 完整验证。后续同一 `0.1.5` 系列版本可以直接安装并进行兼容评估，不再需要仅因为 RC 版本号变化而发布新的 LCX 版本。
 
-### 前提条件
+## 启用功能
 
-- Node.js `^22.19.0 || >=24.0.0`
-- DSH `0.1.1-rc.2`
-- DSH 中已有可工作的 GPT Responses route
-- 上游 endpoint 实际支持准备启用的 Hosted Search / Native V2 / Alpha 能力
+打开 DSH Web 的插件设置，找到 **Responses / Codex 能力**。
 
-### 推荐初始设置
+### 使用 GPT
 
-| 设置 | 推荐值 | 说明 |
-|---|---:|---|
-| Enable LCX | **On** | 接管当前 GPT Responses 会话 |
-| Use GPT Hosted Search | 按需 | 让 DSH `web_search` 使用 GPT Hosted Search |
-| Advanced Hosted Search | Off | 需要高级 Hosted 参数时再开 |
-| Alpha Search | Off | capability probe 通过后再开 |
-| Native-first auto compaction | On | 使用 Native-first pressure coordination |
-| Native threshold | `90%` | 主动 Native V2 阈值 |
-| Emergency DSH prune | `95%` | 紧急 prune 阈值 |
-| Fallback to Basic Compaction | On | Native 首次失败时允许受控回退 |
-| `web_search` timeout | `240s` | 避免较慢 Hosted Search 被过早中断 |
+通常打开：
 
-### 如何确认生效
+1. **启用 LCX**
+2. **GPT Hosted Search**（需要联网时）
 
-| 能力 | 预期行为 |
-|---|---|
-| LCX ownership | LCX ON 后第一轮 GPT ordinary request 就进入 LCX Responses path |
-| Prompt Cache | 稳定 warm turn 可出现 provider `cached_tokens` |
-| Hosted Search | 普通入口仍是 DSH `web_search` |
-| Advanced Hosted | 开启后出现 `websearch_gpt_advanced` |
-| Alpha | capability probe 通过后才出现 `websearch_alpha` |
-| Native V2 | Compact 产生 provider-native checkpoint，而不是把 Basic Compaction 伪装成 Native |
-| Replay | Compact 后继续同一 DSH session；restart/resume 仍可续接 |
+按需再打开：
 
-## DSH 与 LCX 的责任边界
+- **高级 Hosted 工具**：需要图片搜索、限定域名、位置等高级搜索条件时使用；它依赖 GPT Hosted Search。
+- **Alpha**：实验性网页连续操作。日常联网搜索不需要开启。
 
-| 组件 | 负责什么 |
-|---|---|
-| **DSH** | Agent loop、Session/history、GenerateOptions、模型/credential、工具执行、AttachmentStore、pressure policy、compaction transaction |
-| **DSH compatibility seam** | 把 DSH message / GenerateOptions 投影到 Pi Context，并把结果桥接回 DSH |
-| **Plugin Pi 0.84.3** | canonical Responses serialization / parser semantics |
-| **LCX** | ON/OFF ownership、最终 Responses body + HTTP/SSE wire、ordinary/compact/replay orchestration、Native opaque state、Search capabilities |
+### 使用 Grok
 
-更多 checkpoint、portable replay、cache identity、RefStore、pressure coordination 与 protocol 细节见 [ARCHITECTURE.md](ARCHITECTURE.md)。
+Grok 原生搜索与 GPT 的 LCX 主开关相互独立：
 
-## 兼容性
+- **Grok 原生 Web Search**：搜索网页。
+- **Grok 原生 X Search**：搜索 X 内容。
 
-| Plugin | DSH | DSH host Pi | Plugin Pi | 状态 |
-|---|---|---|---|---|
-| `0.4.2` | `0.1.1-rc.2` | `0.82.1` | `0.84.3` | **VERIFIED STABLE** |
-| `0.4.1` | `0.1.1-rc.2` | `0.82.1` | `0.82.1` | historical stable |
+开启 Grok 原生搜索后，LCX 会使用 xAI 的服务端搜索能力，同时保留页面读取和其他 DSH / MCP 工具。
 
-DSH `0.1.2-alpha.1` 和更新的 Pi 版本目前不属于 `0.4.2` 的正式兼容性声明；后续会按受影响 seam 单独验证，而不是自动视为兼容。
+### 搜索媒体预览
 
-## 当前边界
+**搜索媒体预览**可以独立开启。它只改变回答的显示方式，不会修改模型提示词、搜索请求、聊天历史或缓存。
 
-- 当前支持 route 使用 implicit Prompt Cache；content-level explicit breakpoint 在该 route 上会被拒绝，因此没有作为产品设置开放。
-- dynamic skill / plugin 若改变 top-level tool schema，可能触发一次 prompt-cache reset；功能不受影响，新 topology 会重新 warm。
-- `reasoning.context` / `reasoning.mode` 仍取决于 host/Pi 暴露能力，LCX 不额外造第二套控制面。
-- normal operational context 仍使用约 `262K` 级别配置；1.05M long context 不是默认开启项。
-- credentialed `ALPHA-004` runtime 仍为 `NOT_COVERED`，fail-closed 行为已有测试覆盖。
-- Programmatic Tool Calling 当前不作为已支持能力宣传。
+可识别的图片会显示缩略图并支持放大；直接视频链接可以点击播放。媒体加载失败时，原来的文字和链接仍会保留。
 
-## 常见问题
+## 常见用法
 
-<details>
-<summary><strong>为什么切非 GPT 前要关闭 LCX？</strong></summary>
+直接像平时一样和模型说话，不需要手写工具参数。例如：
 
-LCX ON 是 GPT Responses lifecycle ownership switch，不是通用多模型代理层。非 GPT 模型继续走 DSH 原生 adapter。
+> 搜索 Python 官方文档，告诉我 `asyncio.TaskGroup` 应该怎么用。
 
-</details>
+> 搜索几张金门大桥的照片，显示一张，并给我来源网页。
 
-<details>
-<summary><strong>为什么 web_search 还是同一个工具？</strong></summary>
+> 用 Grok 搜一下 X 上最近关于这个项目的讨论。
 
-这是刻意设计。LCX 改的是 DSH `web_search` 后面的 SearchProvider，不给模型重复暴露两个普通搜索工具。
+长任务也不需要自己盯着上下文。启用 LCX 后，兼容的 GPT 路由会在对话变得很长时自动尝试远程压缩并继续工作；你也可以使用 `/compact` 手动压缩。
 
-</details>
+## 兼容性与已知限制
 
-<details>
-<summary><strong>为什么 Alpha 有时不出现？</strong></summary>
+- `0.4.3-pre.13` 的当前完整验证基线是 DSH `0.1.5-rc.1`。同一 `0.1.5` 系列后续版本处于可安装、可评估范围，但仍会单独记录兼容验证结果；`0.1.6` 及更高版本不会自动视为兼容。
+- 从较旧的 LCX / DSH 版本升级时，建议新建会话；旧版保存的压缩状态不保证兼容。
+- Grok 原生搜索支持 API Key / API 网关路由；xAI OAuth / SuperGrok 登录不在当前范围。
+- Alpha 仍是实验功能。搜索可以正常使用，但连续 `open / find` 等操作在部分路由上仍可能失败；截图也不保证能作为可显示图片返回。
+- 修改 DSH profile 中的插件启用状态后，已经打开的浏览器页面可能需要刷新。
+- 不同 API 网关支持的能力可能不同。普通聊天可用，不代表搜索、长对话压缩或 Alpha 等功能也一定可用。
 
-这是 fail-closed 行为。当前 route/schema 没通过 capability probe 时，`websearch_alpha` 不注册。
+## 遇到问题
 
-</details>
+**安装后看不到变化**：确认安装和启动使用的是同一个 `web` profile，并检查对应功能开关是否已经保存。
 
-<details>
-<summary><strong>为什么加载 skill 后有时缓存会重新 warm？</strong></summary>
+**对话正常，但搜索或压缩失败**：先确认当前 GPT / Grok Responses 路由确实提供对应服务端能力。网关名称本身不代表一定支持所有功能。
 
-某些 skill 会动态注册新的顶层工具。工具 schema 属于可缓存 prompt prefix 的一部分，topology 改变时 provider 可能建立新的 cache epoch。`0.4.2` 优先保证工具定义正确，不通过猜测 provenance 来强行维持旧 cache。
-
-</details>
-
-## 开发与验证
-
-```bash
-npm run typecheck
-npm test
-npm run test:schema
-npm pack --ignore-scripts
-```
+提交 [Issue](https://github.com/kk3ya03-star/dsh-lcx-codex/issues) 时，请附上插件版本、DSH 版本、Node.js 版本和复现步骤。不要上传 API Key、完整请求或未脱敏的会话日志。
 
-- 架构：[ARCHITECTURE.md](ARCHITECTURE.md)
-- 版本记录：[CHANGELOG.md](CHANGELOG.md)
-- GitHub Releases：[Releases](https://github.com/kk3ya03-star/dsh-lcx-codex/releases)
-- npm：[`dsh-lcx-codex`](https://www.npmjs.com/package/dsh-lcx-codex)
+## 更多信息
 
-## License
+- [更新日志](CHANGELOG.md)
+- [架构说明](ARCHITECTURE.md)
+- [第三方许可](THIRD_PARTY_NOTICES.md)
 
-MIT
+## 许可证
 
-> `LCX` 只是项目名称。本项目是社区项目，不隶属于 OpenAI、DeepSeek、Sub2API 或 NewAPI。
+[MIT](LICENSE)。独立社区插件，与 OpenAI、DeepSeek、Sub2API、NewAPI 无隶属或官方背书关系。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,64 @@
+# Third-party notices
+
+`lib/pi-responses-runtime.js` is generated from public exports of the packages below. The build recipe in `scripts/build-pi-runtime.mjs` verifies that no other third-party package contributes output bytes.
+
+## @earendil-works/pi-ai 0.85.1
+
+Upstream source: https://github.com/earendil-works/pi/tree/v0.85.1/packages/ai
+
+Included public Responses helpers and model catalogs:
+
+- `api/openai-responses-shared`
+- `api/constrained-sampling`
+- `api/openai-prompt-cache`
+- `utils/event-stream`
+- model helpers from the package root
+- Responses-bearing catalogs for `cloudflare-ai-gateway`, `github-copilot`, `openai`, `opencode`, `opencode-go`, and `xai`
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## partial-json 0.1.7
+
+Upstream source: https://github.com/promplate/partial-json-parser-js
+
+MIT License
+
+Copyright (c) 2023 Promplate Dev Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cordis.patch.yml

@@ -1,25 +1,8 @@
-# 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.
+# GPT Responses lifecycle plugin. Runtime defaults live in the plugin Config;
+# the bundle declares only route capabilities that differ from conservative defaults.
 - insert:
     - id: lcx-codex
       name: dsh-lcx-codex
       config:
-        provider: lcx
-        baseURL: https://api.lcxbot.com/v1
-        apiKeyEnv: LCX_API_KEY
-        model: gpt-5.6-sol
+        supportsLongCacheRetention: true
         supportsExplicitPromptCacheMode: true
-        legacyCheckpointPath: !!js dshHomePath('storages/lcx-codex/checkpoints-v3.json')
-        alphaCapabilityPath: !!js dshHomePath('storages/lcx-codex/web-alpha-capabilities.json')
-        alphaRefPath: !!js dshHomePath('storages/lcx-codex/web-alpha-refs.json')
-        webSearchProvider: lcx-responses
-        webMaxResults: 8
-        timeoutMs: 300000
-        maxAttempts: 3
-        requestImagePixelBudget: 4194304
-        requestImageMaxBytes: 1048576
-        webSearchTimeoutMs: 240000
-        autoCompactionThresholdPercent: 90
-        emergencyPruneThresholdPercent: 95

package/lib/auxiliary-usage.js

@@ -0,0 +1,63 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const calls = new AsyncLocalStorage();
+const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+/** Collect only authoritative Responses billing, independently of context size. */
+export function recordHostedUsage(response, requestId, provider, model) {
+    const store = calls.getStore();
+    if (!store || !object(response) || !object(response.usage))
+        return;
+    const u = response.usage;
+    const input = u.input_tokens, output = u.output_tokens, total = u.total_tokens;
+    const cached = object(u.input_tokens_details) ? u.input_tokens_details.cached_tokens : undefined;
+    if (!count(input) || !count(output) || !count(total) || !count(cached)
+        || cached > input || input + output !== total)
+        return;
+    store.push({ requestId, provider, model, usage: {
+            inputTokens: input - cached, outputTokens: output, totalTokens: total,
+            cacheReadTokens: cached, cacheWriteTokens: 0,
+        } });
+}
+/** Extend only LCX-owned search output; rendering and request schemas stay intact. */
+export function withAuxiliaryUsage(tool) {
+    const schema = tool.output.schema;
+    if (schema.type !== "object")
+        throw new Error("Search accounting requires an object output");
+    return {
+        ...tool,
+        output: {
+            ...tool.output,
+            schema: { ...schema, properties: { ...schema.properties, auxiliaryUsage: {
+                        type: "array", items: { type: "object", additionalProperties: true },
+                    } } },
+            render(args, value) {
+                if (!object(value))
+                    return tool.output.render(args, value);
+                const { auxiliaryUsage: _billing, ...original } = value;
+                return tool.output.render(args, original);
+            },
+            presentationMeta(args, value) {
+                if (!object(value))
+                    return tool.output.presentationMeta?.(args, value) ?? {};
+                const { auxiliaryUsage, ...original } = value;
+                const meta = tool.output.presentationMeta?.(args, original) ?? {};
+                if (!Array.isArray(auxiliaryUsage) || auxiliaryUsage.length === 0)
+                    return meta;
+                if (!object(meta))
+                    throw new Error("Search accounting requires object presentation metadata");
+                return { ...meta, auxiliaryUsage };
+            },
+        },
+        async execute(args, exec) {
+            const records = [];
+            return calls.run(records, async () => {
+                const value = await tool.execute(args, exec);
+                if (records.length === 0)
+                    return value;
+                if (!object(value))
+                    throw new Error("Search accounting requires an object result");
+                return { ...value, auxiliaryUsage: records };
+            });
+        },
+    };
+}