refactor(openai): simplify connection and endpoint module files

Restore connection.rs for production and integration tests by folding the heartbeat tests into the existing connection test module. Keep all heartbeat coverage while satisfying the workspace layout rules without a subdirectory. Rename provider_endpoint.rs to endpoint.rs in production and tests. Update module declarations, imports and frozen file manifests to match. Validation: gateway application tests (36 passed), all gateway-api tests (263 passed), workspace rustfmt, and strict gateway-api Clippy with all targets and features. Co-authored-by: Codex <noreply@openai.com>
fix(tests): align WebSocket connection module layout
2026-11-07 16:05:27 +00:00 · 2026-09-08 01:51:00 +08:00 · 2026-09-08 01:46:08 +08:00 · 2026-09-08 01:37:11 +08:00 · 2026-09-08 01:36:22 +08:00 · 2026-09-08 01:10:44 +08:00
780 changed files with 76705 additions and 65294 deletions
@@ -45,7 +45,7 @@ jobs:
          ref: ${{ inputs.ref }}

      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Build runtime image
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@@ -55,6 +55,9 @@ jobs:
          target: runtime
          load: true
          tags: ${{ env.CPR_IMAGE }}
+          no-cache-filters: |
+            runtime-base
+            runtime
          cache-from: type=gha,scope=runtime-ci
          cache-to: type=gha,mode=max,scope=runtime-ci

@@ -76,7 +79,7 @@ jobs:
          ${{ hashFiles('trivy-results.sarif') != '' &&
              (github.event_name != 'pull_request' ||
               github.event.pull_request.head.repo.full_name == github.repository) }}
-        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          sarif_file: trivy-results.sarif
          category: runtime-container
@@ -33,6 +33,8 @@ jobs:
    timeout-minutes: 30
    env:
      CARGO_TERM_COLOR: always
+      # Rust 1.97 编译 AWS SDK 调试信息需要更大的 codegen 线程栈。
+      RUST_MIN_STACK: 16777216
      CPR_TEST_DATABASE_URL: postgres://codex_proxy:codex_proxy@127.0.0.1:5432/codex_proxy
      CPR_TEST_REDIS_URL: redis://127.0.0.1:6379
    services:
@@ -4,6 +4,8 @@ on:
  push:
    branches:
      - main
+    paths-ignore:
+      - 'release/version.yaml'
  pull_request:
    branches:
      - main
@@ -163,6 +163,15 @@ jobs:
      ref: ${{ needs.release-info.outputs.git_sha }}
      upload_frontend: true

+  container:
+    needs: [release-info]
+    permissions:
+      contents: read
+      security-events: write
+    uses: ./.github/workflows/_container.yml
+    with:
+      ref: ${{ needs.release-info.outputs.git_sha }}
+
  build-docker-binary:
    name: build-docker-binary (${{ matrix.os }}-${{ matrix.arch }})
    needs: release-info
@@ -448,7 +457,7 @@ jobs:
          PY

      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Login to GHCR
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
@@ -468,6 +477,9 @@ jobs:
          push: true
          build-args: |
            CPR_PREBUILT_DIR=dist/docker
+          no-cache-filters: |
+            runtime-base
+            runtime-prebuilt
          cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }}
          cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }},mode=min
          provenance: mode=max
@@ -494,7 +506,7 @@ jobs:
          exit-code: '1'

  publish:
-    needs: [release-info, package-assets, build-docker-image]
+    needs: [release-info, package-assets, build-docker-image, container]
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
@@ -516,7 +528,7 @@ jobs:
          path: dist/release

      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Install Cosign
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
@@ -614,7 +626,7 @@ jobs:
          cosign sign --yes "${images[@]}"

      - name: Publish GitHub Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
        with:
          tag_name: ${{ needs.release-info.outputs.tag }}
          generate_release_notes: true
@@ -5,192 +5,161 @@

 # Codex Proxy RS

-**基于 Rust 的多 Provider 透明 AI 网关**
+集中管理 OpenAI、xAI 账号，为 Codex 和兼容客户端提供统一的访问地址与密钥。

 [![CI](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/releases)
 [![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
 [![MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/license/mit)

-[快速开始](#快速开始) · [客户端接入](#客户端接入) · [运维](#运维) · [部署](deploy/README.md) · [接口](docs/api.md) · [架构](docs/architecture.md)
+[快速开始](#快速开始) · [客户端接入](#客户端接入) · [常见问题](#常见问题) · [部署说明](deploy/README.md)

 </div>

-> [!NOTE]
-> 只支持 OpenAI Responses API，不提供 `/v1/chat/completions`。
+## 功能

-## 能力
+- 在网页中添加账号，查看额度、请求记录和费用，刷新或重新授权过期账号。
+- 用账号分组控制不同密钥可使用的账号，设置并发和请求频率。
+- 接入 Codex CLI、桌面端和支持 Responses API 的客户端。
+- 支持流式对话、WebSocket、图片生成与编辑、Codex 独立搜索。
+- 支持 S3/R2 数据库备份、同大版本在线更新和回滚。

-| 领域     | 实现                                                                                                  |
-| -------- | ----------------------------------------------------------------------------------------------------- |
-| 协议     | OpenAI Responses JSON、SSE、WebSocket 与模型目录                                                       |
-| Provider | 固定 OpenAI、xAI 两个 Provider；各自管理 OAuth、账号、额度与模型目录                                    |
-| 路由     | Client Key 绑定 Provider、全局模型映射、会话亲和与同 Provider 安全 fallback                             |
-| 透明边界 | OpenAI 请求保留未知字段和字段顺序，SSE 与 WebSocket 原样转发业务字节；xAI 在 Provider 内做协议转换          |
-| 延续     | OpenAI native/replay continuation；xAI 使用客户端提交的完整历史                                          |
-| 账号     | 导入、OAuth、credential 刷新、主动额度刷新，以及正常响应中的被动额度/状态观测                              |
-| 管理     | Client Key、账号、模型目录、设置、观测、系统更新与 OAuth                                                 |
-| 计量     | 模型请求 Token、费用、延迟、账号与 Provider 归因，并记录响应确认的实际 `service_tier`                      |
+支持 OpenAI、xAI 账号，但图片与独立搜索目前仅通过 OpenAI 提供。模型和功能是否可用取决于上游账号权限。
+**不支持 `/v1/chat/completions`**；仅支持该接口的客户端不能直接接入。

 ## 快速开始

-需要 Docker Engine 与 Docker Compose Plugin。
+使用 Docker Compose 部署发布镜像 `ghcr.io/zyycn/codex-proxy-rs:latest`，同时启动 PostgreSQL 和 Redis。
+以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
+[升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置。

-### 1. 准备
+### 1. 下载部署文件并配置

 ```bash
-git clone https://github.com/zyycn/codex-proxy-rs.git
+mkdir -p codex-proxy-rs/deploy
 cd codex-proxy-rs

+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/compose.yaml \
+  -o deploy/compose.yaml
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/config.example.yaml \
+  -o deploy/config.example.yaml
+
 mkdir -p .runtime/data .runtime/logs
 install -d -m 0750 .runtime/postgres .runtime/redis
 cp deploy/config.example.yaml deploy/config.yaml
 sudo chown "$(id -u):10001" deploy/config.yaml
 chmod 0640 deploy/config.yaml
-```
-
-分别生成 PostgreSQL 与 Redis 密码：
-
-```bash
-openssl rand -hex 24
-openssl rand -hex 24
-```
-
-把两个结果写入 `deploy/config.yaml`，并单独设置管理员初始密码：
-
-| 配置                       | 约束                         |
-| -------------------------- | ---------------------------- |
-| `store.database.password`  | 48 位十六进制                 |
-| `store.redis.password`     | 48 位十六进制                 |
-| `admin.default_password`   | 至少 12 位，不能包含 `$`      |
-
-PostgreSQL、Redis 容器和应用通过同一份 `config.yaml` 使用这两个基础设施密码，不需要额外
-导出环境变量。管理员密码只在首次创建管理员时生效。
-
-Linux 需要允许容器组写入运行目录：
-
-```bash
 sudo chown -R "$(id -u):10001" .runtime/data .runtime/logs
 chmod 0770 .runtime/data .runtime/logs
 ```

-### 2. 启动
+分别生成数据库和 Redis 密码：
+
+```bash
+openssl rand -hex 24
+openssl rand -hex 24
+```
+
+编辑 `deploy/config.yaml`，填好以下三项：
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| `store.database.password` | 第一个生成的 48 位十六进制密码 |
+| `store.redis.password` | 第二个生成的 48 位十六进制密码 |
+| `admin.default_password` | 管理员初始密码，至少 12 位，不能包含 `$` |
+
+不需要创建 `.env`。管理员初始密码只在首次创建账号时使用。
+
+### 2. 启动服务

 ```bash
 docker compose -f deploy/compose.yaml config --quiet
 docker compose -f deploy/compose.yaml pull
-docker compose -f deploy/compose.yaml up -d --no-build
+docker compose -f deploy/compose.yaml up -d --no-build --wait
 curl -i http://127.0.0.1:8080/healthz
 ```

-`204 No Content` 表示应用、PostgreSQL 与 Redis 均可用。管理端地址：
-`http://127.0.0.1:8080`。
+健康检查返回 `204 No Content` 后，打开 `http://127.0.0.1:8080`，
+使用 `admin@cpr.local` 和刚设置的管理员密码登录。

-### 3. 初始化
+默认地址只能在服务器本机访问。从其他设备使用时，需要配置
+[HTTPS 反向代理](deploy/README.md#公网访问)。

-1. 使用 `admin@cpr.local` 与初始密码登录。
-2. 在账号页选择对应 Provider：OpenAI 支持 OAuth、账号文件与 Agent Identity；xAI 支持 OAuth
-   和兼容账号文件导入。
-3. 按需配置客户端模型到上游模型的全局映射；未命中映射的模型名原样透传。
-4. 创建 `sk_...` Client Key，绑定 `openai` 或 `xai`，并设置速率与并发限制。
+### 3. 添加账号和密钥

-OpenAI 账号导入和首次 OAuth 创建在 credential 提交后会立即尝试一次额度观测；额度接口临时失败不会
-回滚已提交的账号。Free、K12 等套餐共用同一套额度与状态转换逻辑，套餐字段只作为账号事实并隔离
-对应的模型目录 cache。credential 刷新、额度刷新和正常请求中的被动额度观测是三条独立链路，详见
-[账号接口](docs/api.md#5-账号)。
+1. 在「账号」中添加 OpenAI 或 xAI 账号。OpenAI 支持 OAuth 授权、AT/RT 和账号 JSON；xAI 支持 OAuth 授权和账号 JSON。
+2. 按需创建账号分组，并把账号加入分组。
+3. 创建客户端密钥，选择可用分组。**不选分组表示可使用全部账号**。
+4. 点击该密钥的「使用密钥」，复制客户端配置。

-> [!IMPORTANT]
-> xAI 使用 OAuth session，不支持把 xAI API Key 作为上游 credential。
-
-> [!NOTE]
-> `admin.default_password` 只在首次创建管理员时生效。
-
-完整部署、权限和密码轮换规则见 [deploy/README.md](deploy/README.md)。
+只导入 AT 的账号不能自动续期。xAI 暂不支持用 API Key 导入上游账号。

 ## 客户端接入

-| 配置     | 值                                       |
-| -------- | ---------------------------------------- |
-| Base URL | `http://127.0.0.1:8080/v1`               |
-| API Key  | 管理端创建的 `sk_...`                    |
-| 鉴权     | `Authorization: Bearer <client-api-key>` |
+### Codex CLI 和桌面端
+
+在「使用密钥」中按系统复制 `config.toml` 和 `auth.json`，也可以通过 CCSwitch 导入。
+已有文件先备份，再合并配置并重启 Codex。客户端使用代理密钥，OpenAI 账号登录状态由服务端管理。
+
+新配置已启用原生生图。可以直接提出需求，例如：
+
+> 帮我做一个咖啡店首页，生成一张咖啡主题配图并用到页面中。
+
+是否调用生图由 Codex 根据任务决定，也可以明确要求生成图片。需要支持生图的客户端、模型和 OpenAI 账号；
+普通对话可用不代表账号一定有生图额度。
+
+完整配置和旧版配置迁移见 [客户端配置](deploy/README.md#客户端配置)。
+
+### 其他客户端
+
+选择支持 **Responses API** 的客户端，填写：
+
+| 配置 | 值 |
+| --- | --- |
+| Base URL | `http://127.0.0.1:8080/v1`，远程使用时换成服务器的 HTTPS 地址 |
+| API Key | 管理端创建的 `sk_...` 密钥 |
+
+可先检查密钥是否能读取模型列表：

 ```bash
 curl http://127.0.0.1:8080/v1/models \
  -H 'Authorization: Bearer <client-api-key>'
-
-curl http://127.0.0.1:8080/v1/responses \
-  -H 'Authorization: Bearer <client-api-key>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "model": "<model-id>",
-    "input": "Reply with pong.",
-    "stream": false
-  }'
 ```

-<details>
-<summary>API 路由</summary>
+接口列表与请求示例见 [接口文档](docs/api.md)。

-| 路由                               | 用途                           |
-| ---------------------------------- | ------------------------------ |
-| `POST /v1/responses`               | JSON 响应或 SSE Responses 流    |
-| `GET /v1/responses`                | Responses WebSocket 升级        |
-| `POST /v1/responses/review`        | review 子代理请求               |
-| `GET /v1/models`                   | 当前 Client Key 可用的模型列表   |
-| `GET /v1/models/catalog`           | Codex 客户端展示用模型目录      |
-| `GET /v1/models/{model_id}/info`   | Codex 客户端展示用模型详情      |
-| `GET /v1/models/{model_id}`        | OpenAI 兼容模型详情             |
+## 常见问题

-所有 `/v1/*` 路由都需要客户端 API Key。
+### 仍然要求登录，或无法生成图片

-</details>
+重新从管理端复制配置，确认修改的是客户端实际读取的用户配置目录，然后完全退出并重启客户端。
+保留仅含代理密钥的 `auth.json` 不会使新配置失效。详细检查步骤见
+[登录与生图排查](deploy/README.md#登录与生图排查)。

-完整的客户端与管理端路由、鉴权和 mutation 规则见 [接口文档](docs/api.md)。
+### 没有可用账号或模型

-## 运维
+检查账号是否启用、凭据是否过期、额度是否耗尽，以及密钥绑定的分组是否包含可用账号。
+「恢复账号」只清除本地错误状态，不能恢复上游权限或增加额度。
+
+### 如何更新或查看日志
+
+同一大版本内拉取发布镜像并重建应用容器：

 ```bash
-# 实例升级
 docker compose -f deploy/compose.yaml pull codex-proxy-rs
-docker compose -f deploy/compose.yaml up -d --no-build
-
-# 日志
-docker compose -f deploy/compose.yaml logs -f codex-proxy-rs
-
-# 从源码构建
-docker compose -f deploy/compose.yaml build codex-proxy-rs
-docker compose -f deploy/compose.yaml up -d
+docker compose -f deploy/compose.yaml up -d --no-build codex-proxy-rs
+docker compose -f deploy/compose.yaml logs --tail=100 -f codex-proxy-rs
 ```

-> [!IMPORTANT]
-> `.runtime/` 保存 PostgreSQL、Redis、日志、OpenAI 会话锚点密钥和自更新状态。删除该目录会永久清除
-> 运行状态。
-
 > [!WARNING]
-> 不支持跨大版本在线升级。升级到新的大版本时，请使用全新的 `.runtime/` 数据目录重新部署，
-> 并重新导入或重新授权 Provider 账号与客户端 Key。
-
-Compose 默认只绑定 `127.0.0.1`。公网接入应使用 HTTPS 反向代理，转发 WebSocket
-upgrade 与真实客户端 IP；不要暴露 PostgreSQL 或 Redis。
-
-## 维护与发布
-
-发布仓库版本必须从干净、已同步上游的发布分支运行：
-
-```bash
-release/publish <version>
-```
-
-脚本依赖已登录的 GitHub CLI（`gh auth login`）。它会更新 `release/version.yaml`、创建约定提交与带
-注释的 `v<version>` tag，原子推送分支和 tag，再从发布分支触发 Release 构建，使构建缓存可以跨版本
-复用。不要手工修改版本后单独打 tag。该脚本不会登录服务器，也不会改变任何运行实例；源码提交、
-仓库发版和实例升级是三个独立状态。
+> 升级前先备份。跨大版本需使用新的数据目录重新部署，不支持直接沿用旧库在线升级。
+> `.runtime/` 包含数据库和运行数据，请勿删除；账号文件、密钥和日志也不要公开分享。

 ## 文档

- [部署](deploy/README.md)
- [客户端与管理端接口](docs/api.md)
- [架构与数据边界](docs/architecture.md)
- [Release](https://github.com/zyycn/codex-proxy-rs/releases)
- [容器镜像](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
+- [客户端接入与生图](deploy/README.md#客户端配置)
+- [部署、备份与恢复](deploy/README.md)
+- [API 参考](docs/api.md)
+- [系统架构](docs/architecture.md)
+- [管理端主题](docs/theme.md)
+- [数据库迁移](backend/migrations/README.md)
@@ -26,7 +26,7 @@ tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-th
 [dev-dependencies]
 config = { version = "0.15.23", default-features = false, features = ["yaml"] }
 serde_json = "1"
-syn = { version = "3.0.3", features = ["full"] }
+syn = { version = "3.0.3", features = ["full", "visit"] }
 tempfile = "3.27.0"

 [lints]
@@ -27,8 +27,9 @@ impl LoadableConfig for GatewayConfig {
            return Err(ConfigError::InvalidField("schema_version"));
        }
        self.host.resolve_and_validate(source_dir)?;
+        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
        self.store
-            .resolve_and_validate(source_dir)
+            .resolve_and_validate(&runtime_data_dir)
            .map_err(|_| ConfigError::InvalidField("store"))?;
        self.admin
            .resolve_and_validate(source_dir)
@@ -37,7 +38,7 @@ impl LoadableConfig for GatewayConfig {
            .resolve_and_validate(source_dir)
            .map_err(|_| ConfigError::InvalidField("api"))?;
        self.openai
-            .resolve_and_validate(source_dir)
+            .resolve_and_validate(&runtime_data_dir)
            .map_err(|_| ConfigError::InvalidField("openai"))?;
        self.xai
            .resolve_and_validate(source_dir)
@@ -78,6 +79,7 @@ pub async fn run() -> Result<(), BootstrapError> {
        vec![openai.admin_provider(), xai.admin_provider()],
        core.snapshot_control(),
        core.account_probe(),
+        host.client_distribution_resolver(),
        host.system_operations(),
    )
    .await?;
@@ -1,6 +1,6 @@
 use std::{env, error::Error, io};

-use provider_openai::transport::tls::ensure_rustls_provider;
+use provider_openai::ensure_rustls_provider;

 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    ensure_rustls_provider();
@@ -1,12 +1,15 @@
 //! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。

 use std::{
+    collections::{BTreeMap, BTreeSet},
    fs,
    path::{Path, PathBuf},
 };

+use syn::{Item, visit::Visit};
+
 /// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
-const WORKSPACE_MEMBERS: &[&str] = &[
+pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
    "apps/gateway",
    "crates/gateway-admin",
    "crates/gateway-api",
@@ -58,6 +61,82 @@ fn gateway_core_depends_on_no_http_db_redis_or_provider_crate() {
    );
 }

+#[test]
+fn core_value_owners_do_not_depend_on_execution_or_routing() {
+    let root = backend_root().join("crates/gateway-core/src");
+    for relative in super::rust_files(&root) {
+        let allowed: Option<&[&str]> = match relative.to_str().expect("source path") {
+            "validation.rs" => Some(&[]),
+            "identity.rs" => Some(&["validation"]),
+            "upstream.rs" => Some(&["validation"]),
+            "event.rs" => Some(&["metering", "operation", "upstream", "validation"]),
+            "account/store.rs" => Some(&["account", "error", "identity", "validation"]),
+            path if path.starts_with("policy/") => Some(&["account", "policy", "validation"]),
+            path if path.starts_with("account/") => Some(&["account", "identity", "validation"]),
+            _ => None,
+        };
+        let Some(allowed) = allowed else { continue };
+        let source = fs::read_to_string(root.join(&relative)).expect("read core source");
+        let syntax = syn::parse_file(&source).expect("parse core source");
+        let mut references = CrateReferences::default();
+        references.visit_file(&syntax);
+        for dependency in references.0 {
+            assert!(
+                allowed.contains(&dependency.as_str()),
+                "{} must not depend on crate::{dependency}",
+                relative.display()
+            );
+        }
+    }
+}
+
+#[derive(Default)]
+struct CrateReferences(BTreeSet<String>);
+
+impl<'ast> Visit<'ast> for CrateReferences {
+    fn visit_path(&mut self, path: &'ast syn::Path) {
+        let mut segments = path.segments.iter();
+        if segments
+            .next()
+            .is_some_and(|segment| segment.ident == "crate")
+            && let Some(owner) = segments.next()
+        {
+            self.0.insert(owner.ident.to_string());
+        }
+        syn::visit::visit_path(self, path);
+    }
+
+    fn visit_item_use(&mut self, item: &'ast syn::ItemUse) {
+        self.use_tree(&item.tree, false);
+    }
+}
+
+impl CrateReferences {
+    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
+        match tree {
+            syn::UseTree::Path(path) if crate_root => {
+                self.0.insert(path.ident.to_string());
+            }
+            syn::UseTree::Name(name) if crate_root => {
+                self.0.insert(name.ident.to_string());
+            }
+            syn::UseTree::Rename(rename) if crate_root => {
+                self.0.insert(rename.ident.to_string());
+            }
+            syn::UseTree::Path(path) => self.use_tree(&path.tree, path.ident == "crate"),
+            syn::UseTree::Group(group) => {
+                for item in &group.items {
+                    self.use_tree(item, crate_root);
+                }
+            }
+            syn::UseTree::Glob(_) if crate_root => {
+                self.0.insert("*".to_owned());
+            }
+            _ => {}
+        }
+    }
+}
+
 #[test]
 fn gateway_protocol_has_no_workspace_dependencies() {
    for name in dependency_names("crates/gateway-protocol") {
@@ -95,6 +174,36 @@ const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
    ("provider-xai", "crates/providers/xai"),
 ];

+/// Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
+    ("crates/gateway-api", &["admin", "openai"]),
+    (
+        "crates/gateway-host",
+        &[
+            "client_distribution",
+            "config",
+            "serve",
+            "system_update",
+            "workers",
+        ],
+    ),
+    ("crates/gateway-store", &["backup", "postgres", "redis"]),
+    (
+        "crates/providers/openai",
+        &["config", "credential", "transport"],
+    ),
+    (
+        "crates/providers/xai",
+        &["config", "credential", "transport"],
+    ),
+];
+
+/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景。
+const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
+    ("apps/gateway", &["architecture"]),
+    ("crates/gateway-api", &["architecture"]),
+];
+
 /// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
 const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
    ("codex-proxy-rs", "gateway-admin"),
@@ -123,6 +232,46 @@ const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
 #[test]
 fn workspace_internal_dependency_edges_match_frozen_dag() {
    let metadata = cargo_metadata_json();
+    let actual = workspace_runtime_dependency_edges(&metadata);
+    let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
+        .iter()
+        .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
+        .collect();
+    expected.sort();
+
+    assert_eq!(
+        actual, expected,
+        "workspace internal dependency edges diverged from the frozen DAG"
+    );
+}
+
+#[test]
+fn runtime_dependency_edges_exclude_dev_build_and_external_dependencies() {
+    let metadata = serde_json::json!({
+        "packages": [
+            {
+                "name": "gateway-api",
+                "dependencies": [
+                    { "name": "gateway-core", "kind": null },
+                    { "name": "gateway-store", "kind": "dev" },
+                    { "name": "gateway-host", "kind": "build" },
+                    { "name": "serde", "kind": null }
+                ]
+            },
+            {
+                "name": "external-package",
+                "dependencies": [{ "name": "gateway-core", "kind": null }]
+            }
+        ]
+    });
+
+    assert_eq!(
+        workspace_runtime_dependency_edges(&metadata),
+        vec![("gateway-api".to_owned(), "gateway-core".to_owned())]
+    );
+}
+
+fn workspace_runtime_dependency_edges(metadata: &serde_json::Value) -> Vec<(String, String)> {
    let packages = metadata["packages"]
        .as_array()
        .expect("cargo metadata packages");
@@ -140,31 +289,43 @@ fn workspace_internal_dependency_edges_match_frozen_dag() {
            if !internal_names.contains(dep_name) {
                continue;
            }
-            let is_runtime_edge = dependency["dep_kinds"]
-                .as_array()
-                .map(|kinds| {
-                    kinds
-                        .iter()
-                        .any(|kind| kind["kind"].as_str() == Some("normal"))
-                })
-                .unwrap_or(true);
-            if is_runtime_edge {
+            if dependency.get("kind").expect("dependency kind").is_null() {
                actual.push((name.to_owned(), dep_name.to_owned()));
            }
        }
    }

-    let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
-        .iter()
-        .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
-        .collect();
    actual.sort();
-    expected.sort();
+    actual
+}

-    assert_eq!(
-        actual, expected,
-        "workspace internal dependency edges diverged from the frozen DAG"
-    );
+#[test]
+fn adapter_public_module_surfaces_match_allowlist() {
+    for (member, allowed) in ADAPTER_PUBLIC_MODULES {
+        let root = backend_root().join(member).join("src/lib.rs");
+        let source = fs::read_to_string(&root).expect("read adapter crate root");
+        let syntax = syn::parse_file(&source).expect("parse adapter crate root");
+        let actual = syntax
+            .items
+            .iter()
+            .filter_map(|item| match item {
+                Item::Mod(module) if matches!(module.vis, syn::Visibility::Public(_)) => {
+                    Some(module.ident.to_string())
+                }
+                _ => None,
+            })
+            .collect::<BTreeSet<_>>();
+        let expected = allowed
+            .iter()
+            .map(|module| (*module).to_owned())
+            .collect::<BTreeSet<_>>();
+        assert_eq!(
+            actual,
+            expected,
+            "{} public module surface diverged from its allowlist",
+            root.display()
+        );
+    }
 }

 #[test]
@@ -185,7 +346,192 @@ fn production_sources_do_not_host_tests() {
    }
 }

-fn backend_root() -> PathBuf {
+#[test]
+fn workspace_modules_follow_conventional_file_layout() {
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        assert_module_tree(&member_root.join("src"), &["lib.rs", "main.rs"]);
+
+        let tests = member_root.join("tests");
+        if tests.is_dir() {
+            assert_module_tree(&tests, &["main.rs"]);
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ModuleLayout {
+    File,
+    Directory,
+}
+
+#[test]
+fn integration_tests_mirror_production_module_tree() {
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        let tests_root = member_root.join("tests");
+        if !tests_root.is_dir() {
+            continue;
+        }
+
+        let production = module_layouts(&member_root.join("src"), &["lib.rs", "main.rs"]);
+        let tests = module_layouts(&tests_root, &["main.rs"]);
+        for (module, test_layout) in tests {
+            if module == Path::new("support") {
+                continue;
+            }
+
+            if let Some(production_layout) = production.get(&module) {
+                assert_eq!(
+                    test_layout,
+                    *production_layout,
+                    "{} must mirror the production module layout for {}",
+                    tests_root.join(module.with_extension("rs")).display(),
+                    member_root.join("src").join(&module).display(),
+                );
+                continue;
+            }
+
+            let has_production_owner = module
+                .parent()
+                .into_iter()
+                .flat_map(Path::ancestors)
+                .take_while(|ancestor| !ancestor.as_os_str().is_empty())
+                .any(|ancestor| production.contains_key(ancestor));
+            assert!(
+                has_production_owner || root_test_scenario_allowed(member, &module),
+                "{} has no mirrored production module owner",
+                tests_root.join(module.with_extension("rs")).display(),
+            );
+        }
+    }
+}
+
+fn module_layouts(root: &Path, crate_roots: &[&str]) -> BTreeMap<PathBuf, ModuleLayout> {
+    super::rust_files(root)
+        .into_iter()
+        .filter(|relative| {
+            !crate_roots
+                .iter()
+                .any(|candidate| relative == Path::new(candidate))
+        })
+        .map(|relative| {
+            if relative.file_name().and_then(|value| value.to_str()) == Some("mod.rs") {
+                (
+                    relative.parent().expect("mod.rs parent").to_path_buf(),
+                    ModuleLayout::Directory,
+                )
+            } else {
+                (relative.with_extension(""), ModuleLayout::File)
+            }
+        })
+        .collect()
+}
+
+fn root_test_scenario_allowed(member: &str, module: &Path) -> bool {
+    let Some(module) = module.to_str() else {
+        return false;
+    };
+    ROOT_TEST_SCENARIOS
+        .iter()
+        .any(|(candidate, scenarios)| *candidate == member && scenarios.contains(&module))
+}
+
+fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
+    let files = super::rust_files(root);
+    for relative in &files {
+        if crate_roots
+            .iter()
+            .any(|candidate| relative == Path::new(candidate))
+        {
+            continue;
+        }
+
+        let file_name = relative
+            .file_name()
+            .and_then(|value| value.to_str())
+            .expect("Rust source file name");
+        let parent = relative.parent().expect("Rust source parent");
+        let module_name = if file_name == "mod.rs" {
+            parent
+                .file_name()
+                .and_then(|value| value.to_str())
+                .expect("mod.rs module name")
+        } else {
+            relative
+                .file_stem()
+                .and_then(|value| value.to_str())
+                .expect("Rust source module name")
+        };
+
+        if file_name != "mod.rs" {
+            assert_ne!(
+                parent.file_name().and_then(|value| value.to_str()),
+                Some(module_name),
+                "{} repeats its parent module name",
+                root.join(relative).display()
+            );
+            let child_directory = relative.with_extension("");
+            assert!(
+                !files
+                    .iter()
+                    .any(|candidate| candidate.starts_with(&child_directory)),
+                "{} mixes a leaf module with a same-name module directory",
+                root.join(relative).display()
+            );
+        }
+
+        let declaration_parents = if parent.as_os_str().is_empty()
+            || (file_name == "mod.rs"
+                && parent
+                    .parent()
+                    .is_some_and(|ancestor| ancestor.as_os_str().is_empty()))
+        {
+            crate_roots
+                .iter()
+                .map(|candidate| root.join(candidate))
+                .collect::<Vec<_>>()
+        } else {
+            let declaration_directory = if file_name == "mod.rs" {
+                parent.parent().expect("nested mod.rs parent")
+            } else {
+                parent
+            };
+            vec![root.join(declaration_directory).join("mod.rs")]
+        };
+        let declaration_count = declaration_parents
+            .iter()
+            .map(|path| external_module_declaration_count(path, module_name))
+            .sum::<usize>();
+        assert_eq!(
+            declaration_count,
+            1,
+            "{} must be declared exactly once by its parent module",
+            root.join(relative).display()
+        );
+    }
+}
+
+fn external_module_declaration_count(path: &Path, module_name: &str) -> usize {
+    if !path.is_file() {
+        return 0;
+    }
+    let source = fs::read_to_string(path).expect("read parent module source");
+    let syntax = syn::parse_file(&source).expect("parse parent module source");
+    syntax
+        .items
+        .iter()
+        .filter(|item| {
+            matches!(
+                item,
+                Item::Mod(module)
+                    if module.content.is_none() && module.ident == module_name
+            )
+        })
+        .count()
+}
+
+pub(super) fn backend_root() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../..")
        .canonicalize()
@@ -18,10 +18,18 @@ fn config_loader_should_load_complete_terminal_example() {
 fn config_loader_should_resolve_paths_relative_to_config_file() {
    let (config, _directory) = parse_config(&valid_config()).expect("resolved config");
    let debug = format!("{config:?}");
+    assert!(debug.contains(".runtime/data"));
    assert!(debug.contains(".runtime/logs"));
    assert!(debug.contains("frontend/dist"));
 }

+#[test]
+fn config_loader_should_reject_missing_runtime_data_dir() {
+    let config = valid_config().replace("  runtime_data_dir: '../.runtime/data'\n", "");
+
+    assert!(parse_config(&config).is_err());
+}
+
 #[test]
 fn config_loader_should_inject_connection_passwords_into_urls() {
    parse_config(&valid_config()).expect("Store validates password injection into both URLs");
@@ -135,7 +143,7 @@ fn config_loader_should_reject_removed_fingerprint_section() {

 #[test]
 fn config_loader_should_reject_invalid_codex_cli_version() {
-    assert_rejected(valid_config().replace("codex_version: '0.146.0'", "codex_version: 'latest'"));
+    assert_rejected(valid_config().replace("codex_version: '0.153.4'", "codex_version: 'latest'"));
 }

 #[test]
@@ -154,7 +162,7 @@ fn config_loader_should_reject_zero_server_port() {

 #[test]
 fn config_loader_should_reject_invalid_desktop_profile_fields() {
-    assert_rejected(valid_config().replace("desktop_build: '6119'", "desktop_build: 'build'"));
+    assert_rejected(valid_config().replace("desktop_build: '8109'", "desktop_build: 'build'"));
 }

 fn assert_rejected(config: String) {
@@ -43,31 +43,33 @@ fn cargo_library_root_is_conventional_lib() {
 }

 #[test]
-fn production_files_have_no_hidden_modules_or_test_hooks() {
-    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-    for relative in ["bootstrap.rs", "lib.rs", "main.rs"] {
-        let path = root.join(relative);
-        let source = fs::read_to_string(&path).expect("read production source");
-        assert!(
-            !source.contains("include!("),
-            "{} uses include!",
-            path.display()
-        );
-        let syntax = syn::parse_file(&source).expect("parse production source");
-        for item in &syntax.items {
-            if let Item::Mod(module) = item {
-                assert!(
-                    module.content.is_none(),
-                    "{} has an inline module",
-                    path.display()
-                );
-            }
-            for attribute in item_attrs(item) {
-                assert!(
-                    !is_path_or_test_cfg(attribute),
-                    "{} has a production test/path hook",
-                    path.display(),
-                );
+fn workspace_production_files_have_no_hidden_modules_or_test_hooks() {
+    for member in architecture::WORKSPACE_MEMBERS {
+        let root = architecture::backend_root().join(member).join("src");
+        for relative in rust_files(&root) {
+            let path = root.join(relative);
+            let source = fs::read_to_string(&path).expect("read production source");
+            assert!(
+                !source.contains("include!("),
+                "{} uses include!",
+                path.display()
+            );
+            let syntax = syn::parse_file(&source).expect("parse production source");
+            for item in &syntax.items {
+                if let Item::Mod(module) = item {
+                    assert!(
+                        module.content.is_none(),
+                        "{} has an inline module",
+                        path.display()
+                    );
+                }
+                for attribute in item_attrs(item) {
+                    assert!(
+                        !is_path_or_test_cfg(attribute),
+                        "{} has a production test/path hook",
+                        path.display(),
+                    );
+                }
            }
        }
    }
@@ -12,15 +12,17 @@ name = "main"
 path = "tests/main.rs"

 [dependencies]
-argon2 = "0.5.3"
+argon2 = "0.6.0"
 async-trait = "0.1.89"
 base64 = "0.23.0"
+bytes = "1.11.1"
 chrono = "0.4.45"
 futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
 hex = "0.4.3"
 rand_core = { version = "0.6.4", features = ["getrandom"] }
 serde = { version = "1.0.228", features = ["derive"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 secrecy = { version = "0.10.3", features = ["serde"] }
 subtle = "2.6.1"
 thiserror = "2.0.18"
@@ -28,10 +30,9 @@ tracing = "0.1.44"
 uuid = { version = "1.23.3", features = ["v7"] }
 cron = "0.17"
 chrono-tz = "0.10"
-tokio = { version = "1.52", features = ["rt", "time", "macros"] }
+tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }

 [dev-dependencies]
-serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 sha2 = "0.11"
 tempfile = "3"
 tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt"] }
@@ -119,11 +119,11 @@ pub struct RetentionDecision {

 /// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录。
 ///
-/// 规则（`docs/s3-backup-design-audit.md` §4.4）：
+/// 自动保留规则：
 /// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
 /// - 自动计划备份满足任一启用阈值即可进入删除。
 /// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
-/// - 手动备份不受自动阈值影响；无 TTL，仅由管理员手动删除。
+/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理。
 #[must_use]
 pub fn decide_retention(
    retention_days: u32,
@@ -9,7 +9,7 @@ use std::time::Duration;
 use chrono::{DateTime, Utc};
 use futures::future::BoxFuture;
 use gateway_core::{
-    engine::CancellationToken,
+    lifecycle::CancellationToken,
    task::{DaemonTask, WorkerTaskError},
 };
 use tracing::{info, warn};
@@ -6,7 +6,8 @@ use std::{fmt, path::Path, sync::Arc, time::Duration};

 use gateway_core::{
    engine::probe::AccountProbe,
-    routing::{ProviderKind, snapshot::SnapshotControl},
+    routing::ProviderKind,
+    runtime::SnapshotControl,
    task::{
        DaemonRestartPolicy, WorkerContribution, WorkerId, WorkerKind, WorkerRegistration,
        WorkerRunnable,
@@ -22,19 +23,22 @@ mod use_case;

 pub use use_case::{
    account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
-    backup::BackupService, client_keys::ClientKeyService, observability::ObservabilityService,
-    openai::OpenAiService, settings::SettingsService, system::SystemService, xai::XaiService,
+    backup::BackupService, client_distribution::ClientDistributionService,
+    client_keys::ClientKeyService, observability::ObservabilityService, openai::OpenAiService,
+    settings::SettingsService, system::SystemService, xai::XaiService,
 };

 use model::{AdminError, AdminErrorKind};
 use ports::{
+    client_distribution::ClientDistributionResolver,
    provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind, ProviderAdminRegistry},
    store::AdminStorePorts,
    system::SystemOperations,
 };
 use use_case::{
    account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
-    auth::DefaultAuthService, backup::DefaultBackupService, client_keys::DefaultClientKeyService,
+    auth::DefaultAuthService, backup::DefaultBackupService,
+    client_distribution::DefaultClientDistributionService, client_keys::DefaultClientKeyService,
    observability::DefaultObservabilityService, openai::DefaultOpenAiService,
    settings::DefaultSettingsService, system::DefaultSystemService, xai::DefaultXaiService,
 };
@@ -134,9 +138,9 @@ impl fmt::Debug for AdminConfig {
 /// Admin-owned 启动配置错误；不回显任何配置值。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum AdminConfigError {
-    #[error("configuration field `{0}` is invalid")]
+    #[error("配置字段 `{0}` 不合法")]
    InvalidField(&'static str),
-    #[error("admin.default_password does not meet the initial password policy")]
+    #[error("admin.default_password 不符合初始密码策略")]
    WeakInitialPassword,
 }

@@ -149,6 +153,7 @@ pub struct AdminServices {
    accounts: Arc<dyn AccountsService>,
    account_groups: Arc<dyn AccountGroupService>,
    client_keys: Arc<dyn ClientKeyService>,
+    client_distribution: Arc<dyn ClientDistributionService>,
    observability: Arc<dyn ObservabilityService>,
    settings: Arc<dyn SettingsService>,
    system: Arc<dyn SystemService>,
@@ -178,6 +183,11 @@ impl AdminServices {
        self.client_keys.as_ref()
    }

+    #[must_use]
+    pub fn client_distribution(&self) -> &dyn ClientDistributionService {
+        self.client_distribution.as_ref()
+    }
+
    #[must_use]
    pub fn observability(&self) -> &dyn ObservabilityService {
        self.observability.as_ref()
@@ -238,6 +248,7 @@ pub async fn initialize(
    providers: Vec<Arc<dyn ProviderAdmin>>,
    snapshot: Arc<dyn SnapshotControl>,
    probe: Arc<dyn AccountProbe>,
+    client_distribution: Arc<dyn ClientDistributionResolver>,
    system: Arc<dyn SystemOperations>,
 ) -> Result<AdminBundle, AdminError> {
    config
@@ -261,6 +272,7 @@ pub async fn initialize(

    let accounts = Arc::new(DefaultAccountsService::new(
        store.accounts(),
+        store.account_runtime(),
        registry.clone(),
        snapshot.clone(),
        probe.clone(),
@@ -282,14 +294,17 @@ pub async fn initialize(
        accounts,
        account_groups: Arc::new(DefaultAccountGroupService::new(
            store.account_groups(),
+            store.account_runtime(),
            snapshot.clone(),
        )),
        client_keys: Arc::new(DefaultClientKeyService::new(
            store.client_keys(),
            snapshot.clone(),
        )),
+        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
        observability: Arc::new(DefaultObservabilityService::new(
            store.observability(),
+            store.accounts(),
            store.settings(),
            registry,
        )),
@@ -322,9 +337,9 @@ fn backup_worker_contribution(
    task: backup::task::BackupTask,
 ) -> Result<Vec<WorkerContribution>, AdminError> {
    let id = WorkerId::try_new(WorkerKind::Backup, BACKUP_WORKER_OWNER)
-        .map_err(|_| AdminError::internal("Backup worker id is invalid"))?;
+        .map_err(|_| AdminError::internal("备份 Worker ID 不合法"))?;
    let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
-        .map_err(|_| AdminError::internal("Backup worker restart policy is invalid"))?;
+        .map_err(|_| AdminError::internal("备份 Worker 重启策略不合法"))?;
    let registration = WorkerRegistration::try_new(
        id,
        WorkerRunnable::Daemon {
@@ -332,12 +347,12 @@ fn backup_worker_contribution(
            task: Box::new(task),
        },
    )
-    .map_err(|_| AdminError::internal("Backup worker registration is invalid"))?;
+    .map_err(|_| AdminError::internal("备份 Worker 注册信息不合法"))?;
    Ok(vec![WorkerContribution::Registration(registration)])
 }

 fn provider_kind(value: &'static str) -> Result<ProviderKind, AdminError> {
-    ProviderKind::new(value).map_err(|_| AdminError::internal("Built-in Provider kind is invalid"))
+    ProviderKind::new(value).map_err(|_| AdminError::internal("内置 Provider 类型不合法"))
 }

 fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
@@ -347,8 +362,12 @@ fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
        }
        ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
        ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
-        ProviderAdminErrorKind::Unavailable => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
+        ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
+            AdminErrorKind::Unavailable
+        }
+        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
    };
-    AdminError::new(kind, "Provider registry initialization failed")
+    AdminError::new(kind, "Provider 注册表初始化失败")
 }
@@ -3,7 +3,7 @@
 use std::collections::BTreeMap;

 use chrono::{DateTime, Utc};
-use gateway_core::routing::AccountGroupId;
+use gateway_core::{account::AccountStatusFacts, routing::AccountGroupId};

 use super::{PageSize, Revision, observability::DecimalAmount};

@@ -45,7 +45,17 @@ pub struct AccountGroupCapacity {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupUsage {
    pub today_usd: DecimalAmount,
-    pub total_usd: DecimalAmount,
+    /// 当前 usage retention 窗口内、按请求发生时 routing group 快照归属的累计成本。
+    pub retained_total_usd: DecimalAmount,
+}
+
+/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupMemberFact {
+    pub group_id: AccountGroupId,
+    pub account_id: String,
+    pub status: AccountStatusFacts,
+    pub total_slots: u64,
 }

 /// Lightweight group reference embedded in account and client-key views.
@@ -1,15 +1,18 @@
 //! 多 Provider 账号目录与连接测试的公共事实。

-use std::pin::Pin;
+use std::{collections::BTreeMap, pin::Pin};

 use chrono::{DateTime, Utc};
 use futures::Stream;

-use gateway_core::routing::ProviderKind;
+use gateway_core::{
+    engine::probe::AccountProbeErrorSource, error::GatewayErrorKind, routing::ProviderKind,
+    upstream::UpstreamSendState,
+};

 use super::{PageSize, Revision, account_groups::AccountGroupRef, observability::TimeRange};

-pub use gateway_core::engine::credential::{
+pub use gateway_core::account::{
    AccountConcurrencyLimit, AccountErrorReason, AccountStatus, AccountStatusFacts,
    AccountStatusProjection, AccountWeight, CredentialState, QuotaAccessState, QuotaEvidence,
    QuotaState, resolve_account_status,
@@ -52,6 +55,14 @@ pub struct AccountListQuery {
    pub sort: Option<AccountSort>,
 }

+/// Admin query service 从运行态存储取得的当前账号冷却快照。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AccountRuntimeSnapshot {
+    pub rate_limited_until: BTreeMap<String, DateTime<Utc>>,
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    pub in_flight: Option<BTreeMap<String, u64>>,
+}
+
 /// Optional account membership filter.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountGroupFilter {
@@ -206,7 +217,7 @@ pub struct UpdateAccount {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUpdateResult {
    pub config_revision: Revision,
-    pub account_id: gateway_core::engine::credential::ProviderAccountId,
+    pub account_id: gateway_core::account::ProviderAccountId,
 }

 /// 一批账号可编辑事实的一次性替换命令。
@@ -223,7 +234,7 @@ pub struct BatchUpdateAccounts {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountsUpdateResult {
    pub config_revision: Revision,
-    pub account_ids: Vec<gateway_core::engine::credential::ProviderAccountId>,
+    pub account_ids: Vec<gateway_core::account::ProviderAccountId>,
 }

 /// 账号批量删除命令。
@@ -249,6 +260,9 @@ pub enum AccountConnectionTestEvent {
    },
    Completed,
    Failed {
+        source: AccountProbeErrorSource,
+        gateway_error_code: GatewayErrorKind,
+        send_state: Option<UpstreamSendState>,
        message: String,
        provider_error_code: Option<String>,
        provider_error_type: Option<String>,
@@ -4,6 +4,12 @@ use chrono::{DateTime, Utc};

 use super::{MutationActor, MutationContext, Revision};

+/// 会话审计使用的稳定管理员标识。
+#[must_use]
+pub fn admin_session_actor_ref(admin_user_id: &str) -> String {
+    format!("admin:{admin_user_id}")
+}
+
 /// 已认证的管理主体。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AdminPrincipal {
@@ -0,0 +1,34 @@
+//! 备份领域的稳定错误码。
+
+/// 配置或参数非法。
+pub const INVALID_CONFIG: &str = "backup.invalid_config";
+/// Cron 表达式非法。
+pub const INVALID_CRON: &str = "backup.invalid_cron";
+/// IANA 时区非法。
+pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
+/// 记录不存在。
+pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
+/// 已存在活跃任务，拒绝创建。
+pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
+/// 记录状态与期望不符，无法迁移。
+pub const STATE_CONFLICT: &str = "backup.state_conflict";
+/// 已有记录时禁止切换存储目标。
+pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
+/// `pg_dump` 非零退出或失败。
+pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
+/// 暂存磁盘空间不足。
+pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
+/// S3 认证失败。
+pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
+/// S3 权限拒绝。
+pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
+/// S3 上传失败。
+pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
+/// 远端对象校验失败。
+pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
+/// 任务被取消。
+pub const CANCELLED: &str = "backup.cancelled";
+/// 仓储或对象存储暂不可用。
+pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
+/// 上游 S3 服务返回无效或失败响应。
+pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";
@@ -288,7 +288,7 @@ pub struct BackupRecord {
    pub error_message: Option<String>,
    pub started_at: Option<DateTime<Utc>>,
    pub completed_at: Option<DateTime<Utc>>,
-    /// 手动过期时间；创建时确定，到期自动清理。
+    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理。
    pub expires_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
@@ -447,40 +447,7 @@ impl BackupError {
 }

 /// 构造稳定错误码常量。
-pub mod code {
-    /// 配置或参数非法。
-    pub const INVALID_CONFIG: &str = "backup.invalid_config";
-    /// Cron 表达式非法。
-    pub const INVALID_CRON: &str = "backup.invalid_cron";
-    /// IANA 时区非法。
-    pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
-    /// 记录不存在。
-    pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
-    /// 已存在活跃任务，拒绝创建。
-    pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
-    /// 记录状态与期望不符，无法迁移。
-    pub const STATE_CONFLICT: &str = "backup.state_conflict";
-    /// 已有记录时禁止切换存储目标。
-    pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
-    /// `pg_dump` 非零退出或失败。
-    pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
-    /// 暂存磁盘空间不足。
-    pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
-    /// S3 认证失败。
-    pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
-    /// S3 权限拒绝。
-    pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
-    /// S3 上传失败。
-    pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
-    /// 远端对象校验失败。
-    pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
-    /// 任务被取消。
-    pub const CANCELLED: &str = "backup.cancelled";
-    /// 仓储或对象存储暂不可用。
-    pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
-    /// 上游 S3 服务返回无效或失败响应。
-    pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";
-}
+pub mod code;

 /// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`。
 ///
@@ -0,0 +1,58 @@
+//! 管理设置页使用的 Codex 客户端下载信息。
+
+use chrono::{DateTime, Utc};
+
+/// Windows 安装包架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum ClientArchitecture {
+    X64,
+    Arm64,
+}
+
+impl ClientArchitecture {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::X64 => "x64",
+            Self::Arm64 => "arm64",
+        }
+    }
+}
+
+/// 下载地址的可信来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientDownloadSource {
+    MicrosoftStore,
+    OfficialOpenAi,
+}
+
+impl ClientDownloadSource {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::MicrosoftStore => "microsoft_store",
+            Self::OfficialOpenAi => "official_openai",
+        }
+    }
+}
+
+/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientDownloadPackage {
+    pub architecture: ClientArchitecture,
+    pub source: ClientDownloadSource,
+    pub version: Option<String>,
+    pub file_name: String,
+    pub size_bytes: Option<u64>,
+    pub download_url: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// Codex Desktop Windows 下载解析结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CodexDesktopWindowsDownloads {
+    pub resolved_at: DateTime<Utc>,
+    pub cached: bool,
+    pub warning: Option<String>,
+    pub packages: Vec<ClientDownloadPackage>,
+}
@@ -6,6 +6,7 @@ pub mod account_groups;
 pub mod accounts;
 pub mod auth;
 pub mod backup;
+pub mod client_distribution;
 pub mod client_keys;
 pub mod observability;
 pub mod provider_credentials;
@@ -21,11 +22,12 @@ pub enum AdminErrorKind {
    Conflict,
    RateLimited,
    BadGateway,
+    UpstreamResultUnknown,
    Unavailable,
    Internal,
 }

-/// 不携带基础设施细节的管理用例错误。
+/// 不携带基础设施细节、可安全返回给管理员的管理用例错误。
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
 #[error("{message}")]
 pub struct AdminError {
@@ -47,6 +49,12 @@ impl AdminError {
        self.kind
    }

+    /// 返回已脱敏、可公开给管理员的文案。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
    #[must_use]
    pub fn invalid(message: impl Into<String>) -> Self {
        Self::new(AdminErrorKind::Invalid, message)
@@ -72,6 +80,11 @@ impl AdminError {
        Self::new(AdminErrorKind::BadGateway, message)
    }

+    #[must_use]
+    pub fn upstream_result_unknown(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::UpstreamResultUnknown, message)
+    }
+
    #[must_use]
    pub fn unavailable(message: impl Into<String>) -> Self {
        Self::new(AdminErrorKind::Unavailable, message)
@@ -1,6 +1,6 @@
 //! 用量、成本、健康与错误诊断的 UTC 语义事实。

-use std::{num::NonZeroU32, str::FromStr};
+use std::str::FromStr;

 use chrono::{DateTime, TimeDelta, Timelike as _, Utc};

@@ -38,29 +38,6 @@ impl TimeRange {
    }
 }

-/// 从一开始的观测页码。
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct PageNumber(NonZeroU32);
-
-impl PageNumber {
-    #[must_use]
-    pub const fn new(value: NonZeroU32) -> Self {
-        Self(value)
-    }
-
-    #[must_use]
-    pub const fn get(self) -> u32 {
-        self.0.get()
-    }
-}
-
-/// 观测记录的稳定键集游标。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ObservabilityCursor {
-    pub observed_at: DateTime<Utc>,
-    pub stable_id: String,
-}
-
 /// 请求结果状态。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum RequestOutcome {
@@ -146,8 +123,7 @@ pub struct UsageFilter {
 pub struct UsageQuery {
    pub range: TimeRange,
    pub filter: UsageFilter,
-    pub cursor: Option<ObservabilityCursor>,
-    pub page: PageNumber,
+    pub current_page: u32,
    pub page_size: PageSize,
 }

@@ -164,7 +140,6 @@ pub struct OpsErrorFilter {
    pub attempt_index: Option<u32>,
    pub response_id: Option<String>,
    pub upstream_request_id: Option<String>,
-    pub failure_kind: Option<String>,
    pub status_code: Option<u16>,
    pub search: Option<String>,
 }
@@ -174,8 +149,7 @@ pub struct OpsErrorFilter {
 pub struct OpsErrorQuery {
    pub range: TimeRange,
    pub filter: OpsErrorFilter,
-    pub cursor: Option<ObservabilityCursor>,
-    pub page: PageNumber,
+    pub current_page: u32,
    pub page_size: PageSize,
 }

@@ -213,11 +187,11 @@ impl DecimalAmount {
        Self::from_decimal(self.to_decimal()?.checked_div_u64(divisor)?)
    }

-    fn to_decimal(&self) -> Option<gateway_core::accounting::Decimal> {
+    fn to_decimal(&self) -> Option<gateway_core::metering::Decimal> {
        self.0.parse().ok()
    }

-    fn from_decimal(value: gateway_core::accounting::Decimal) -> Option<Self> {
+    fn from_decimal(value: gateway_core::metering::Decimal) -> Option<Self> {
        Some(Self(value.canonical()))
    }
 }
@@ -402,6 +376,16 @@ pub struct RequestMetrics {
    pub max_latency_ms: Option<u64>,
    pub latency_percentiles: LatencyPercentiles,
    pub first_token_latency_percentiles: LatencyPercentiles,
+    pub admission_decision_count: u64,
+    pub admission_decision_percentiles: LatencyPercentiles,
+    pub account_selection_wait_count: u64,
+    pub account_selection_wait_percentiles: LatencyPercentiles,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_sample_count: u64,
+    pub capacity_utilization_avg_basis_points: Option<u64>,
+    pub capacity_utilization_p95_basis_points: Option<u64>,
    pub cache_eligible_request_count: u64,
    pub cache_hit_request_count: u64,
 }
@@ -507,6 +491,8 @@ pub struct DashboardAccountUsage {
    ///
    /// `None` 表示上游未提供可比较的百分比，不应伪造为零。
    pub quota_used_percent: Option<f64>,
+    /// Provider 返回的代表窗口；缺失时保留未知语义。
+    pub quota_window: Option<super::provider_credentials::ProviderQuotaWindow>,
    pub models: Vec<DashboardAccountModelUsage>,
 }

@@ -535,13 +521,60 @@ pub struct DashboardTotals {
 #[derive(Debug, Clone, PartialEq)]
 pub struct DashboardObservation {
    pub range: TimeRange,
-    pub requests: RequestMetrics,
-    pub attempts: AttemptMetrics,
    pub totals: DashboardTotals,
    pub provider_accounts: AccountPoolMetrics,
    pub trend: Vec<RequestMetricPoint>,
    pub account_usage: Vec<DashboardAccountUsage>,
-    pub recent_requests: Vec<UsageRecord>,
+    pub recent_requests: Vec<UsageListRecord>,
+}
+
+/// 使用记录表格的窄读模型。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageListRecord {
+    pub id: String,
+    pub endpoint: String,
+    pub client_transport: String,
+    pub requested_model_id: Option<String>,
+    pub provider_kind: Option<String>,
+    pub provider_account_ref: Option<String>,
+    pub provider_account_name: Option<String>,
+    pub provider_account_email: Option<String>,
+    pub provider_account_authentication_kind: Option<String>,
+    pub upstream_model_id: Option<String>,
+    pub upstream_transport: Option<String>,
+    pub service_tier: Option<String>,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub total_tokens: Option<u64>,
+    pub cost_source: String,
+    pub cost_amount: Option<DecimalAmount>,
+    pub cost_currency: Option<String>,
+    pub billing: Option<UsageBilling>,
+    pub transport_decision_wait_ms: Option<u64>,
+    pub connect_ms: Option<u64>,
+    pub headers_ms: Option<u64>,
+    pub first_event_ms: Option<u64>,
+    pub first_reasoning_ms: Option<u64>,
+    pub first_text_ms: Option<u64>,
+    pub first_token_ms: Option<u64>,
+    pub provider_processing_ms: Option<u64>,
+    pub latency_ms: Option<u64>,
+    pub admission_decision_ms: Option<u64>,
+    pub account_selection_wait_ms: Option<u64>,
+    pub capacity_used_slots: Option<u64>,
+    pub capacity_total_slots: Option<u64>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: bool,
+    pub started_at: DateTime<Utc>,
 }

 /// 一次完整模型请求的公共观测记录。
@@ -557,7 +590,7 @@ pub struct UsageRecord {
    pub operation: String,
    pub endpoint: String,
    pub client_transport: String,
-    pub requested_model_id: String,
+    pub requested_model_id: Option<String>,
    pub provider_kind: Option<String>,
    pub provider_account_ref: Option<String>,
    pub provider_account_name: Option<String>,
@@ -604,6 +637,10 @@ pub struct UsageRecord {
    pub first_token_ms: Option<u64>,
    pub provider_processing_ms: Option<u64>,
    pub latency_ms: Option<u64>,
+    pub admission_decision_ms: Option<u64>,
+    pub account_selection_wait_ms: Option<u64>,
+    pub capacity_used_slots: Option<u64>,
+    pub capacity_total_slots: Option<u64>,
    pub client_ip: Option<String>,
    pub user_agent: Option<String>,
    pub reasoning_effort: Option<String>,
@@ -621,9 +658,10 @@ pub struct UsageRecord {
 /// 用量分页结果。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UsagePage {
-    pub items: Vec<UsageRecord>,
+    pub items: Vec<UsageListRecord>,
+    pub current_page: u32,
+    pub page_size: u16,
    pub total: u64,
-    pub next_cursor: Option<ObservabilityCursor>,
 }

 /// 请求中的一次上游尝试或运维事件。
@@ -666,6 +704,8 @@ pub struct UsageAttempt {
 /// 一条请求及其全部尝试。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UsageDetail {
+    pub trace: Option<serde_json::Value>,
+    pub related_requests: Vec<serde_json::Value>,
    pub request: UsageRecord,
    pub attempts: Vec<UsageAttempt>,
 }
@@ -708,6 +748,9 @@ pub struct DiagnosticObservation {
    pub total_tokens: u64,
    pub average_latency_ms: Option<u64>,
    pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub retry_count: u64,
    pub cost_coverage: CostCoverage,
    pub costs: Vec<CurrencyCost>,
 }
@@ -722,6 +765,10 @@ pub struct OpsError {
    pub client_api_key_ref: Option<String>,
    pub component: String,
    pub operation: String,
+    pub protocol: Option<String>,
+    pub client_transport: Option<String>,
+    pub requested_model_id: Option<String>,
+    pub service_tier: Option<String>,
    pub endpoint: Option<String>,
    pub provider_kind: Option<String>,
    pub provider_account_ref: Option<String>,
@@ -731,6 +778,7 @@ pub struct OpsError {
    pub upstream_model_id: Option<String>,
    pub upstream_transport: Option<String>,
    pub failure_kind: String,
+    pub upstream_send_state: Option<String>,
    pub client_status_code: Option<u16>,
    pub upstream_status_code: Option<u16>,
    pub provider_error_code: Option<String>,
@@ -738,7 +786,26 @@ pub struct OpsError {
    pub upstream_request_id: Option<String>,
    pub latency_ms: Option<u64>,
    pub message: String,
-    pub occurrence_count: u32,
+    pub raw_upstream_error: Option<String>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: Option<bool>,
+    pub continuation_affinity_hash: Option<String>,
+    pub continuation_previous_response_id_hash: Option<String>,
+    pub continuation_unavailable_reason: Option<String>,
+    pub upstream_connection_id: Option<String>,
+    pub upstream_connection_exit_reason: Option<String>,
+    pub upstream_connection_age_ms: Option<u64>,
+    pub upstream_connection_idle_ms: Option<u64>,
+    pub recovery_request_id: Option<String>,
+    pub recovered_at: Option<DateTime<Utc>>,
+    pub recovery_attempt_count: u32,
+    pub recovery_retry_delay_ms: Option<u64>,
+    pub recovery_total_latency_ms: Option<u64>,
    pub occurred_at: DateTime<Utc>,
    pub stable_sort_id: String,
 }
@@ -747,8 +814,9 @@ pub struct OpsError {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OpsErrorPage {
    pub items: Vec<OpsError>,
+    pub current_page: u32,
+    pub page_size: u16,
    pub total: u64,
-    pub next_cursor: Option<ObservabilityCursor>,
 }

 /// 仪表盘趋势指标。
@@ -787,6 +855,9 @@ pub struct TrendSummary {
    pub average_latency_ms: Option<u64>,
    pub max_latency_ms: Option<u64>,
    pub min_latency_ms: Option<u64>,
+    pub peak_first_token_p95_ms: Option<f64>,
+    pub peak_latency_p95_ms: Option<f64>,
+    pub minimum_output_throughput_p50: Option<u64>,
    pub success_rate: Option<f64>,
    pub cache_hit_request_rate: Option<f64>,
    pub costs: Vec<CurrencyCost>,
@@ -935,6 +1006,7 @@ pub struct DashboardResult {
 /// 洞察健康时间点的语义结果。
 #[derive(Debug, Clone, PartialEq)]
 pub struct UsageInsightsHealthPoint {
+    pub total_requests: u64,
    pub bucket_start: DateTime<Utc>,
    pub success_requests: u64,
    pub failed_requests: u64,
@@ -954,6 +1026,7 @@ pub struct UsageInsightsHealth {
    pub incomplete_requests: u64,
    pub caller_error_requests: u64,
    pub success_rate: f64,
+    pub completion_rate: f64,
    pub points: Vec<UsageInsightsHealthPoint>,
 }

@@ -963,6 +1036,13 @@ pub struct UsageInsightsPerformancePoint {
    pub bucket_start: DateTime<Utc>,
    pub latency_percentiles: LatencyPercentiles,
    pub first_token_latency_percentiles: LatencyPercentiles,
+    pub admission_decision_percentiles: LatencyPercentiles,
+    pub account_selection_wait_percentiles: LatencyPercentiles,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization_avg_basis_points: Option<u64>,
+    pub capacity_utilization_p95_basis_points: Option<u64>,
 }

 /// 洞察性能汇总与可观测覆盖率。
@@ -972,6 +1052,16 @@ pub struct UsageInsightsPerformance {
    pub first_token_latency_percentiles: LatencyPercentiles,
    pub latency_coverage: f64,
    pub first_token_coverage: f64,
+    pub admission_decision_percentiles: LatencyPercentiles,
+    pub account_selection_wait_percentiles: LatencyPercentiles,
+    pub admission_decision_coverage: f64,
+    pub account_selection_wait_coverage: f64,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization_avg_basis_points: Option<u64>,
+    pub capacity_utilization_p95_basis_points: Option<u64>,
+    pub capacity_coverage: f64,
    pub points: Vec<UsageInsightsPerformancePoint>,
 }

@@ -985,6 +1075,8 @@ pub struct UsageInsightsCostPoint {
    pub total_tokens: u64,
    pub estimated_cost: Option<DecimalAmount>,
    pub standard_cost: Option<DecimalAmount>,
+    pub no_cache_cost: Option<DecimalAmount>,
+    pub cache_savings: Option<DecimalAmount>,
    pub cached_token_rate: f64,
    pub cache_hit_request_rate: Option<f64>,
 }
@@ -994,7 +1086,11 @@ pub struct UsageInsightsCostPoint {
 pub struct UsageInsightsCost {
    pub estimated_cost: Option<DecimalAmount>,
    pub standard_cost: Option<DecimalAmount>,
+    pub no_cache_cost: Option<DecimalAmount>,
+    pub cache_savings: Option<DecimalAmount>,
+    pub tier_premium: Option<DecimalAmount>,
    pub cost_per_request: Option<DecimalAmount>,
+    pub cost_per_successful_request: Option<DecimalAmount>,
    pub tokens_per_request: f64,
    pub cached_token_rate: f64,
    pub cache_hit_request_rate: Option<f64>,
@@ -1030,6 +1126,12 @@ pub struct DiagnosticsItem {
    pub request_share: f64,
    pub average_latency_ms: Option<u64>,
    pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub non_completion_rate: f64,
+    pub retry_count: u64,
+    pub retry_rate: f64,
+    pub impact_score: f64,
    pub estimated_cost: Option<DecimalAmount>,
    pub attempt_count: u64,
    pub total_tokens: u64,
@@ -1,13 +1,18 @@
 //! Provider 管理能力交换的中立 Command 与 Result。

-use std::fmt;
+use std::{fmt, pin::Pin};

 use async_trait::async_trait;
-use chrono::{DateTime, Utc};
+use bytes::Bytes;
+use chrono::{DateTime, NaiveDate, Utc};
+use futures::Stream;
 use gateway_core::{
-    engine::credential::{OpaqueProviderData, ProviderAccountId, ProviderAccountIdentity},
+    account::{OpaqueProviderData, ProviderAccountId, ProviderAccountIdentity},
    routing::{ProviderKind, UpstreamModelId},
 };
+use serde::Deserialize;
+use serde_json::{Map, Value};
+use uuid::Uuid;

 use super::{
    AdminError, MutationActor, MutationContext, PageSize, Revision,
@@ -276,6 +281,101 @@ impl PendingAuthorizationMutation {
    }
 }

+impl PendingAuthorizationMutation {
+    /// 编码 v1 中立事务字段；版本号的位置和 Provider 私有外层文档由 adapter 保持。
+    #[must_use]
+    pub fn to_storage_v1(&self) -> Map<String, Value> {
+        let target = match &self.target {
+            AuthorizationMutationTarget::Create { name } => {
+                serde_json::json!({"kind": "create", "name": name})
+            }
+            AuthorizationMutationTarget::Reauthorize { account_id } => {
+                serde_json::json!({"kind": "reauthorize", "account_id": account_id.to_string()})
+            }
+        };
+        let owner = match self.owner_binding.owner() {
+            AuthorizationOwner::AdminSession { admin_user_id } => {
+                serde_json::json!({"kind": "admin_session", "admin_user_id": admin_user_id})
+            }
+            AuthorizationOwner::AdminApiKey => serde_json::json!({"kind": "admin_api_key"}),
+            AuthorizationOwner::System => serde_json::json!({"kind": "system"}),
+        };
+        Map::from_iter([
+            (
+                "provider_kind".to_owned(),
+                Value::String(self.provider_kind.as_str().to_owned()),
+            ),
+            ("target".to_owned(), target),
+            ("owner".to_owned(), owner),
+            (
+                "started_request_id".to_owned(),
+                Value::String(self.owner_binding.started_request_id().to_owned()),
+            ),
+        ])
+    }
+
+    /// 恢复 adapter 已确认版本为 v1 的中立事务字段。
+    ///
+    /// # Errors
+    ///
+    /// 文档字段、Provider kind 或账号身份非法时返回错误，不携带原始 pending 内容。
+    pub fn from_storage_v1(value: Value) -> Result<Self, AdminError> {
+        let invalid = || AdminError::invalid("invalid pending authorization mutation");
+        let document: StoredAuthorizationMutationV1 =
+            serde_json::from_value(value).map_err(|_| invalid())?;
+        let provider_kind = ProviderKind::new(document.provider_kind).map_err(|_| invalid())?;
+        let target = match document.target {
+            StoredAuthorizationTargetV1::Create { name } => {
+                AuthorizationMutationTarget::Create { name }
+            }
+            StoredAuthorizationTargetV1::Reauthorize { account_id } => {
+                AuthorizationMutationTarget::Reauthorize {
+                    account_id: ProviderAccountId::new(account_id).map_err(|_| invalid())?,
+                }
+            }
+        };
+        let owner = match document.owner {
+            StoredAuthorizationOwnerV1::AdminSession { admin_user_id } => {
+                AuthorizationOwner::AdminSession { admin_user_id }
+            }
+            StoredAuthorizationOwnerV1::AdminApiKey => AuthorizationOwner::AdminApiKey,
+            StoredAuthorizationOwnerV1::System => AuthorizationOwner::System,
+        };
+        Ok(Self::new(
+            provider_kind,
+            target,
+            AuthorizationOwnerBinding {
+                owner,
+                started_request_id: document.started_request_id,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StoredAuthorizationMutationV1 {
+    provider_kind: String,
+    target: StoredAuthorizationTargetV1,
+    owner: StoredAuthorizationOwnerV1,
+    started_request_id: String,
+}
+
+#[derive(Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+enum StoredAuthorizationTargetV1 {
+    Create { name: String },
+    Reauthorize { account_id: String },
+}
+
+#[derive(Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+enum StoredAuthorizationOwnerV1 {
+    AdminSession { admin_user_id: String },
+    AdminApiKey,
+    System,
+}
+
 /// 启动 Provider OAuth Authorization Code 流程。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct StartAuthorization {
@@ -570,13 +670,34 @@ pub enum QuotaLocalUsageAttribution {
    Unavailable,
 }

+/// Provider quota bucket 中窗口的官方位置语义。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProviderQuotaWindowRole {
+    Primary,
+    Secondary,
+    Monthly,
+}
+
+impl ProviderQuotaWindowRole {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Primary => "primary",
+            Self::Secondary => "secondary",
+            Self::Monthly => "monthly",
+        }
+    }
+}
+
 /// 一个 Provider quota 窗口的公共投影。
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuotaWindow {
    pub key: String,
    pub group: String,
    pub label: String,
-    pub source: Option<String>,
+    pub limit_id: Option<String>,
+    pub limit_name: Option<String>,
+    pub role: Option<ProviderQuotaWindowRole>,
    pub local_usage_attribution: QuotaLocalUsageAttribution,
    pub window_seconds: Option<u64>,
    pub used_percent: Option<f64>,
@@ -605,11 +726,125 @@ pub struct ProviderQuota {
    pub provider_data: Option<ProviderDocument>,
 }

+/// Provider 官方个人资料中的累计摘要。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderProfileStatisticsSummary {
+    pub total_text_tokens: Option<u64>,
+    pub peak_tokens: Option<u64>,
+    pub longest_task_duration_ms: Option<u64>,
+    pub current_streak_days: Option<u64>,
+    pub longest_streak_days: Option<u64>,
+}
+
+/// Provider 官方个人资料中的单日 Token bucket。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderProfileDailyUsage {
+    pub date: NaiveDate,
+    pub tokens: u64,
+}
+
+/// Provider 官方个人资料中的插件或 Skill 调用排行。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderProfileInvocation {
+    pub invocation_type: String,
+    pub plugin_id: Option<String>,
+    pub plugin_name: Option<String>,
+    pub skill_id: Option<String>,
+    pub skill_name: Option<String>,
+    pub usage_count: Option<u64>,
+}
+
+/// Provider 官方个人资料中的活动洞察。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProviderProfileActivityInsights {
+    pub fast_mode_percent: Option<f64>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_effort_percent: Option<f64>,
+    pub skills_explored: Option<u64>,
+    pub total_skills_used: Option<u64>,
+    pub total_threads: Option<u64>,
+    pub invocations: Option<Vec<ProviderProfileInvocation>>,
+}
+
+/// Provider 已解释的官方个人资料统计。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProviderProfileStatistics {
+    pub display_name: Option<String>,
+    pub username: Option<String>,
+    pub image_url: Option<String>,
+    pub has_stats_error: bool,
+    pub summary: ProviderProfileStatisticsSummary,
+    pub daily_usage: Option<Vec<ProviderProfileDailyUsage>>,
+    pub activity_insights: ProviderProfileActivityInsights,
+}
+
+/// Provider 头像正文的中立字节流；公共层不解释 MIME，也不限制总字节数。
+pub type ProviderProfileAvatarStream =
+    Pin<Box<dyn Stream<Item = Result<Bytes, ProviderProfileAvatarStreamError>> + Send + 'static>>;
+
+/// Provider 头像流在响应开始后的通用失败，不携带上游 URL 或正文。
+#[derive(Debug, thiserror::Error)]
+#[error("provider profile avatar stream failed")]
+pub struct ProviderProfileAvatarStreamError;
+
+/// Provider 已校验并打开的官方头像响应。
+pub struct ProviderProfileAvatar {
+    pub content_type: Option<String>,
+    pub content_length: Option<u64>,
+    pub etag: Option<String>,
+    pub body: ProviderProfileAvatarStream,
+}
+
+impl fmt::Debug for ProviderProfileAvatar {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ProviderProfileAvatar")
+            .field("content_type", &self.content_type)
+            .field("content_length", &self.content_length)
+            .field("etag", &self.etag)
+            .field("body", &"<stream>")
+            .finish()
+    }
+}
+
+/// Provider 返回的一张安全主动额度重置卡。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderResetCredit {
+    pub id: String,
+    pub status: Option<String>,
+    pub title: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub reset_type: Option<String>,
+}
+
+/// Provider 主动额度重置卡列表。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderResetCredits {
+    pub available_count: u64,
+    pub credits: Vec<ProviderResetCredit>,
+}
+
+/// 一次主动额度重置卡消费命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConsumeProviderResetCredit {
+    pub account_id: ProviderAccountId,
+    pub credit_id: Option<String>,
+    pub redeem_request_id: Uuid,
+}
+
+/// Provider 返回的主动额度重置卡消费结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderResetCreditResult {
+    pub code: String,
+    pub credit: Option<ProviderResetCredit>,
+}
+
 impl ProviderQuota {
    /// 返回账号展开面板使用的当前额度窗口用量。
    ///
-    /// 只选择具备完整时间边界且可按账号归属的窗口；优先级与 Dashboard
-    /// 代表性额度窗口一致，同一优先级保持 Provider 投影顺序。
+    /// Provider 已提供账号级本地用量时，固定窗口和无固定重置点的滚动窗口
+    /// 都可作为代表用量；优先级与 Dashboard 代表性额度窗口一致，
+    /// 同一优先级保持 Provider 投影顺序。
    #[must_use]
    pub fn representative_window_usage(&self) -> Option<&AccountUsage> {
        self.windows
@@ -618,7 +853,6 @@ impl ProviderQuota {
            .filter(|(_, window)| {
                window.local_usage_attribution == QuotaLocalUsageAttribution::AccountWide
                    && window.window_seconds.is_some()
-                    && window.reset_at.is_some()
                    && window.local_usage.is_some()
            })
            .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
@@ -627,39 +861,108 @@ impl ProviderQuota {

    /// 返回 Dashboard 使用的代表性额度比例。
    ///
-    /// 优先使用短周期窗口，再依次使用周、月和其它窗口；同一优先级取较高的已用比例。
-    /// 这里只解释跨 Provider 共享的窗口语义，绝不读取 Provider 私有 JSON。
+    /// 优先使用覆盖账号全部请求的窗口；同一归属范围内再依次使用短周期、周、月
+    /// 和其它窗口，同一优先级取较高的已用比例。这里只解释跨 Provider 共享的窗口
+    /// 语义，绝不读取 Provider 私有 JSON。
    #[must_use]
    pub fn representative_used_percent(&self) -> Option<f64> {
+        if self.limit_reached {
+            return Some(100.0);
+        }
+        self.representative_used_window()
+            .map(|(_, used_percent)| used_percent)
+    }
+
+    /// 选择 Dashboard 展示的真实窗口；没有百分比时仍保留 Provider 的滚动窗口语义。
+    #[must_use]
+    pub fn representative_window(&self) -> Option<&ProviderQuotaWindow> {
+        self.representative_used_window()
+            .map(|(index, _)| &self.windows[index])
+            .or_else(|| {
+                self.windows
+                    .iter()
+                    .enumerate()
+                    .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
+                    .map(|(_, window)| window)
+            })
+    }
+
+    /// 将已确认的账号级额度耗尽事实投影到展示窗口。
+    ///
+    /// Provider 已指出具体触顶窗口时只归一化这些窗口；否则归一化 Dashboard
+    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽。
+    pub fn apply_limit_reached_display(&mut self) {
+        if !self.limit_reached {
+            return;
+        }
+        let reached_windows = self
+            .windows
+            .iter()
+            .enumerate()
+            .filter_map(|(index, window)| window.limit_reached.then_some(index))
+            .collect::<Vec<_>>();
+        if !reached_windows.is_empty() {
+            for index in reached_windows {
+                self.windows[index].used_percent = Some(100.0);
+            }
+            return;
+        }
+        let representative = self
+            .representative_used_window()
+            .map(|(index, _)| index)
+            .or_else(|| {
+                self.windows
+                    .iter()
+                    .enumerate()
+                    .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
+                    .map(|(index, _)| index)
+            });
+        if let Some(index) = representative {
+            self.windows[index].used_percent = Some(100.0);
+            self.windows[index].limit_reached = true;
+        }
+    }
+
+    fn representative_used_window(&self) -> Option<(usize, f64)> {
        self.windows
            .iter()
+            .enumerate()
            .filter_map(|window| {
+                let (index, window) = window;
                let used_percent = window
                    .used_percent
                    .filter(|value| value.is_finite())
                    .map(|value| value.clamp(0.0, 100.0))?;
-                Some((quota_usage_priority(window), used_percent))
+                Some((index, quota_usage_priority(window), used_percent))
            })
-            .fold(None::<(u8, f64)>, |selected, candidate| match selected {
-                Some(current)
-                    if current.0 < candidate.0
-                        || (current.0 == candidate.0 && current.1 >= candidate.1) =>
-                {
+            .fold(
+                None::<(usize, (u8, u8), f64)>,
+                |selected, candidate| match selected {
                    Some(current)
-                }
-                _ => Some(candidate),
-            })
-            .map(|(_, used_percent)| used_percent)
+                        if current.1 < candidate.1
+                            || (current.1 == candidate.1 && current.2 >= candidate.2) =>
+                    {
+                        Some(current)
+                    }
+                    _ => Some(candidate),
+                },
+            )
+            .map(|(index, _, used_percent)| (index, used_percent))
    }
 }

-fn quota_usage_priority(window: &ProviderQuotaWindow) -> u8 {
-    match window.group.as_str() {
+fn quota_usage_priority(window: &ProviderQuotaWindow) -> (u8, u8) {
+    let attribution = match window.local_usage_attribution {
+        QuotaLocalUsageAttribution::AccountWide => 0,
+        QuotaLocalUsageAttribution::Unavailable => 1,
+    };
+    let duration = match window.group.as_str() {
        "shortTerm" if window.window_seconds.is_some_and(is_week_window) => 1,
        "shortTerm" => 0,
        "monthly" => 2,
        _ => 3,
-    }
+    };
+    (attribution, duration)
 }

 fn is_week_window(seconds: u64) -> bool {
@@ -716,7 +1019,7 @@ impl fmt::Debug for ProviderExport {
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryItem {
    pub account: AccountRecord,
-    pub projection: gateway_core::engine::credential::AccountStatusProjection,
+    pub projection: gateway_core::account::AccountStatusProjection,
    pub usage: Option<super::accounts::AccountUsage>,
    pub quota: ProviderQuota,
 }
@@ -12,7 +12,7 @@ use super::Revision;
 pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;

 /// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
-pub use gateway_core::engine::credential::RotationStrategy;
+pub use gateway_core::account::RotationStrategy;

 /// 完整运行设置事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -24,6 +24,8 @@ pub struct RuntimeSettings {
    pub max_concurrent_per_account: u32,
    pub request_interval_ms: u64,
    pub rotation_strategy: RotationStrategy,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
    pub usage_retention_days: u32,
    pub ops_event_retention_days: u32,
    pub audit_retention_days: u32,
@@ -39,6 +41,8 @@ pub struct ReplaceRuntimeSettings {
    pub max_concurrent_per_account: u32,
    pub request_interval_ms: u64,
    pub rotation_strategy: RotationStrategy,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
    pub usage_retention_days: u32,
    pub ops_event_retention_days: u32,
    pub audit_retention_days: u32,
@@ -145,7 +145,7 @@ pub trait DatabaseDumpPort: Send + Sync {
 #[derive(Debug, Clone)]
 pub struct DumpRequest {
    pub backup_id: String,
-    pub cancellation: gateway_core::engine::CancellationToken,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
 }

 /// 已完成并落盘的归档事实。
@@ -212,7 +212,7 @@ pub struct UploadObjectRequest {
    pub object_key: String,
    pub source: PathBuf,
    pub metadata: BackupObjectMetadata,
-    pub cancellation: gateway_core::engine::CancellationToken,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
 }

 /// 备份控制面所需的全部 Store 能力集合。
@@ -0,0 +1,10 @@
+//! 客户端安装包解析的外部能力端口。
+
+use async_trait::async_trait;
+
+use crate::model::client_distribution::CodexDesktopWindowsDownloads;
+
+#[async_trait]
+pub trait ClientDistributionResolver: Send + Sync {
+    async fn resolve_codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}
@@ -1,6 +1,7 @@
 //! 管理用例依赖的外部能力端口。

 pub mod backup;
+pub mod client_distribution;
 pub mod provider;
 pub mod store;
 pub mod system;
@@ -4,7 +4,7 @@ use std::{collections::BTreeMap, sync::Arc};

 use async_trait::async_trait;
 use gateway_core::{
-    engine::credential::ProviderAccountId,
+    account::ProviderAccountId,
    operation::Operation,
    routing::{ProviderKind, UpstreamModelId},
 };
@@ -13,11 +13,12 @@ use crate::model::observability::{
    CalculatedBillingBreakdown, DashboardWireProfile, ProviderBillingInput,
 };
 use crate::model::provider_credentials::{
-    AuthorizationStarted, CompleteAuthorization, PendingAuthorizationMutation,
-    PrepareCredentialImport, PrepareCredentialRefresh, PrepareCredentialRotation,
-    PreparedAuthorizationCommit, PreparedCredentialImport, PreparedCredentialRotation,
-    ProviderExport, ProviderExportCredentialInput, ProviderModels, ProviderQuota,
-    ProviderQuotaRequest,
+    AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+    PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
+    PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
+    PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput, ProviderModels,
+    ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+    ProviderResetCreditResult, ProviderResetCredits,
 };

 /// Provider 管理失败的稳定分类。
@@ -27,27 +28,59 @@ pub enum ProviderAdminErrorKind {
    Unsupported,
    NotFound,
    Conflict,
+    /// Provider 已发起不可逆操作，但无法确认最终执行结果。
+    Ambiguous,
    Unavailable,
+    CredentialRefreshRequired,
+    BadGateway,
    Internal,
 }

-/// 不泄漏 OAuth material 与 Provider 响应体的管理错误。
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+/// 不携带 OAuth 请求材料的管理错误。
+///
+/// `message` 是 Provider 局部诊断，可能包含原始上游正文；通用管理用例不得自动把它作为公开文案。
+/// 只有明确拥有原始诊断合同的调用方才能读取，`Debug` 始终只记录是否存在。
+#[derive(Clone, PartialEq, Eq, thiserror::Error)]
 #[error("provider admin operation failed: {kind:?}")]
 pub struct ProviderAdminError {
    kind: ProviderAdminErrorKind,
+    message: Option<String>,
+}
+
+impl std::fmt::Debug for ProviderAdminError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("ProviderAdminError")
+            .field("kind", &self.kind)
+            .field("message", &self.message.as_ref().map(|_| "<redacted>"))
+            .finish()
+    }
 }

 impl ProviderAdminError {
    #[must_use]
    pub const fn new(kind: ProviderAdminErrorKind) -> Self {
-        Self { kind }
+        Self {
+            kind,
+            message: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_message(mut self, message: impl Into<String>) -> Self {
+        self.message = Some(message.into());
+        self
    }

    #[must_use]
    pub const fn kind(&self) -> ProviderAdminErrorKind {
        self.kind
    }
+
+    #[must_use]
+    pub fn message(&self) -> Option<&str> {
+        self.message.as_deref()
+    }
 }

 /// 一个具体 Provider 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力。
@@ -116,6 +149,38 @@ pub trait ProviderAdmin: Send + Sync {
        request: ProviderQuotaRequest,
    ) -> Result<ProviderQuota, ProviderAdminError>;

+    /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 打开 Provider 官方头像字节流；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 查询 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn reset_credits(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderResetCredits, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 消费 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn consume_reset_credit(
+        &self,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
    async fn models(
        &self,
        account_id: &ProviderAccountId,
@@ -6,18 +6,19 @@ use std::sync::Arc;

 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
+use futures::stream::BoxStream;

 use super::backup::BackupStorePorts;
 use crate::model::{
    MutationContext, Revision,
    account_groups::{
-        AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, DeleteAccountGroup,
-        NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+        AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+        DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
    },
    accounts::{
-        AccountListQuery, AccountPage, AccountPageItem, AccountUpdateResult, AccountUsage,
-        AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
-        BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
+        AccountListQuery, AccountPage, AccountPageItem, AccountRuntimeSnapshot,
+        AccountUpdateResult, AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult,
+        AccountsUpdateResult, BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
    },
    auth::{AdminAuditEvent, AdminSession},
    client_keys::{
@@ -86,9 +87,17 @@ pub type AdminStoreResult<T> = Result<T, AdminStoreError>;
 /// 账号目录与公共账号写操作。
 #[async_trait]
 pub trait AccountStore: Send + Sync {
-    async fn list_accounts(&self, query: AccountListQuery) -> AdminStoreResult<AccountPage>;
+    async fn list_accounts(
+        &self,
+        query: AccountListQuery,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage>;

-    async fn load_account(&self, account_id: &str) -> AdminStoreResult<Option<AccountPageItem>>;
+    async fn load_account(
+        &self,
+        account_id: &str,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<Option<AccountPageItem>>;

    async fn load_account_usage(
        &self,
@@ -110,13 +119,13 @@ pub trait AccountStore: Send + Sync {
    async fn credential_details(
        &self,
        provider_kind: &gateway_core::routing::ProviderKind,
-        account_id: &gateway_core::engine::credential::ProviderAccountId,
+        account_id: &gateway_core::account::ProviderAccountId,
    ) -> AdminStoreResult<Option<CredentialDetails>>;

    async fn load_credentials_for_export(
        &self,
        provider_kind: &gateway_core::routing::ProviderKind,
-        account_ids: &[gateway_core::engine::credential::ProviderAccountId],
+        account_ids: &[gateway_core::account::ProviderAccountId],
    ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>>;

    async fn commit_credential_import(
@@ -151,7 +160,7 @@ pub trait AccountStore: Send + Sync {

    async fn recover_account(
        &self,
-        account_id: &gateway_core::engine::credential::ProviderAccountId,
+        account_id: &gateway_core::account::ProviderAccountId,
        context: &MutationContext,
    ) -> AdminStoreResult<AccountUpdateResult>;

@@ -169,11 +178,22 @@ pub trait AccountStore: Send + Sync {

    async fn record_credential_export(
        &self,
-        account_ids: &[gateway_core::engine::credential::ProviderAccountId],
+        account_ids: &[gateway_core::account::ProviderAccountId],
        context: &MutationContext,
    ) -> AdminStoreResult<()>;
 }

+/// 可丢失账号运行态的管理读端口；跨存储编排由 Admin application service 拥有。
+#[async_trait]
+pub trait AccountRuntimeStore: Send + Sync {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot>;
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot>;
+}
+
 /// 管理员密码、会话和安全审计。
 #[async_trait]
 pub trait AuthStore: Send + Sync {
@@ -240,6 +260,11 @@ pub trait AccountGroupStore: Send + Sync {
        query: AccountGroupListQuery,
    ) -> AdminStoreResult<AccountGroupPage>;

+    async fn load_account_group_members(
+        &self,
+        group_ids: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>>;
+
    async fn create_account_group(
        &self,
        command: NewAccountGroup,
@@ -265,6 +290,10 @@ pub trait AccountGroupStore: Send + Sync {
    ) -> AdminStoreResult<AccountGroupMutation>;
 }

+/// 逐条读取的已计算费用事实；消费结束或丢弃时释放查询资源。
+pub type UsageCalculatedBillingStream<'a> =
+    BoxStream<'a, AdminStoreResult<UsageCalculatedBillingFact>>;
+
 /// 用量、趋势、诊断与运维错误的只读能力。
 #[async_trait]
 pub trait ObservabilityStore: Send + Sync {
@@ -294,12 +323,13 @@ pub trait ObservabilityStore: Send + Sync {
        filter: UsageFilter,
    ) -> AdminStoreResult<Vec<RequestMetricPoint>>;

-    /// 返回可由 Provider 重新校验的已计算费用事实，用于恢复标准费用趋势。
-    async fn usage_calculated_billing_facts(
+    /// 流式返回可由 Provider 重新校验的已计算费用事实，不保证顺序。
+    /// 查询及解码错误由流返回；调用方应逐条聚合，避免收集整个区间。
+    fn usage_calculated_billing_facts(
        &self,
        range: TimeRange,
        filter: UsageFilter,
-    ) -> AdminStoreResult<Vec<UsageCalculatedBillingFact>>;
+    ) -> UsageCalculatedBillingStream<'_>;

    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage>;

@@ -346,13 +376,35 @@ pub trait SettingsStore: Send + Sync {
    ) -> AdminStoreResult<AdminApiKeyMutation>;
 }

+/// 账号目录、运行态与分组所需的 Store 能力集合。
+#[derive(Clone)]
+pub struct AdminAccountStorePorts {
+    accounts: Arc<dyn AccountStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
+    groups: Arc<dyn AccountGroupStore>,
+}
+
+impl AdminAccountStorePorts {
+    #[must_use]
+    pub fn new(
+        accounts: Arc<dyn AccountStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
+        groups: Arc<dyn AccountGroupStore>,
+    ) -> Self {
+        Self {
+            accounts,
+            runtime,
+            groups,
+        }
+    }
+}
+
 /// 管理用例所需能力的封闭集合。
 ///
 /// 字段保持私有，每个 getter 只交出一种明确能力。该类型不提供通用拆包入口。
 #[derive(Clone)]
 pub struct AdminStorePorts {
-    accounts: Arc<dyn AccountStore>,
-    account_groups: Arc<dyn AccountGroupStore>,
+    accounts: AdminAccountStorePorts,
    auth: Arc<dyn AuthStore>,
    client_keys: Arc<dyn ClientKeyStore>,
    observability: Arc<dyn ObservabilityStore>,
@@ -363,8 +415,7 @@ pub struct AdminStorePorts {
 impl AdminStorePorts {
    #[must_use]
    pub fn new(
-        accounts: Arc<dyn AccountStore>,
-        account_groups: Arc<dyn AccountGroupStore>,
+        accounts: AdminAccountStorePorts,
        auth: Arc<dyn AuthStore>,
        client_keys: Arc<dyn ClientKeyStore>,
        observability: Arc<dyn ObservabilityStore>,
@@ -373,7 +424,6 @@ impl AdminStorePorts {
    ) -> Self {
        Self {
            accounts,
-            account_groups,
            auth,
            client_keys,
            observability,
@@ -384,12 +434,17 @@ impl AdminStorePorts {

    #[must_use]
    pub fn accounts(&self) -> Arc<dyn AccountStore> {
-        self.accounts.clone()
+        self.accounts.accounts.clone()
+    }
+
+    #[must_use]
+    pub fn account_runtime(&self) -> Arc<dyn AccountRuntimeStore> {
+        self.accounts.runtime.clone()
    }

    #[must_use]
    pub fn account_groups(&self) -> Arc<dyn AccountGroupStore> {
-        self.account_groups.clone()
+        self.accounts.groups.clone()
    }

    #[must_use]
@@ -1,20 +1,30 @@
 //! Account group management use cases.

-use std::sync::Arc;
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+    time::SystemTime,
+};

 use async_trait::async_trait;
-use gateway_core::routing::{AccountGroupId, snapshot::SnapshotControl};
+use gateway_core::{
+    account::{AccountStatus, resolve_account_status},
+    routing::AccountGroupId,
+    runtime::SnapshotControl,
+};
 use uuid::Uuid;

 use crate::{
    model::{
        AdminError, MutationContext,
        account_groups::{
-            AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, CreateAccountGroup,
-            DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupListQuery,
+            AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage, AccountGroupRecord,
+            CreateAccountGroup, DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled,
+            UpdateAccountGroup,
        },
    },
-    ports::store::AccountGroupStore,
+    ports::store::{AccountGroupStore, AccountRuntimeStore},
 };

 use super::{map_store_error, publish_committed};
@@ -47,6 +57,7 @@ pub trait AccountGroupService: Send + Sync {

 pub(crate) struct DefaultAccountGroupService {
    store: Arc<dyn AccountGroupStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
    snapshot: Arc<dyn SnapshotControl>,
 }

@@ -54,16 +65,54 @@ impl DefaultAccountGroupService {
    #[must_use]
    pub(crate) fn new(
        store: Arc<dyn AccountGroupStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
        snapshot: Arc<dyn SnapshotControl>,
    ) -> Self {
-        Self { store, snapshot }
+        Self {
+            store,
+            runtime,
+            snapshot,
+        }
+    }
+
+    async fn enrich_records(&self, records: &mut [AccountGroupRecord]) -> Result<(), AdminError> {
+        if records.is_empty() {
+            return Ok(());
+        }
+        let group_ids = records
+            .iter()
+            .map(|record| record.id.clone())
+            .collect::<Vec<_>>();
+        let members = self
+            .store
+            .load_account_group_members(&group_ids)
+            .await
+            .map_err(|error| map_store_error(error, "account group members"))?;
+        let account_ids = members
+            .iter()
+            .map(|member| member.account_id.clone())
+            .collect::<BTreeSet<_>>()
+            .into_iter()
+            .collect::<Vec<_>>();
+        let runtime = match self.runtime.account_runtime(&account_ids).await {
+            Ok(runtime) => runtime,
+            Err(error) => {
+                tracing::warn!(error = %error, "account group runtime projection is unavailable");
+                Default::default()
+            }
+        };
+        project_group_runtime(records, &members, &runtime);
+        Ok(())
    }

    async fn publish(
        &self,
        result: Result<AccountGroupMutation, crate::ports::store::AdminStoreError>,
    ) -> Result<AccountGroupMutation, AdminError> {
-        let result = result.map_err(|error| map_store_error(error, "account group"))?;
+        let mut result = result.map_err(|error| map_store_error(error, "account group"))?;
+        if let Some(record) = result.record.as_mut() {
+            self.enrich_records(std::slice::from_mut(record)).await?;
+        }
        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
        Ok(result)
    }
@@ -72,10 +121,13 @@ impl DefaultAccountGroupService {
 #[async_trait]
 impl AccountGroupService for DefaultAccountGroupService {
    async fn list(&self, query: AccountGroupListQuery) -> Result<AccountGroupPage, AdminError> {
-        self.store
+        let mut page = self
+            .store
            .list_account_groups(query)
            .await
-            .map_err(|error| map_store_error(error, "account group"))
+            .map_err(|error| map_store_error(error, "account group"))?;
+        self.enrich_records(&mut page.items).await?;
+        Ok(page)
    }

    async fn create(
@@ -84,7 +136,7 @@ impl AccountGroupService for DefaultAccountGroupService {
        command: CreateAccountGroup,
    ) -> Result<AccountGroupMutation, AdminError> {
        let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
-            .map_err(|_| AdminError::internal("Failed to create account group ID"))?;
+            .map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
        self.publish(
            self.store
                .create_account_group(
@@ -128,3 +180,63 @@ impl AccountGroupService for DefaultAccountGroupService {
            .await
    }
 }
+
+fn project_group_runtime(
+    records: &mut [AccountGroupRecord],
+    members: &[AccountGroupMemberFact],
+    runtime: &crate::model::accounts::AccountRuntimeSnapshot,
+) {
+    let now = SystemTime::now();
+    let mut status_by_account = BTreeMap::new();
+    let mut slots_by_account = BTreeMap::new();
+    let mut accounts_by_group = BTreeMap::<&str, Vec<&str>>::new();
+    for member in members {
+        let mut status = member.status.clone();
+        status.rate_limited_until = runtime
+            .rate_limited_until
+            .get(&member.account_id)
+            .copied()
+            .map(Into::into);
+        status_by_account
+            .entry(member.account_id.as_str())
+            .or_insert_with(|| resolve_account_status(&status, now).status);
+        slots_by_account
+            .entry(member.account_id.as_str())
+            .or_insert(member.total_slots);
+        accounts_by_group
+            .entry(member.group_id.as_str())
+            .or_default()
+            .push(member.account_id.as_str());
+    }
+    for record in records {
+        let account_ids = accounts_by_group
+            .get(record.id.as_str())
+            .map_or(&[][..], Vec::as_slice);
+        let available_ids = account_ids
+            .iter()
+            .copied()
+            .filter(|account_id| status_by_account.get(account_id) == Some(&AccountStatus::Normal))
+            .collect::<Vec<_>>();
+        let total = u64::try_from(account_ids.len()).unwrap_or(u64::MAX);
+        let available = u64::try_from(available_ids.len()).unwrap_or(u64::MAX);
+        record.account_summary = AccountGroupAccountSummary {
+            available,
+            limited: total.saturating_sub(available),
+            total,
+        };
+        record.capacity = AccountGroupCapacity {
+            used_slots: if available_ids.is_empty() {
+                Some(0)
+            } else {
+                runtime.in_flight.as_ref().map(|in_flight| {
+                    available_ids.iter().fold(0_u64, |sum, account_id| {
+                        sum.saturating_add(in_flight.get(*account_id).copied().unwrap_or(0))
+                    })
+                })
+            },
+            total_slots: available_ids.iter().fold(0_u64, |sum, account_id| {
+                sum.saturating_add(slots_by_account.get(*account_id).copied().unwrap_or(0))
+            }),
+        };
+    }
+}
@@ -6,11 +6,10 @@ use async_trait::async_trait;
 use chrono::{Duration, Utc};
 use futures::StreamExt as _;
 use gateway_core::{
-    engine::{
-        credential::ProviderAccountId,
-        probe::{AccountProbe, AccountProbeRequest},
-    },
-    routing::{ProviderKind, UpstreamModelId, snapshot::SnapshotControl},
+    account::ProviderAccountId,
+    engine::probe::{AccountProbe, AccountProbeRequest},
+    routing::{ProviderKind, UpstreamModelId},
+    runtime::SnapshotControl,
 };

 use crate::{
@@ -24,11 +23,16 @@ use crate::{
        observability::TimeRange,
        provider_credentials::{
            AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
-            PrepareCredentialRefresh, ProviderModels, ProviderQuota, ProviderQuotaRequest,
-            ProviderQuotaWindow, QuotaLocalUsageAttribution,
+            ConsumeProviderResetCredit, PrepareCredentialRefresh, ProviderModels,
+            ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+            ProviderQuotaWindow, ProviderResetCreditResult, ProviderResetCredits,
+            QuotaLocalUsageAttribution,
        },
    },
-    ports::{provider::ProviderAdminRegistry, store::AccountStore},
+    ports::{
+        provider::ProviderAdminRegistry,
+        store::{AccountRuntimeStore, AccountStore},
+    },
 };

 use super::{
@@ -79,6 +83,36 @@ pub trait AccountsService: Send + Sync {
        refresh: bool,
    ) -> Result<AccountDirectoryItem, AdminError>;

+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持账号统计"))
+    }
+
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持账号头像"))
+    }
+
+    async fn reset_credits(
+        &self,
+        _context: &MutationContext,
+        _account_id: ProviderAccountId,
+    ) -> Result<ProviderResetCredits, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持重置额度"))
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        _context: &MutationContext,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持重置额度"))
+    }
+
    async fn models(
        &self,
        account_id: &ProviderAccountId,
@@ -94,36 +128,59 @@ pub trait AccountsService: Send + Sync {

 pub(crate) struct DefaultAccountsService {
    accounts: Arc<dyn AccountStore>,
+    account_runtime: Arc<dyn AccountRuntimeStore>,
    providers: ProviderAdminRegistry,
    snapshot: Arc<dyn SnapshotControl>,
    probe: Arc<dyn AccountProbe>,
+    reset_credit_locks:
+        Arc<futures::lock::Mutex<BTreeMap<ProviderAccountId, Arc<futures::lock::Mutex<()>>>>>,
 }

 impl DefaultAccountsService {
    #[must_use]
-    pub(crate) const fn new(
+    pub(crate) fn new(
        accounts: Arc<dyn AccountStore>,
+        account_runtime: Arc<dyn AccountRuntimeStore>,
        providers: ProviderAdminRegistry,
        snapshot: Arc<dyn SnapshotControl>,
        probe: Arc<dyn AccountProbe>,
    ) -> Self {
        Self {
            accounts,
+            account_runtime,
            providers,
            snapshot,
            probe,
+            reset_credit_locks: Arc::new(futures::lock::Mutex::new(BTreeMap::new())),
        }
    }

+    async fn reset_credit_lock(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Arc<futures::lock::Mutex<()>> {
+        let mut locks = self.reset_credit_locks.lock().await;
+        Arc::clone(
+            locks
+                .entry(account_id.clone())
+                .or_insert_with(|| Arc::new(futures::lock::Mutex::new(()))),
+        )
+    }
+
    async fn load_account(
        &self,
        account_id: &ProviderAccountId,
    ) -> Result<AccountPageItem, AdminError> {
+        let runtime = self
+            .account_runtime
+            .account_runtime(&[account_id.as_str().to_owned()])
+            .await
+            .map_err(|error| map_store_error(error, "account runtime"))?;
        self.accounts
-            .load_account(account_id.as_str())
+            .load_account(account_id.as_str(), runtime)
            .await
            .map_err(|error| map_store_error(error, "provider account"))?
-            .ok_or_else(|| AdminError::not_found("Provider account was not found"))
+            .ok_or_else(|| AdminError::not_found("Provider 账号不存在"))
    }

    async fn provider_for_account(
@@ -212,6 +269,11 @@ impl DefaultAccountsService {
            })
            .await
            .map_err(|error| map_provider_error(error, "provider quota"))?;
+        let stored = if refresh_quota {
+            self.load_account(account_id).await?
+        } else {
+            stored
+        };
        self.attach_quota_local_usage(
            std::slice::from_ref(&stored),
            std::slice::from_mut(&mut quota),
@@ -230,9 +292,14 @@ impl DefaultAccountsService {
 #[async_trait]
 impl AccountsService for DefaultAccountsService {
    async fn list(&self, query: AccountListQuery) -> Result<AccountDirectoryPage, AdminError> {
+        let runtime = self
+            .account_runtime
+            .active_rate_limits()
+            .await
+            .map_err(|error| map_store_error(error, "account runtime"))?;
        let page = self
            .accounts
-            .list_accounts(query)
+            .list_accounts(query, runtime)
            .await
            .map_err(|error| map_store_error(error, "account directory"))?;
        let now = Utc::now();
@@ -257,7 +324,7 @@ impl AccountsService for DefaultAccountsService {
        let mut quotas = futures::future::join_all(page.items.iter().map(|item| async {
            let account = &item.account;
            let account_id = ProviderAccountId::new(account.id.clone())
-                .map_err(|_| AdminError::invalid("Invalid provider account ID"))?;
+                .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
            // 单个账号的 quota 投影失败（Provider 未注册或 quota 读取失败）不拖垮整页：
            // 该账号降级为空额度投影，其余账号与页面状态照常返回。
            let provider = match self.providers.require(&account.provider_kind) {
@@ -323,9 +390,7 @@ impl AccountsService for DefaultAccountsService {
        account_ids: Vec<ProviderAccountId>,
    ) -> Result<AccountExportBundle, AdminError> {
        if account_ids.is_empty() || account_ids.len() > 200 {
-            return Err(AdminError::invalid(
-                "Account export requires between 1 and 200 accounts",
-            ));
+            return Err(AdminError::invalid("账号导出数量必须在 1 到 200 之间"));
        }
        let exported_ids = account_ids.clone();
        let mut grouped = BTreeMap::<ProviderKind, Vec<ProviderAccountId>>::new();
@@ -340,7 +405,7 @@ impl AccountsService for DefaultAccountsService {
            let unique = ids.iter().collect::<std::collections::BTreeSet<_>>();
            unique.len() != ids.len()
        }) {
-            return Err(AdminError::invalid("Account export contains duplicate IDs"));
+            return Err(AdminError::invalid("账号导出列表包含重复 ID"));
        }
        let mut documents = Vec::with_capacity(grouped.len());
        for (provider_kind, ids) in grouped {
@@ -430,7 +495,7 @@ impl AccountsService for DefaultAccountsService {
        command: UpdateAccount,
    ) -> Result<AccountUpdateResult, AdminError> {
        let account_id = ProviderAccountId::new(command.account_id.clone())
-            .map_err(|_| AdminError::invalid("Invalid provider account ID"))?;
+            .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
        let (_, provider) = self.provider_for_account(&account_id).await?;
        let enabled = command.enabled;
        let result = self
@@ -458,7 +523,7 @@ impl AccountsService for DefaultAccountsService {
            .iter()
            .map(|id| {
                ProviderAccountId::new(id.clone())
-                    .map_err(|_| AdminError::invalid("Invalid provider account ID"))
+                    .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))
            })
            .collect::<Result<Vec<_>, _>>()?;
        let mut providers = BTreeMap::<
@@ -502,6 +567,79 @@ impl AccountsService for DefaultAccountsService {
        self.load_directory_item(account_id, refresh).await
    }

+    async fn profile_statistics(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .profile_statistics(account_id)
+            .await
+            .map_err(|error| map_provider_error(error, "provider profile statistics"))
+    }
+
+    async fn profile_avatar(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .profile_avatar(account_id)
+            .await
+            .map_err(|error| map_provider_error(error, "provider profile avatar"))
+    }
+
+    async fn reset_credits(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<ProviderResetCredits, AdminError> {
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        match provider.reset_credits(&account_id).await {
+            Ok(credits) => Ok(credits),
+            Err(error)
+                if error.kind()
+                    == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired =>
+            {
+                self.refresh(context, account_id.clone()).await?;
+                let (_, provider) = self.provider_for_account(&account_id).await?;
+                provider
+                    .reset_credits(&account_id)
+                    .await
+                    .map_err(map_reset_credits_error_after_refresh)
+            }
+            Err(error) => Err(map_provider_error(error, "provider reset credits")),
+        }
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        context: &MutationContext,
+        command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, AdminError> {
+        let account_id = command.account_id.clone();
+        // 覆盖 credential refresh + 同键重试的完整账号级临界区，避免 401 两次调用
+        // 之间插入另一笔不可逆消费。
+        let lock = self.reset_credit_lock(&account_id).await;
+        let _guard = lock.lock().await;
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        match provider.consume_reset_credit(command.clone()).await {
+            Ok(result) => Ok(result),
+            Err(error)
+                if error.kind()
+                    == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired =>
+            {
+                self.refresh(context, account_id.clone()).await?;
+                let (_, provider) = self.provider_for_account(&account_id).await?;
+                provider
+                    .consume_reset_credit(command)
+                    .await
+                    .map_err(map_reset_credits_error_after_refresh)
+            }
+            Err(error) => Err(map_provider_error(error, "provider reset-credit consume")),
+        }
+    }
+
    async fn models(
        &self,
        account_id: &ProviderAccountId,
@@ -565,12 +703,11 @@ impl AccountsService for DefaultAccountsService {
                    let upstream_body = error
                        .upstream_response()
                        .map(|response| String::from_utf8_lossy(response.body()).into_owned());
-                    let message = upstream_body
-                        .as_deref()
-                        .filter(|body| !body.is_empty())
-                        .unwrap_or_else(|| error.client_message())
-                        .to_owned();
+                    let message = error.client_message().to_owned();
                    vec![AccountConnectionTestEvent::Failed {
+                        source: error.source(),
+                        gateway_error_code: error.kind(),
+                        send_state: error.send_state(),
                        message,
                        provider_error_code: error.client_error_code().map(ToOwned::to_owned),
                        provider_error_type: error.client_error_type().map(ToOwned::to_owned),
@@ -586,6 +723,15 @@ impl AccountsService for DefaultAccountsService {
    }
 }

+fn map_reset_credits_error_after_refresh(
+    error: crate::ports::provider::ProviderAdminError,
+) -> AdminError {
+    if error.kind() == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired {
+        return AdminError::bad_gateway("上游服务拒绝了刷新后的凭据");
+    }
+    map_provider_error(error, "provider reset credits")
+}
+
 /// 账号目录中单个账号 quota 读取失败时使用的空额度投影。
 fn empty_quota() -> ProviderQuota {
    ProviderQuota {
@@ -2,7 +2,7 @@

 use std::sync::Arc;

-use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier, password_hash::SaltString};
+use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier};
 use async_trait::async_trait;
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use chrono::{Duration, Utc};
@@ -69,7 +69,7 @@ impl DefaultAuthService {
            id: format!("audit_{}", Uuid::now_v7().simple()),
            actor_kind: AuditActorKind::AdminSession,
            actor_admin_user_id: Some(self.default_admin_user_id.clone()),
-            actor_ref: format!("admin:{}", self.default_admin_user_id),
+            actor_ref: crate::model::auth::admin_session_actor_ref(&self.default_admin_user_id),
            request_id: None,
            action: action.to_owned(),
            entity_kind: "admin_session".to_owned(),
@@ -183,7 +183,7 @@ impl AuthService for DefaultAuthService {
        if let Some(session) = session {
            let mut event = self.auth_audit("admin.logout", Utc::now());
            event.actor_admin_user_id = Some(session.admin_user_id.clone());
-            event.actor_ref = format!("admin:{}", session.admin_user_id);
+            event.actor_ref = crate::model::auth::admin_session_actor_ref(&session.admin_user_id);
            event.entity_ref = session.admin_user_id;
            self.store
                .append_audit_event(event)
@@ -195,16 +195,15 @@ impl AuthService for DefaultAuthService {
 }

 fn hash_admin_password(password: &str) -> Result<String, AdminError> {
-    let salt = SaltString::generate(&mut OsRng);
    Argon2::default()
-        .hash_password(password.as_bytes(), &salt)
+        .hash_password(password.as_bytes())
        .map(|hash| hash.to_string())
-        .map_err(|_| AdminError::internal("Failed to hash administrator password"))
+        .map_err(|_| AdminError::internal("管理员密码哈希失败"))
 }

 fn verify_admin_password(password: &str, encoded: &str) -> Result<bool, AdminError> {
    let hash = PasswordHash::new(encoded)
-        .map_err(|_| AdminError::internal("Stored administrator password hash is invalid"))?;
+        .map_err(|_| AdminError::internal("已保存的管理员密码哈希不合法"))?;
    Ok(Argon2::default()
        .verify_password(password.as_bytes(), &hash)
        .is_ok())
@@ -5,7 +5,7 @@ use std::time::Duration;

 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::runtime::SnapshotControl;
 use secrecy::ExposeSecret as _;
 use uuid::Uuid;

@@ -326,7 +326,9 @@ impl DefaultBackupService {
            crate::model::MutationActor::System => AuditActorKind::System,
        };
        let actor_ref = match &context.actor {
-            crate::model::MutationActor::AdminSession { admin_user_id } => admin_user_id.clone(),
+            crate::model::MutationActor::AdminSession { admin_user_id } => {
+                crate::model::auth::admin_session_actor_ref(admin_user_id)
+            }
            crate::model::MutationActor::AdminApiKey => "admin_api_key".to_owned(),
            crate::model::MutationActor::System => "system".to_owned(),
        };
@@ -429,9 +431,7 @@ fn map_backup_error(error: BackupError) -> AdminError {
        code::ACTIVE_TASK_CONFLICT | code::STATE_CONFLICT | code::STORAGE_IDENTITY_LOCKED => {
            AdminError::conflict(error.message().to_owned())
        }
-        code::STORE_UNAVAILABLE => {
-            AdminError::new(AdminErrorKind::Unavailable, error.message().to_owned())
-        }
-        _ => AdminError::bad_gateway(error.message().to_owned()),
+        code::STORE_UNAVAILABLE => AdminError::new(AdminErrorKind::Unavailable, "备份服务暂不可用"),
+        _ => AdminError::bad_gateway("备份服务请求失败"),
    }
 }
@@ -0,0 +1,33 @@
+//! Codex 客户端下载信息用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::{
+    model::client_distribution::CodexDesktopWindowsDownloads,
+    ports::client_distribution::ClientDistributionResolver,
+};
+
+#[async_trait]
+pub trait ClientDistributionService: Send + Sync {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}
+
+pub(crate) struct DefaultClientDistributionService {
+    resolver: Arc<dyn ClientDistributionResolver>,
+}
+
+impl DefaultClientDistributionService {
+    #[must_use]
+    pub(crate) const fn new(resolver: Arc<dyn ClientDistributionResolver>) -> Self {
+        Self { resolver }
+    }
+}
+
+#[async_trait]
+impl ClientDistributionService for DefaultClientDistributionService {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads {
+        self.resolver.resolve_codex_desktop_windows(refresh).await
+    }
+}
@@ -5,7 +5,7 @@ use std::sync::Arc;
 use async_trait::async_trait;
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use gateway_core::policy::ClientApiKeyId;
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::runtime::SnapshotControl;
 use rand_core::{OsRng, RngCore as _};
 use uuid::Uuid;

@@ -77,7 +77,7 @@ impl ClientKeyService for DefaultClientKeyService {
            .reveal_client_key(id)
            .await
            .map_err(|error| map_store_error(error, "client API key"))?
-            .ok_or_else(|| AdminError::not_found("Client API key was not found"))
+            .ok_or_else(|| AdminError::not_found("Client API Key 不存在"))
    }

    async fn create(
@@ -86,7 +86,7 @@ impl ClientKeyService for DefaultClientKeyService {
        command: CreateClientKey,
    ) -> Result<CreatedClientKey, AdminError> {
        let id = ClientApiKeyId::new(format!("key_{}", Uuid::now_v7().simple()))
-            .map_err(|_| AdminError::internal("Failed to create Client API key ID"))?;
+            .map_err(|_| AdminError::internal("创建 Client API Key ID 失败"))?;
        let mut bytes = [0_u8; 32];
        OsRng.fill_bytes(&mut bytes);
        let plaintext = format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes));
@@ -176,7 +176,7 @@ fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
    };
    if cursor.sort != query.sort {
        return Err(AdminError::invalid(
-            "Client API key cursor sort does not match the query",
+            "Client API Key 游标排序与查询条件不一致",
        ));
    }
    let matches = matches!(
@@ -198,6 +198,6 @@ fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
    if matches {
        Ok(())
    } else {
-        Err(AdminError::invalid("Invalid Client API key cursor"))
+        Err(AdminError::invalid("Client API Key 游标不合法"))
    }
 }
@@ -4,6 +4,7 @@ pub mod account_groups;
 pub mod accounts;
 pub mod auth;
 pub mod backup;
+pub mod client_distribution;
 pub mod client_keys;
 pub mod observability;
 pub mod openai;
@@ -29,8 +30,9 @@ use crate::{
    },
 };
 use gateway_core::{
-    engine::credential::ProviderAccountId,
-    routing::{ConfigRevision, ProviderKind, snapshot::SnapshotControl},
+    account::ProviderAccountId,
+    routing::{ConfigRevision, ProviderKind},
+    runtime::SnapshotControl,
 };

 fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError {
@@ -42,7 +44,15 @@ fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError
        }
        AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
    };
-    AdminError::new(kind, format!("{resource} operation failed"))
+    tracing::warn!(resource, error_kind = ?error.kind(), "admin store operation failed");
+    let message = match kind {
+        AdminErrorKind::Invalid => "请求参数不合法",
+        AdminErrorKind::NotFound => "请求的资源不存在",
+        AdminErrorKind::Conflict => "当前资源状态冲突，请刷新后重试",
+        AdminErrorKind::Unavailable => "依赖服务暂不可用",
+        _ => "服务内部错误",
+    };
+    AdminError::new(kind, message)
 }

 fn map_provider_error(
@@ -56,10 +66,24 @@ fn map_provider_error(
        ProviderAdminErrorKind::Unsupported => AdminErrorKind::Invalid,
        ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
        ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
+        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
        ProviderAdminErrorKind::Unavailable => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::CredentialRefreshRequired => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
    };
-    AdminError::new(kind, format!("{resource} operation failed"))
+    tracing::warn!(resource, error_kind = ?error.kind(), "admin provider operation failed");
+    let message = match kind {
+        AdminErrorKind::Invalid => "Provider 请求不合法",
+        AdminErrorKind::NotFound => "Provider 资源不存在",
+        AdminErrorKind::Conflict => "Provider 资源状态冲突，请刷新后重试",
+        AdminErrorKind::BadGateway => "上游服务请求失败",
+        AdminErrorKind::UpstreamResultUnknown => "上游执行结果未知，请刷新状态后再决定是否重试",
+        AdminErrorKind::Unavailable => "Provider 服务暂不可用",
+        AdminErrorKind::Internal => "服务内部错误",
+        _ => "Provider 操作失败",
+    };
+    AdminError::new(kind, message)
 }

 async fn publish_committed(
@@ -67,7 +91,7 @@ async fn publish_committed(
    revision: crate::model::Revision,
 ) -> Result<(), AdminError> {
    let revision = ConfigRevision::new(revision.get())
-        .map_err(|_| AdminError::internal("Committed configuration revision is invalid"))?;
+        .map_err(|_| AdminError::internal("已提交的配置版本不合法"))?;
    snapshot.publish_committed(revision).await;
    Ok(())
 }
@@ -82,7 +106,7 @@ async fn required_credential(
        .credential_details(provider_kind, account_id)
        .await
        .map_err(|error| map_store_error(error, resource))?
-        .ok_or_else(|| AdminError::not_found(format!("{resource} was not found")))
+        .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))
 }

 async fn pending_authorization(
@@ -114,7 +138,7 @@ async fn pending_authorization(
 fn validate_prepared_import(
    provider_kind: &ProviderKind,
    prepared: &PreparedCredentialImport,
-    resource: &'static str,
+    _resource: &'static str,
 ) -> Result<(), AdminError> {
    if prepared.provider_kind != *provider_kind
        || prepared
@@ -122,9 +146,7 @@ fn validate_prepared_import(
            .iter()
            .any(|credential| credential.provider_kind != *provider_kind)
    {
-        return Err(AdminError::conflict(format!(
-            "{resource} prepared facts do not match the requested Provider scope"
-        )));
+        return Err(AdminError::conflict("Provider 准备结果与请求范围不一致"));
    }
    Ok(())
 }
@@ -132,15 +154,13 @@ fn validate_prepared_import(
 fn validate_prepared_rotation(
    account: &crate::model::accounts::AccountRecord,
    prepared: &PreparedCredentialRotation,
-    resource: &'static str,
+    _resource: &'static str,
 ) -> Result<(), AdminError> {
    let facts = prepared.facts();
    if facts.account_id.as_str() != account.id.as_str()
        || facts.provider_kind != account.provider_kind
    {
-        return Err(AdminError::conflict(format!(
-            "{resource} prepared facts do not match the current credential"
-        )));
+        return Err(AdminError::conflict("Provider 准备结果与当前凭据不一致"));
    }
    Ok(())
 }
@@ -154,9 +174,7 @@ async fn validate_authorization_commit(
    if prepared.pending.provider_kind() != provider_kind
        || !prepared.pending.owner_binding().matches_context(context)
    {
-        let validation_error = AdminError::conflict(format!(
-            "{resource} pending authorization binding is invalid"
-        ));
+        let validation_error = AdminError::conflict("OAuth 授权绑定已失效，请重新发起授权");
        if let Err(error) = prepared.abort().await {
            tracing::warn!(
                resource,
@@ -182,9 +200,7 @@ async fn validate_authorization_commit(
        _ => false,
    };
    if !matches_target {
-        let validation_error = AdminError::conflict(format!(
-            "{resource} prepared credential does not match its pending target"
-        ));
+        let validation_error = AdminError::conflict("OAuth 凭据与待提交目标不一致");
        if let Err(error) = prepared.abort().await {
            tracing::warn!(
                resource,
@@ -1,13 +1,16 @@
 //! 观测查询、趋势、费用覆盖与健康阈值规则。

 use std::{
-    collections::{BTreeMap, btree_map::Entry},
+    collections::{BTreeMap, HashMap, btree_map::Entry},
+    str::FromStr,
    sync::Arc,
+    time::{Duration as StdDuration, Instant},
 };

 use async_trait::async_trait;
 use chrono::{DateTime, Duration, Timelike as _, Utc};
-use gateway_core::{engine::credential::ProviderAccountId, routing::ProviderKind};
+use futures::TryStreamExt;
+use gateway_core::{account::ProviderAccountId, routing::ProviderKind};

 use crate::{
    model::{
@@ -27,7 +30,7 @@ use crate::{
    },
    ports::{
        provider::{ProviderAdminErrorKind, ProviderAdminRegistry},
-        store::{ObservabilityStore, SettingsStore},
+        store::{AccountStore, ObservabilityStore, SettingsStore, UsageCalculatedBillingStream},
    },
 };

@@ -38,6 +41,58 @@ const HEALTH_TIMELINE_SLOTS: i64 = 24 * 4;
 const HEALTH_TIMELINE_MIN_SAMPLE_SIZE: u64 = 10;
 const HEALTH_TIMELINE_UNAVAILABLE_FAILURE_THRESHOLD: u64 = 3;
 const HEALTH_TIMELINE_STABLE_RELIABILITY: f64 = 99.0;
+const DASHBOARD_QUERY_BUCKET_SECONDS: i64 = 2;
+const DASHBOARD_QUERY_CACHE_RETENTION: StdDuration = StdDuration::from_secs(2);
+
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+struct DashboardQueryKey {
+    start: DateTime<Utc>,
+    end_bucket: i64,
+}
+
+impl DashboardQueryKey {
+    fn new(range: TimeRange) -> Self {
+        Self {
+            start: range.start,
+            end_bucket: range
+                .end
+                .timestamp()
+                .div_euclid(DASHBOARD_QUERY_BUCKET_SECONDS),
+        }
+    }
+}
+
+struct DashboardQueryEntry {
+    created_at: Instant,
+    result: Arc<tokio::sync::OnceCell<Result<DashboardResult, AdminError>>>,
+}
+
+#[derive(Default)]
+struct DashboardQueryCache {
+    entries: tokio::sync::Mutex<HashMap<DashboardQueryKey, DashboardQueryEntry>>,
+}
+
+impl DashboardQueryCache {
+    async fn result_cell(
+        &self,
+        key: DashboardQueryKey,
+    ) -> Arc<tokio::sync::OnceCell<Result<DashboardResult, AdminError>>> {
+        let now = Instant::now();
+        let mut entries = self.entries.lock().await;
+        entries.retain(|_, entry| {
+            now.duration_since(entry.created_at) < DASHBOARD_QUERY_CACHE_RETENTION
+        });
+        Arc::clone(
+            &entries
+                .entry(key)
+                .or_insert_with(|| DashboardQueryEntry {
+                    created_at: now,
+                    result: Arc::new(tokio::sync::OnceCell::new()),
+                })
+                .result,
+        )
+    }
+}

 /// API 消费的观测控制面服务。
 #[async_trait]
@@ -72,31 +127,32 @@ pub trait ObservabilityService: Send + Sync {

 pub(crate) struct DefaultObservabilityService {
    store: Arc<dyn ObservabilityStore>,
+    accounts: Arc<dyn AccountStore>,
    settings: Arc<dyn SettingsStore>,
    providers: ProviderAdminRegistry,
+    dashboard_queries: DashboardQueryCache,
 }

 impl DefaultObservabilityService {
    #[must_use]
    pub(crate) fn new(
        store: Arc<dyn ObservabilityStore>,
+        accounts: Arc<dyn AccountStore>,
        settings: Arc<dyn SettingsStore>,
        providers: ProviderAdminRegistry,
    ) -> Self {
        Self {
            store,
+            accounts,
            settings,
            providers,
+            dashboard_queries: DashboardQueryCache::default(),
        }
    }
-}

-#[async_trait]
-impl ObservabilityService for DefaultObservabilityService {
-    async fn dashboard_summary(
+    async fn load_dashboard_summary(
        &self,
        range: TimeRange,
-        kind: TrendKind,
    ) -> Result<DashboardResult, AdminError> {
        let observed_at = Utc::now();
        let (mut observation, settings, runtime_slots) = futures::try_join!(
@@ -105,7 +161,7 @@ impl ObservabilityService for DefaultObservabilityService {
            self.store.dashboard_runtime_slots(observed_at),
        )
        .map_err(|error| map_store_error(error, "dashboard"))?;
-        self.enrich_billing(&mut observation.recent_requests);
+        self.enrich_list_billing(&mut observation.recent_requests);
        self.enrich_dashboard_quotas(&mut observation.account_usage)
            .await;
        let today_start = china_day_start(observation.range.end);
@@ -118,11 +174,18 @@ impl ObservabilityService for DefaultObservabilityService {
            observation.totals.cached_tokens,
            observation.totals.input_tokens,
        );
-        let average_first_token_latency_ms = average(
-            observation.requests.first_token_latency_sum_ms,
-            observation.requests.first_token_latency_count,
-        );
-        let trend = trend(kind, observation.trend.clone())?;
+        let (first_token_latency_sum_ms, first_token_latency_count) = observation
+            .trend
+            .iter()
+            .fold((0_u64, 0_u64), |(sum, count), point| {
+                (
+                    sum.saturating_add(point.metrics.first_token_latency_sum_ms),
+                    count.saturating_add(point.metrics.first_token_latency_count),
+                )
+            });
+        let average_first_token_latency_ms =
+            average(first_token_latency_sum_ms, first_token_latency_count);
+        let trend = trend(TrendKind::Usage, observation.trend.clone())?;
        let health_timeline = health_timeline_at(&observation.trend, Utc::now());
        let wire_profiles = self.providers.dashboard_wire_profiles();
        let max_concurrent_per_account = u64::from(settings.max_concurrent_per_account);
@@ -160,6 +223,26 @@ impl ObservabilityService for DefaultObservabilityService {
            wire_profiles,
        })
    }
+}
+
+#[async_trait]
+impl ObservabilityService for DefaultObservabilityService {
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        kind: TrendKind,
+    ) -> Result<DashboardResult, AdminError> {
+        let cell = self
+            .dashboard_queries
+            .result_cell(DashboardQueryKey::new(range))
+            .await;
+        let mut result = cell
+            .get_or_init(|| self.load_dashboard_summary(range))
+            .await
+            .clone()?;
+        result.trend = trend(kind, result.observation.trend.clone())?;
+        Ok(result)
+    }

    async fn dashboard_trend(
        &self,
@@ -180,20 +263,20 @@ impl ObservabilityService for DefaultObservabilityService {
            .list_usage_records(query)
            .await
            .map_err(|error| map_store_error(error, "usage records"))?;
-        self.enrich_billing(&mut page.items);
+        self.enrich_list_billing(&mut page.items);
        Ok(page)
    }

    async fn usage_record_detail(&self, request_id: &str) -> Result<UsageDetail, AdminError> {
        if request_id.trim().is_empty() {
-            return Err(AdminError::invalid("Usage record ID is required"));
+            return Err(AdminError::invalid("用量记录 ID 不能为空"));
        }
        let mut detail = self
            .store
            .usage_record_detail(request_id)
            .await
            .map_err(|error| map_store_error(error, "usage record"))?;
-        self.enrich_billing(std::slice::from_mut(&mut detail.request));
+        self.enrich_detail_billing(std::slice::from_mut(&mut detail.request));
        Ok(detail)
    }

@@ -222,13 +305,21 @@ impl ObservabilityService for DefaultObservabilityService {
        range: TimeRange,
        filter: UsageFilter,
    ) -> Result<UsageInsights, AdminError> {
-        let (overview, trend, billing_facts) = futures::try_join!(
-            self.store.usage_summary(range, filter.clone()),
-            self.store.usage_trend(range, filter.clone()),
-            self.store.usage_calculated_billing_facts(range, filter),
-        )
-        .map_err(|error| map_store_error(error, "usage insights"))?;
-        let standard_costs = recover_standard_costs(&self.providers, billing_facts)?;
+        let aggregates = async {
+            futures::try_join!(
+                self.store.usage_summary(range, filter.clone()),
+                self.store.usage_trend(range, filter.clone()),
+            )
+            .map_err(|error| map_store_error(error, "usage insights"))
+        };
+        let ((overview, trend), standard_costs) = futures::try_join!(
+            aggregates,
+            recover_standard_costs(
+                &self.providers,
+                self.store
+                    .usage_calculated_billing_facts(range, filter.clone()),
+            ),
+        )?;
        build_usage_insights(overview, trend, standard_costs)
    }

@@ -246,26 +337,50 @@ impl ObservabilityService for DefaultObservabilityService {
        let total_requests = items.iter().fold(0_u64, |total, item| {
            total.saturating_add(item.request_count)
        });
-        Ok(DiagnosticsResult {
-            dimension,
-            items: items
-                .into_iter()
-                .map(|item| DiagnosticsItem {
+        let mut items = items
+            .into_iter()
+            .map(|item| {
+                let error_rate = rate_or_zero(item.failure_count, item.request_count);
+                let non_completion_rate =
+                    rate_or_zero(item.non_completion_count, item.request_count);
+                let retry_rate = rate_or_zero(item.retry_count, item.request_count);
+                let impact_score = diagnostic_impact_score(
+                    item.request_count,
+                    total_requests,
+                    error_rate,
+                    non_completion_rate,
+                    retry_rate,
+                    item.first_token_p95_ms,
+                );
+                DiagnosticsItem {
                    key: item.key,
                    name: item.name,
                    request_count: item.request_count,
-                    success_count: item.request_count.saturating_sub(item.failure_count),
+                    success_count: item.success_count,
                    error_count: item.failure_count,
-                    error_rate: rate_or_zero(item.failure_count, item.request_count),
+                    error_rate,
                    request_share: rate_or_zero(item.request_count, total_requests),
                    average_latency_ms: item.average_latency_ms,
                    latency_p95_ms: item.latency_p95_ms,
+                    first_token_p95_ms: item.first_token_p95_ms,
+                    non_completion_count: item.non_completion_count,
+                    non_completion_rate,
+                    retry_count: item.retry_count,
+                    retry_rate,
+                    impact_score,
                    estimated_cost: usd_cost(&item.costs),
                    attempt_count: item.attempt_count,
                    total_tokens: item.total_tokens,
-                })
-                .collect(),
-        })
+                }
+            })
+            .collect::<Vec<_>>();
+        items.sort_by(|left, right| {
+            right
+                .impact_score
+                .total_cmp(&left.impact_score)
+                .then_with(|| right.request_count.cmp(&left.request_count))
+        });
+        Ok(DiagnosticsResult { dimension, items })
    }

    async fn ops_errors(&self, query: OpsErrorQuery) -> Result<OpsErrorPage, AdminError> {
@@ -279,35 +394,40 @@ impl ObservabilityService for DefaultObservabilityService {
 fn build_usage_insights(
    overview: UsageOverview,
    trend: Vec<RequestMetricPoint>,
-    standard_costs: UsageStandardCosts,
+    standard_costs: UsageCostScenarios,
 ) -> Result<UsageInsights, AdminError> {
    let granularity = trend.first().map_or(
        crate::model::observability::Granularity::FifteenMinutes,
        |point| point.granularity,
    );
    if trend.iter().any(|point| point.granularity != granularity) {
-        return Err(AdminError::internal(
-            "Usage insight trend contains mixed granularities",
-        ));
+        return Err(AdminError::internal("用量洞察趋势包含不一致的时间粒度"));
    }

    let requests = &overview.requests;
    let failed_requests = service_failure_count(requests);
    let health_requests = requests.success_count.saturating_add(failed_requests);
    let health = UsageInsightsHealth {
-        total_requests: health_requests,
+        total_requests: requests.request_count,
        success_requests: requests.success_count,
        failed_requests,
        cancelled_requests: requests.cancelled_count,
        incomplete_requests: requests.incomplete_count,
        caller_error_requests: requests.caller_error_count,
        success_rate: rate_or_zero(requests.success_count, health_requests),
+        completion_rate: rate_or_zero(
+            requests
+                .success_count
+                .saturating_add(requests.failure_count),
+            requests.request_count,
+        ),
        points: trend
            .iter()
            .map(|point| {
                let failed_requests = service_failure_count(&point.metrics);
                let health_requests = point.metrics.success_count.saturating_add(failed_requests);
                UsageInsightsHealthPoint {
+                    total_requests: point.metrics.request_count,
                    bucket_start: point.bucket_start,
                    success_requests: point.metrics.success_count,
                    failed_requests,
@@ -327,27 +447,74 @@ fn build_usage_insights(
            requests.first_token_latency_count,
            requests.request_count,
        ),
+        admission_decision_percentiles: requests.admission_decision_percentiles,
+        account_selection_wait_percentiles: requests.account_selection_wait_percentiles,
+        admission_decision_coverage: rate_or_zero(
+            requests.admission_decision_count,
+            requests.request_count,
+        ),
+        account_selection_wait_coverage: rate_or_zero(
+            requests.account_selection_wait_count,
+            requests.request_count,
+        ),
+        output_throughput_p10: requests.output_throughput_p10,
+        output_throughput_p50: requests.output_throughput_p50,
+        output_throughput_p90: requests.output_throughput_p90,
+        capacity_utilization_avg_basis_points: requests.capacity_utilization_avg_basis_points,
+        capacity_utilization_p95_basis_points: requests.capacity_utilization_p95_basis_points,
+        capacity_coverage: rate_or_zero(requests.capacity_sample_count, requests.request_count),
        points: trend
            .iter()
            .map(|point| UsageInsightsPerformancePoint {
                bucket_start: point.bucket_start,
                latency_percentiles: point.metrics.latency_percentiles,
                first_token_latency_percentiles: point.metrics.first_token_latency_percentiles,
+                admission_decision_percentiles: point.metrics.admission_decision_percentiles,
+                account_selection_wait_percentiles: point
+                    .metrics
+                    .account_selection_wait_percentiles,
+                output_throughput_p10: point.metrics.output_throughput_p10,
+                output_throughput_p50: point.metrics.output_throughput_p50,
+                output_throughput_p90: point.metrics.output_throughput_p90,
+                capacity_utilization_avg_basis_points: point
+                    .metrics
+                    .capacity_utilization_avg_basis_points,
+                capacity_utilization_p95_basis_points: point
+                    .metrics
+                    .capacity_utilization_p95_basis_points,
            })
            .collect(),
    };
    let estimated_cost = usd_cost(&overview.attempts.costs);
-    let UsageStandardCosts {
-        total: standard_cost,
-        by_bucket: standard_costs_by_bucket,
+    let UsageCostScenarios {
+        standard:
+            ScenarioCosts {
+                total: standard_cost,
+                by_bucket: standard_costs_by_bucket,
+            },
+        no_cache:
+            ScenarioCosts {
+                total: no_cache_cost,
+                by_bucket: no_cache_costs_by_bucket,
+            },
    } = standard_costs;
+    let cache_savings = amount_difference(no_cache_cost.as_ref(), estimated_cost.as_ref());
+    let tier_premium = amount_difference(estimated_cost.as_ref(), standard_cost.as_ref());
+    let cost_per_request = estimated_cost
+        .as_ref()
+        .and_then(|cost| cost.checked_div_u64(requests.request_count));
+    let cost_per_successful_request = estimated_cost
+        .as_ref()
+        .and_then(|cost| cost.checked_div_u64(requests.success_count));
    let cost = UsageInsightsCost {
-        cost_per_request: estimated_cost
-            .as_ref()
-            .and_then(|cost| cost.checked_div_u64(requests.request_count)),
+        cost_per_request,
        estimated_cost,
        standard_cost,
+        no_cache_cost,
+        cache_savings,
+        tier_premium,
        tokens_per_request: rate_or_zero(requests.total_tokens, requests.request_count),
+        cost_per_successful_request,
        cached_token_rate: rate_or_zero(requests.cached_tokens, requests.input_tokens),
        cache_hit_request_rate: ratio(
            requests.cache_hit_request_count,
@@ -367,6 +534,11 @@ fn build_usage_insights(
                total_tokens: point.metrics.total_tokens,
                estimated_cost: usd_cost(&point.costs),
                standard_cost: standard_costs_by_bucket.get(&point.bucket_start).cloned(),
+                no_cache_cost: no_cache_costs_by_bucket.get(&point.bucket_start).cloned(),
+                cache_savings: amount_difference(
+                    no_cache_costs_by_bucket.get(&point.bucket_start),
+                    usd_cost(&point.costs).as_ref(),
+                ),
                cached_token_rate: rate_or_zero(
                    point.metrics.cached_tokens,
                    point.metrics.input_tokens,
@@ -391,12 +563,12 @@ fn build_usage_insights(
 }

 #[derive(Debug, Default)]
-struct UsageStandardCosts {
+struct ScenarioCosts {
    total: Option<DecimalAmount>,
    by_bucket: BTreeMap<DateTime<Utc>, DecimalAmount>,
 }

-impl UsageStandardCosts {
+impl ScenarioCosts {
    fn add(
        &mut self,
        bucket_start: DateTime<Utc>,
@@ -405,14 +577,15 @@ impl UsageStandardCosts {
        self.total = Some(match self.total.take() {
            Some(current) => current
                .checked_add(&amount)
-                .ok_or_else(|| AdminError::internal("Usage standard cost exceeds decimal range"))?,
+                .ok_or_else(|| AdminError::internal("用量标准成本超出数值范围"))?,
            None => amount.clone(),
        });
        match self.by_bucket.entry(bucket_start) {
            Entry::Occupied(mut entry) => {
-                let sum = entry.get().checked_add(&amount).ok_or_else(|| {
-                    AdminError::internal("Usage standard cost exceeds decimal range")
-                })?;
+                let sum = entry
+                    .get()
+                    .checked_add(&amount)
+                    .ok_or_else(|| AdminError::internal("用量标准成本超出数值范围"))?;
                entry.insert(sum);
            }
            Entry::Vacant(entry) => {
@@ -423,23 +596,33 @@ impl UsageStandardCosts {
    }
 }

-fn recover_standard_costs(
+#[derive(Debug, Default)]
+struct UsageCostScenarios {
+    standard: ScenarioCosts,
+    no_cache: ScenarioCosts,
+}
+
+async fn recover_standard_costs(
    providers: &ProviderAdminRegistry,
-    facts: Vec<UsageCalculatedBillingFact>,
-) -> Result<UsageStandardCosts, AdminError> {
-    let mut standard_costs = UsageStandardCosts::default();
-    for fact in facts {
-        let Ok(provider_kind) = ProviderKind::new(fact.provider_kind) else {
+    mut facts: UsageCalculatedBillingStream<'_>,
+) -> Result<UsageCostScenarios, AdminError> {
+    let mut scenarios = UsageCostScenarios::default();
+    while let Some(fact) = facts
+        .try_next()
+        .await
+        .map_err(|error| map_store_error(error, "usage billing facts"))?
+    {
+        let Ok(provider_kind) = ProviderKind::new(fact.provider_kind.clone()) else {
            continue;
        };
        let input = ProviderBillingInput {
-            upstream_model_id: fact.upstream_model_id,
-            service_tier: fact.service_tier,
+            upstream_model_id: fact.upstream_model_id.clone(),
+            service_tier: fact.service_tier.clone(),
            input_tokens: fact.input_tokens,
            output_tokens: fact.output_tokens,
            cached_tokens: fact.cached_tokens,
            cache_write_tokens: fact.cache_write_tokens,
-            total: fact.total,
+            total: fact.total.clone(),
        };
        let breakdown = match providers.calculated_billing(&provider_kind, &input) {
            Ok(breakdown) => breakdown,
@@ -456,9 +639,80 @@ fn recover_standard_costs(
        {
            continue;
        }
-        standard_costs.add(fact.bucket_start, breakdown.standard_amount.amount)?;
+        scenarios
+            .standard
+            .add(fact.bucket_start, breakdown.standard_amount.amount.clone())?;
+        if let Some(no_cache_cost) = no_cache_cost(&fact, &breakdown) {
+            scenarios.no_cache.add(fact.bucket_start, no_cache_cost)?;
+        }
    }
-    Ok(standard_costs)
+    Ok(scenarios)
+}
+
+fn no_cache_cost(
+    fact: &UsageCalculatedBillingFact,
+    breakdown: &crate::model::observability::CalculatedBillingBreakdown,
+) -> Option<DecimalAmount> {
+    let input_tokens = fact.input_tokens?;
+    let cached_tokens = fact.cached_tokens.unwrap_or_default().min(input_tokens);
+    let cache_write_tokens = fact
+        .cache_write_tokens
+        .unwrap_or_default()
+        .min(input_tokens.saturating_sub(cached_tokens));
+    let input_rate = decimal(&breakdown.input_price_per_million.amount)?;
+    let replaced_input_amount = input_rate
+        .scaled()
+        .checked_mul(u128::from(cached_tokens.saturating_add(cache_write_tokens)))?
+        .checked_div(1_000_000)?;
+    let total = decimal(&breakdown.total_amount.amount)?
+        .scaled()
+        .checked_sub(decimal(&breakdown.cache_read_amount.amount)?.scaled())?
+        .checked_sub(decimal(&breakdown.cache_write_amount.amount)?.scaled())?
+        .checked_add(replaced_input_amount)?;
+    DecimalAmount::from_str(
+        &gateway_core::metering::Decimal::from_scaled(total)
+            .ok()?
+            .canonical(),
+    )
+    .ok()
+}
+
+fn amount_difference(
+    larger: Option<&DecimalAmount>,
+    smaller: Option<&DecimalAmount>,
+) -> Option<DecimalAmount> {
+    let difference = decimal(larger?)?
+        .scaled()
+        .checked_sub(decimal(smaller?)?.scaled())?;
+    DecimalAmount::from_str(
+        &gateway_core::metering::Decimal::from_scaled(difference)
+            .ok()?
+            .canonical(),
+    )
+    .ok()
+}
+
+fn decimal(value: &DecimalAmount) -> Option<gateway_core::metering::Decimal> {
+    value.as_str().parse().ok()
+}
+
+fn diagnostic_impact_score(
+    request_count: u64,
+    total_requests: u64,
+    error_rate: f64,
+    non_completion_rate: f64,
+    retry_rate: f64,
+    first_token_p95_ms: Option<u64>,
+) -> f64 {
+    let request_share = rate_or_zero(request_count, total_requests);
+    let slow_score = first_token_p95_ms
+        .map_or(0.0, |value| value as f64 / 30_000.0)
+        .min(1.0);
+    error_rate * 0.35
+        + non_completion_rate * 0.25
+        + retry_rate.min(1.0) * 0.20
+        + request_share * 0.10
+        + slow_score * 0.10
 }

 fn usd_cost(costs: &[CurrencyCost]) -> Option<DecimalAmount> {
@@ -470,8 +724,31 @@ fn usd_cost(costs: &[CurrencyCost]) -> Option<DecimalAmount> {

 impl DefaultObservabilityService {
    async fn enrich_dashboard_quotas(&self, accounts: &mut [DashboardAccountUsage]) {
+        if accounts.is_empty() {
+            return;
+        }
+        let now = Utc::now();
+        let ids = accounts
+            .iter()
+            .map(|account| account.account_id.clone())
+            .collect::<Vec<_>>();
+        let mut rolling_usage = self
+            .accounts
+            .load_account_usage(
+                TimeRange {
+                    start: now - Duration::hours(24),
+                    end: now,
+                },
+                &ids,
+            )
+            .await
+            .unwrap_or_default()
+            .into_iter()
+            .map(|usage| (usage.account_id.clone(), usage))
+            .collect::<HashMap<_, _>>();
        let providers = self.providers.clone();
        let quota_reads = accounts.iter().map(|account| {
+            let rolling_usage = rolling_usage.remove(&account.account_id);
            let account_id = ProviderAccountId::new(account.account_id.clone()).ok();
            let provider = ProviderKind::new(account.provider_kind.clone())
                .ok()
@@ -484,22 +761,57 @@ impl DefaultObservabilityService {
                    .quota(ProviderQuotaRequest {
                        account_id,
                        refresh: false,
-                        rolling_usage: None,
+                        rolling_usage,
                    })
                    .await
                    .ok()
-                    .and_then(|quota| quota.representative_used_percent())
            }
        });
-        let quota_used = futures::future::join_all(quota_reads).await;
-        for (account, used_percent) in accounts.iter_mut().zip(quota_used) {
-            account.quota_used_percent = used_percent;
+        let quotas = futures::future::join_all(quota_reads).await;
+        for (account, quota) in accounts.iter_mut().zip(quotas) {
+            if let Some(mut quota) = quota {
+                quota.apply_limit_reached_display();
+                account.quota_used_percent = quota.representative_used_percent();
+                account.quota_window = quota.representative_window().cloned();
+            }
        }
    }

    /// 逐条尽力把可校验的总额升级为完整分解；单条脏数据（非法 Provider kind、
    /// 不支持的来源或费用规则失败）只保留该条已存的总额，不影响整页返回。
-    fn enrich_billing(&self, records: &mut [crate::model::observability::UsageRecord]) {
+    fn enrich_list_billing(&self, records: &mut [crate::model::observability::UsageListRecord]) {
+        for record in records {
+            let Some(UsageBilling::Total { source, total }) = record.billing.as_ref() else {
+                continue;
+            };
+            if !matches!(source.as_str(), "calculated" | "provider_reported") {
+                continue;
+            }
+            let (Some(provider), Some(upstream_model_id)) = (
+                record.provider_kind.as_deref(),
+                record.upstream_model_id.as_ref(),
+            ) else {
+                continue;
+            };
+            let Ok(provider_kind) = ProviderKind::new(provider.to_owned()) else {
+                continue;
+            };
+            let input = ProviderBillingInput {
+                upstream_model_id: upstream_model_id.clone(),
+                service_tier: record.service_tier.clone(),
+                input_tokens: record.input_tokens,
+                output_tokens: record.output_tokens,
+                cached_tokens: record.cached_tokens,
+                cache_write_tokens: record.cache_write_tokens,
+                total: total.clone(),
+            };
+            if let Ok(Some(breakdown)) = self.providers.calculated_billing(&provider_kind, &input) {
+                record.billing = Some(UsageBilling::Calculated(Box::new(breakdown)));
+            }
+        }
+    }
+
+    fn enrich_detail_billing(&self, records: &mut [crate::model::observability::UsageRecord]) {
        for record in records {
            let Some(UsageBilling::Total { source, total }) = record.billing.as_ref() else {
                continue;
@@ -612,9 +924,9 @@ fn trend(kind: TrendKind, points: Vec<RequestMetricPoint>) -> Result<Trend, Admi
            .saturating_add(point.cost_coverage.not_billable_count);
        for cost in &point.costs {
            if let Some(amount) = costs.get_mut(&cost.currency) {
-                *amount = amount.checked_add(&cost.amount).ok_or_else(|| {
-                    AdminError::internal("Cost aggregation exceeded numeric bounds")
-                })?;
+                *amount = amount
+                    .checked_add(&cost.amount)
+                    .ok_or_else(|| AdminError::internal("成本聚合结果超出数值范围"))?;
            } else {
                costs.insert(cost.currency.clone(), cost.amount.clone());
            }
@@ -630,6 +942,20 @@ fn trend(kind: TrendKind, points: Vec<RequestMetricPoint>) -> Result<Trend, Admi
        metrics.cache_hit_request_count,
        metrics.cache_eligible_request_count,
    );
+    let peak_first_token_p95_ms = points
+        .iter()
+        .filter_map(|point| point.metrics.first_token_latency_percentiles.p95_ms)
+        .map(|value| value.as_f64())
+        .reduce(f64::max);
+    let peak_latency_p95_ms = points
+        .iter()
+        .filter_map(|point| point.metrics.latency_percentiles.p95_ms)
+        .map(|value| value.as_f64())
+        .reduce(f64::max);
+    let minimum_output_throughput_p50 = points
+        .iter()
+        .filter_map(|point| point.metrics.output_throughput_p50)
+        .min();
    Ok(Trend {
        kind,
        points: points.into_iter().map(trend_point).collect(),
@@ -643,6 +969,9 @@ fn trend(kind: TrendKind, points: Vec<RequestMetricPoint>) -> Result<Trend, Admi
            average_latency_ms,
            max_latency_ms: metrics.max_latency_ms,
            min_latency_ms: metrics.min_latency_ms,
+            peak_first_token_p95_ms,
+            peak_latency_p95_ms,
+            minimum_output_throughput_p50,
            success_rate,
            cache_hit_request_rate,
            costs: costs
@@ -3,7 +3,7 @@
 use std::sync::Arc;

 use async_trait::async_trait;
-use gateway_core::{engine::credential::ProviderAccountId, routing::snapshot::SnapshotControl};
+use gateway_core::{account::ProviderAccountId, runtime::SnapshotControl};

 use crate::{
    model::{
@@ -3,7 +3,8 @@
 use std::sync::Arc;

 use async_trait::async_trait;
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::policy::CodexClientVersion;
+use gateway_core::runtime::SnapshotControl;
 use rand_core::{OsRng, RngCore as _};

 use crate::{
@@ -119,10 +120,16 @@ fn validate_settings(command: &ReplaceRuntimeSettings) -> Result<(), AdminError>
        && command.usage_retention_days >= 31
        && command.ops_event_retention_days > 0
        && command.audit_retention_days > 0
+        && valid_client_version(command.min_codex_desktop_version.as_deref())
+        && valid_client_version(command.min_codex_cli_version.as_deref())
        && i64::try_from(command.request_interval_ms).is_ok();
    if valid {
        Ok(())
    } else {
-        Err(AdminError::invalid("Runtime settings violate constraints"))
+        Err(AdminError::invalid("运行时设置不满足约束"))
    }
 }
+
+fn valid_client_version(value: Option<&str>) -> bool {
+    value.is_none_or(|value| CodexClientVersion::parse(value).is_ok())
+}
@@ -94,5 +94,12 @@ fn map_system_error(error: SystemOperationError) -> AdminError {
        SystemOperationErrorKind::Upstream => AdminErrorKind::BadGateway,
        SystemOperationErrorKind::Internal => AdminErrorKind::Internal,
    };
-    AdminError::new(kind, error.message())
+    let message = match kind {
+        AdminErrorKind::Invalid => "系统操作请求不合法",
+        AdminErrorKind::Conflict => "系统当前状态不允许执行该操作",
+        AdminErrorKind::BadGateway => "系统更新服务请求失败",
+        AdminErrorKind::Internal => "系统操作失败",
+        _ => "系统操作失败",
+    };
+    AdminError::new(kind, message)
 }
@@ -3,7 +3,7 @@
 use std::sync::Arc;

 use async_trait::async_trait;
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::runtime::SnapshotControl;

 use crate::{
    model::{
@@ -10,7 +10,7 @@ use gateway_admin::{
    },
    ports::backup::{BackupRepository, DatabaseDumpPort, DumpRequest},
 };
-use gateway_core::engine::CancellationToken;
+use gateway_core::lifecycle::CancellationToken;

 use super::support::{
    DUMP_CONTENT, FakeBackupRepository, FakeDumpPort, FakeObjectStore, backup_id,
@@ -1,11 +1,12 @@
 use std::str::FromStr as _;

 use chrono::{TimeDelta, Utc};
-use gateway_core::engine::credential::OpaqueProviderData;
+use gateway_core::account::OpaqueProviderData;

 use gateway_admin::{
    model::{
        PageSize, Revision,
+        accounts::AccountUsage,
        auth::LoginCommand,
        client_keys::ClientKeyPageSize,
        observability::{DecimalAmount, RequestOutcome, TimeRange},
@@ -135,6 +136,115 @@ fn representative_quota_should_prefer_short_window_and_highest_usage() {
    assert_eq!(quota.representative_used_percent(), Some(45.0));
 }

+#[test]
+fn representative_quota_should_prefer_account_wide_window_over_model_specific_window() {
+    let mut model_specific = quota_window("shortTerm", Some(18_000), Some(64.0));
+    model_specific.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    let quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            model_specific,
+            quota_window("shortTerm", Some(604_800), Some(5.0)),
+        ],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(5.0));
+}
+
+#[test]
+fn representative_window_usage_should_accept_account_wide_rolling_window_without_reset() {
+    let usage = AccountUsage {
+        account_id: "acct_xai".to_owned(),
+        request_count: 5,
+        success_count: 5,
+        input_tokens: Some(100),
+        output_tokens: Some(20),
+        cached_tokens: Some(80),
+        cache_write_tokens: Some(0),
+        reasoning_tokens: Some(0),
+        image_input_tokens: Some(0),
+        image_output_tokens: Some(0),
+        image_request_count: 0,
+        image_request_failed_count: 0,
+        total_tokens: Some(120),
+        cost_coverage: Default::default(),
+        costs: Vec::new(),
+        last_used_at: Some(Utc::now()),
+        request_buckets: Vec::new(),
+        models: Vec::new(),
+    };
+    let quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![ProviderQuotaWindow {
+            key: "free-rolling-24h".to_owned(),
+            group: "shortTerm".to_owned(),
+            label: "日限额".to_owned(),
+            limit_id: None,
+            limit_name: None,
+            role: None,
+            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+            window_seconds: Some(86_400),
+            used_percent: None,
+            reset_at: None,
+            limit_reached: false,
+            local_usage: Some(usage.clone()),
+            provider_data: None,
+        }],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_window_usage(), Some(&usage));
+}
+
+#[test]
+fn exhausted_quota_should_project_full_usage_to_only_the_representative_window() {
+    let mut quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            quota_window("monthly", Some(2_592_000), Some(99.0)),
+            quota_window("shortTerm", Some(604_800), Some(80.0)),
+            quota_window("shortTerm", Some(18_000), Some(30.0)),
+            quota_window("shortTerm", Some(14_400), Some(95.0)),
+        ],
+        limit_reached: true,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(100.0));
+    quota.apply_limit_reached_display();
+
+    assert_eq!(quota.windows[0].used_percent, Some(99.0));
+    assert_eq!(quota.windows[1].used_percent, Some(80.0));
+    assert_eq!(quota.windows[2].used_percent, Some(30.0));
+    assert_eq!(quota.windows[3].used_percent, Some(100.0));
+    assert!(quota.windows[3].limit_reached);
+}
+
+#[test]
+fn exhausted_quota_should_preserve_the_provider_identified_reached_window() {
+    let mut reached = quota_window("monthly", Some(2_592_000), Some(98.0));
+    reached.limit_reached = true;
+    let mut quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![reached, quota_window("shortTerm", Some(18_000), Some(95.0))],
+        limit_reached: true,
+        provider_data: None,
+    };
+
+    quota.apply_limit_reached_display();
+
+    assert_eq!(quota.windows[0].used_percent, Some(100.0));
+    assert_eq!(quota.windows[1].used_percent, Some(95.0));
+    assert!(!quota.windows[1].limit_reached);
+}
+
 fn quota_window(
    group: &str,
    window_seconds: Option<u64>,
@@ -144,7 +254,9 @@ fn quota_window(
        key: group.to_owned(),
        group: group.to_owned(),
        label: group.to_owned(),
-        source: None,
+        limit_id: None,
+        limit_name: None,
+        role: None,
        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
        window_seconds,
        used_percent,
@@ -1,4 +1,4 @@
-//! 备份领域模型（model/backup.rs）的纯逻辑测试。
+//! 备份领域模型（model/backup）的纯逻辑测试。

 use chrono::{TimeZone as _, Utc};
 use secrecy::SecretString;
@@ -1,3 +1,4 @@
 //! 模型模块测试：镜像 src/model/ 中带逻辑的模块。

 mod backup;
+mod provider_credentials;
@@ -0,0 +1,134 @@
+use gateway_admin::model::provider_credentials::{
+    AuthorizationMutationTarget, AuthorizationOwnerBinding, PendingAuthorizationMutation,
+    ProviderQuota, ProviderQuotaWindow, ProviderQuotaWindowRole, QuotaLocalUsageAttribution,
+};
+use gateway_admin::model::{MutationActor, MutationContext};
+use gateway_core::account::ProviderAccountId;
+use gateway_core::routing::ProviderKind;
+use serde_json::{Value, json};
+
+#[test]
+fn dashboard_quota_should_preserve_unknown_and_actual_window_facts() {
+    let mut quota = ProviderQuota {
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: Vec::new(),
+        limit_reached: false,
+        provider_data: None,
+    };
+    assert!(quota.representative_window().is_none());
+    assert!(quota.representative_used_percent().is_none());
+
+    let rolling = ProviderQuotaWindow {
+        key: "provider_rolling".to_owned(),
+        group: "requests".to_owned(),
+        label: "Provider rolling window".to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: Some(ProviderQuotaWindowRole::Primary),
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(86_400),
+        used_percent: None,
+        reset_at: None,
+        limit_reached: false,
+        local_usage: None,
+        provider_data: None,
+    };
+    quota.windows.push(rolling.clone());
+    assert_eq!(quota.representative_window(), Some(&rolling));
+    assert!(quota.representative_used_percent().is_none());
+
+    quota.windows[0].used_percent = Some(99.6);
+    quota.apply_limit_reached_display();
+    let actual = quota.representative_window().expect("actual window");
+    assert_eq!(actual.used_percent, Some(99.6));
+    assert!(
+        !actual.limit_reached,
+        "display rounding cannot exhaust quota"
+    );
+    assert_eq!(actual.window_seconds, Some(86_400));
+    assert_eq!(actual.reset_at, None);
+
+    quota.windows.insert(
+        0,
+        ProviderQuotaWindow {
+            key: "model_specific".to_owned(),
+            used_percent: Some(100.0),
+            local_usage_attribution: QuotaLocalUsageAttribution::Unavailable,
+            ..rolling
+        },
+    );
+    assert_eq!(
+        quota
+            .representative_window()
+            .map(|window| window.key.as_str()),
+        Some("provider_rolling")
+    );
+}
+
+#[test]
+fn pending_mutation_v1_should_round_trip_all_targets_and_owners() {
+    for provider in ["openai", "xai"] {
+        for target in [
+            AuthorizationMutationTarget::Create {
+                name: "account".to_owned(),
+            },
+            AuthorizationMutationTarget::Reauthorize {
+                account_id: ProviderAccountId::new("acct_1").expect("account id"),
+            },
+        ] {
+            for actor in [
+                MutationActor::AdminSession {
+                    admin_user_id: "admin-1".to_owned(),
+                },
+                MutationActor::AdminApiKey,
+                MutationActor::System,
+            ] {
+                let expected = PendingAuthorizationMutation::new(
+                    ProviderKind::new(provider).expect("provider"),
+                    target.clone(),
+                    AuthorizationOwnerBinding::from_context(&MutationContext {
+                        actor,
+                        request_id: "request-1".to_owned(),
+                    }),
+                );
+                assert_eq!(
+                    PendingAuthorizationMutation::from_storage_v1(Value::Object(
+                        expected.to_storage_v1()
+                    )),
+                    Ok(expected),
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn pending_mutation_v1_should_keep_existing_storage_fields_and_reject_invalid_documents() {
+    let legacy = json!({
+        "provider_kind": "openai",
+        "target": { "kind": "reauthorize", "account_id": "acct_1" },
+        "owner": { "kind": "admin_session", "admin_user_id": "admin-1" },
+        "started_request_id": "request-1"
+    });
+    let restored =
+        PendingAuthorizationMutation::from_storage_v1(legacy.clone()).expect("v1 document");
+    assert_eq!(Value::Object(restored.to_storage_v1()), legacy);
+    for (pointer, invalid) in [
+        ("/provider_kind", json!("")),
+        ("/target/account_id", json!("")),
+        ("/target/kind", json!("other")),
+        ("/owner/kind", json!("other")),
+        ("/started_request_id", json!(null)),
+    ] {
+        let mut document = legacy.clone();
+        *document.pointer_mut(pointer).expect("field") = invalid;
+        assert!(
+            PendingAuthorizationMutation::from_storage_v1(document).is_err(),
+            "{pointer}"
+        );
+    }
+    let mut document = legacy;
+    document["schema_version"] = json!(2);
+    assert!(PendingAuthorizationMutation::from_storage_v1(document).is_err());
+}
@@ -0,0 +1,236 @@
+use std::{
+    collections::BTreeMap,
+    str::FromStr as _,
+    sync::{Arc, Mutex},
+};
+
+use async_trait::async_trait;
+use chrono::{Duration, Utc};
+use gateway_admin::{
+    model::{
+        MutationContext, PageSize, Revision,
+        account_groups::{
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupColor,
+            AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+            AccountGroupRecord, AccountGroupUsage, DeleteAccountGroup, NewAccountGroup,
+            SetAccountGroupEnabled, UpdateAccountGroup,
+        },
+        accounts::AccountRuntimeSnapshot,
+        observability::DecimalAmount,
+    },
+    ports::store::{
+        AccountGroupStore, AccountRuntimeStore, AdminStoreError, AdminStoreErrorKind,
+        AdminStoreResult,
+    },
+};
+use gateway_core::{
+    account::{AccountStatusFacts, CredentialState, QuotaState},
+    routing::AccountGroupId,
+};
+
+use super::AdminHarness;
+
+const GROUP_ID: &str = "grp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+#[tokio::test]
+async fn group_query_service_enriches_only_current_page_members_with_runtime_facts() {
+    let groups = Arc::new(FakeGroupStore::default());
+    let runtime = Arc::new(FakeRuntimeStore::default());
+    let service = AdminHarness::new()
+        .account_groups(groups.clone())
+        .account_runtime(runtime.clone())
+        .build()
+        .await;
+
+    let page = service
+        .account_groups()
+        .list(AccountGroupListQuery {
+            page: 1,
+            page_size: PageSize::new(20).expect("page size"),
+            search: None,
+            enabled: None,
+        })
+        .await
+        .expect("list projected account groups");
+
+    assert_eq!(
+        groups
+            .requested_groups
+            .lock()
+            .expect("requested groups")
+            .as_slice(),
+        [GROUP_ID]
+    );
+    assert_eq!(
+        runtime
+            .requested_accounts
+            .lock()
+            .expect("requested accounts")
+            .as_slice(),
+        ["acct_available", "acct_limited"]
+    );
+    let group = &page.items[0];
+    assert_eq!(
+        group.account_summary,
+        AccountGroupAccountSummary {
+            available: 1,
+            limited: 1,
+            total: 2,
+        }
+    );
+    assert_eq!(
+        group.capacity,
+        AccountGroupCapacity {
+            used_slots: Some(2),
+            total_slots: 4,
+        }
+    );
+}
+
+#[derive(Default)]
+struct FakeGroupStore {
+    requested_groups: Mutex<Vec<String>>,
+}
+
+#[async_trait]
+impl AccountGroupStore for FakeGroupStore {
+    async fn list_account_groups(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage> {
+        Ok(AccountGroupPage {
+            config_revision: Revision::new(1).expect("revision"),
+            items: vec![group_record()],
+            total: 1,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+
+    async fn load_account_group_members(
+        &self,
+        group_ids: &[AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>> {
+        *self.requested_groups.lock().expect("requested groups") = group_ids
+            .iter()
+            .map(|group_id| group_id.as_str().to_owned())
+            .collect();
+        Ok(vec![member("acct_available", 4), member("acct_limited", 3)])
+    }
+
+    async fn create_account_group(
+        &self,
+        _: NewAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn update_account_group(
+        &self,
+        _: UpdateAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn set_account_group_enabled(
+        &self,
+        _: SetAccountGroupEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn delete_account_group(
+        &self,
+        _: DeleteAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+}
+
+#[derive(Default)]
+struct FakeRuntimeStore {
+    requested_accounts: Mutex<Vec<String>>,
+}
+
+#[async_trait]
+impl AccountRuntimeStore for FakeRuntimeStore {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        *self.requested_accounts.lock().expect("requested accounts") = account_ids.to_vec();
+        Ok(AccountRuntimeSnapshot {
+            rate_limited_until: BTreeMap::from([(
+                "acct_limited".to_owned(),
+                Utc::now() + Duration::minutes(5),
+            )]),
+            in_flight: Some(BTreeMap::from([("acct_available".to_owned(), 2)])),
+        })
+    }
+}
+
+fn group_record() -> AccountGroupRecord {
+    let now = Utc::now();
+    AccountGroupRecord {
+        id: group_id(),
+        name: "Primary".to_owned(),
+        description: None,
+        color: AccountGroupColor::parse("#2563EBFF").expect("color"),
+        enabled: true,
+        member_count: 2,
+        provider_counts: BTreeMap::from([("openai".to_owned(), 2)]),
+        client_key_count: 1,
+        account_summary: AccountGroupAccountSummary {
+            available: 0,
+            limited: 0,
+            total: 0,
+        },
+        capacity: AccountGroupCapacity {
+            used_slots: None,
+            total_slots: 0,
+        },
+        usage: AccountGroupUsage {
+            today_usd: DecimalAmount::from_str("1").expect("today usage"),
+            retained_total_usd: DecimalAmount::from_str("3").expect("retained usage"),
+        },
+        created_at: now,
+        updated_at: now,
+    }
+}
+
+fn member(account_id: &str, total_slots: u64) -> AccountGroupMemberFact {
+    AccountGroupMemberFact {
+        group_id: group_id(),
+        account_id: account_id.to_owned(),
+        status: AccountStatusFacts {
+            enabled: true,
+            credential_state: CredentialState::Ready,
+            access_token_expires_at: None,
+            quota: QuotaState::default(),
+            rate_limited_until: None,
+            last_error_reason: None,
+            last_error_message: None,
+        },
+        total_slots,
+    }
+}
+
+fn group_id() -> AccountGroupId {
+    AccountGroupId::new(GROUP_ID).expect("group ID")
+}
+
+fn unused() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "account group",
+        "unused test operation",
+    )
+}
@@ -4,16 +4,18 @@ use async_trait::async_trait;
 use chrono::{TimeDelta, Utc};
 use futures::{StreamExt as _, future::BoxFuture};
 use gateway_core::{
-    engine::{
-        credential::{
-            AccountStatusFacts, CredentialState, OpaqueProviderData, ProviderAccountId,
-            QuotaEvidence, QuotaState, resolve_account_status,
-        },
-        probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
+    account::{
+        AccountStatusFacts, CredentialState, OpaqueProviderData, ProviderAccountId, QuotaEvidence,
+        QuotaState, resolve_account_status,
+    },
+    engine::probe::{
+        AccountProbe, AccountProbeError, AccountProbeErrorSource, AccountProbeRequest,
+        AccountProbeResult,
    },
    error::{ClientVisibleUpstreamError, GatewayError, GatewayErrorKind},
    operation::{GenerateRequest, Operation, ProtocolPayload},
    routing::ProviderKind,
+    upstream::UpstreamSendState,
 };

 use gateway_admin::{
@@ -22,22 +24,24 @@ use gateway_admin::{
        AdminError, MutationContext, Revision,
        accounts::{
            AccountConnectionTestEvent, AccountListQuery, AccountPage, AccountPageItem,
-            AccountRecord, AccountSummary, AccountUpdateResult, AccountUsage,
-            AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+            AccountRecord, AccountRuntimeSnapshot, AccountSummary, AccountUpdateResult,
+            AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
            BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
        },
        observability::TimeRange,
        provider_credentials::{
            AuthorizationCommit, AuthorizationCommitGuard, AuthorizationCredentialCommit,
            AuthorizationMutationTarget, AuthorizationStarted, CompleteAuthorization,
-            CredentialCommitGuard, CredentialDetails, CredentialImportCommit,
-            CredentialImportResult, CredentialListQuery, CredentialMutationResult, CredentialPage,
-            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
-            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
+            ConsumeProviderResetCredit, CredentialCommitGuard, CredentialDetails,
+            CredentialImportCommit, CredentialImportResult, CredentialListQuery,
+            CredentialMutationResult, CredentialPage, CredentialRotationCommit,
+            PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
+            PrepareCredentialRotation, PreparedAuthorizationCommit,
            PreparedAuthorizationCredential, PreparedCredentialCreate, PreparedCredentialImport,
            PreparedCredentialRotation, PreparedCredentialRotationFacts, ProviderDocument,
            ProviderExport, ProviderExportCredentialInput, ProviderModels, ProviderQuota,
-            ProviderQuotaRequest, ProviderQuotaWindow, QuotaLocalUsageAttribution,
+            ProviderQuotaRequest, ProviderQuotaWindow, ProviderResetCreditResult,
+            QuotaLocalUsageAttribution,
        },
        settings::{
            AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
@@ -60,7 +64,7 @@ pub(super) type EventLog = Arc<Mutex<Vec<&'static str>>>;
 pub(super) struct FakeProviderAdmin {
    kind: ProviderKind,
    events: EventLog,
-    failure: Mutex<Option<ProviderAdminErrorKind>>,
+    failure: Mutex<Option<ProviderAdminError>>,
    quota_failure: Mutex<Option<ProviderAdminErrorKind>>,
    pending: Arc<Mutex<Option<PendingAuthorizationMutation>>>,
    retry_authorization_after_abort: Mutex<bool>,
@@ -68,7 +72,9 @@ pub(super) struct FakeProviderAdmin {
    import_account_ids: Mutex<Vec<String>>,
    quota_requests: Mutex<Vec<ProviderQuotaRequest>>,
    quota: Mutex<ProviderQuota>,
+    quota_refresh_account: Mutex<Option<(Arc<FakeAccountStore>, AccountRecord)>>,
    current_credential_revision: Mutex<Revision>,
+    reset_credit_commands: Mutex<Vec<ConsumeProviderResetCredit>>,
 }

 impl FakeProviderAdmin {
@@ -84,12 +90,19 @@ impl FakeProviderAdmin {
            import_account_ids: Mutex::new(vec!["acct_prepared".to_owned()]),
            quota_requests: Mutex::new(Vec::new()),
            quota: Mutex::new(empty_quota()),
+            quota_refresh_account: Mutex::new(None),
            current_credential_revision: Mutex::new(revision(1)),
+            reset_credit_commands: Mutex::new(Vec::new()),
        })
    }

    pub(super) fn fail_next(&self, kind: ProviderAdminErrorKind) {
-        *self.failure.lock().expect("provider failure") = Some(kind);
+        *self.failure.lock().expect("provider failure") = Some(ProviderAdminError::new(kind));
+    }
+
+    fn fail_next_with_message(&self, kind: ProviderAdminErrorKind, message: &str) {
+        *self.failure.lock().expect("provider failure") =
+            Some(ProviderAdminError::new(kind).with_message(message));
    }

    pub(super) fn fail_next_quota(&self, kind: ProviderAdminErrorKind) {
@@ -113,6 +126,13 @@ impl FakeProviderAdmin {
            .clone()
    }

+    fn reset_credit_commands(&self) -> Vec<ConsumeProviderResetCredit> {
+        self.reset_credit_commands
+            .lock()
+            .expect("provider reset-credit commands")
+            .clone()
+    }
+
    pub(super) fn set_quota(&self, quota: ProviderQuota) {
        *self.quota.lock().expect("provider quota") = quota;
    }
@@ -145,7 +165,7 @@ impl FakeProviderAdmin {

    fn require_available(&self) -> Result<(), ProviderAdminError> {
        match self.failure.lock().expect("provider failure").take() {
-            Some(kind) => Err(ProviderAdminError::new(kind)),
+            Some(error) => Err(error),
            None => Ok(()),
        }
    }
@@ -328,6 +348,14 @@ impl ProviderAdmin for FakeProviderAdmin {
    ) -> Result<ProviderQuota, ProviderAdminError> {
        if request.refresh {
            self.record("provider.quota");
+            if let Some((store, account)) = self
+                .quota_refresh_account
+                .lock()
+                .expect("quota refresh account")
+                .take()
+            {
+                store.set_accounts(vec![account]);
+            }
        }
        self.quota_requests
            .lock()
@@ -344,6 +372,22 @@ impl ProviderAdmin for FakeProviderAdmin {
        Ok(self.quota.lock().expect("provider quota").clone())
    }

+    async fn consume_reset_credit(
+        &self,
+        command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        self.record("provider.consume_reset_credit");
+        self.reset_credit_commands
+            .lock()
+            .expect("provider reset-credit commands")
+            .push(command);
+        self.require_available()?;
+        Ok(ProviderResetCreditResult {
+            code: "reset".to_owned(),
+            credit: None,
+        })
+    }
+
    async fn models(
        &self,
        _: &ProviderAccountId,
@@ -471,7 +515,11 @@ impl FakeAccountStore {

 #[async_trait]
 impl AccountStore for FakeAccountStore {
-    async fn list_accounts(&self, _: AccountListQuery) -> AdminStoreResult<AccountPage> {
+    async fn list_accounts(
+        &self,
+        _: AccountListQuery,
+        _: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage> {
        self.record("store.list_accounts");
        let accounts = self.accounts.lock().expect("accounts").clone();
        let total = accounts.len() as u64;
@@ -490,7 +538,11 @@ impl AccountStore for FakeAccountStore {
        })
    }

-    async fn load_account(&self, account_id: &str) -> AdminStoreResult<Option<AccountPageItem>> {
+    async fn load_account(
+        &self,
+        account_id: &str,
+        _: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<Option<AccountPageItem>> {
        self.record("store.load_account");
        // probe 后的账号状态覆盖只对同一 id 生效；其余按账号列表查询。
        let account = self
@@ -754,6 +806,8 @@ impl SettingsStore for StaticSettingsStore {
            max_concurrent_per_account: 1,
            request_interval_ms: 0,
            rotation_strategy: RotationStrategy::Smart,
+            min_codex_desktop_version: None,
+            min_codex_cli_version: None,
            usage_retention_days: 30,
            ops_event_retention_days: 30,
            audit_retention_days: 30,
@@ -918,6 +972,9 @@ async fn connection_test_should_probe_unavailable_account() {
    assert!(matches!(
        events.last(),
        Some(AccountConnectionTestEvent::Failed {
+            source: AccountProbeErrorSource::Upstream,
+            gateway_error_code: GatewayErrorKind::RateLimited,
+            send_state: Some(UpstreamSendState::NotSent),
            message,
            provider_error_code: Some(code),
            provider_error_type: Some(error_type),
@@ -952,6 +1009,9 @@ async fn connection_test_rate_limited_probe_returns_provider_failure() {
    assert!(matches!(
        events.last(),
        Some(AccountConnectionTestEvent::Failed {
+            source: AccountProbeErrorSource::Provider,
+            gateway_error_code: GatewayErrorKind::RateLimited,
+            send_state: Some(UpstreamSendState::NotSent),
            message,
            ..
        })
@@ -1048,6 +1108,47 @@ async fn accounts_refresh_should_keep_guard_through_store_commit() {
    assert_eq!(store.audit_requests(), ["refresh-request"]);
 }

+#[tokio::test]
+async fn accounts_quota_refresh_should_return_the_updated_account_status() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let mut account = account_record("openai");
+    account.quota = QuotaState::exhausted(
+        QuotaEvidence::UsageLimitReached,
+        std::time::SystemTime::now(),
+        None,
+    );
+    let store = FakeAccountStore::with_account(account.clone(), events.clone());
+    account.quota = QuotaState::allowed(std::time::SystemTime::now());
+    *provider
+        .quota_refresh_account
+        .lock()
+        .expect("quota refresh account") = Some((store.clone(), account));
+
+    let result = accounts_service(provider, store)
+        .await
+        .accounts()
+        .quota(
+            &ProviderAccountId::new("acct_test").expect("account ID"),
+            true,
+        )
+        .await
+        .expect("refresh quota");
+
+    assert_eq!(
+        result.account.quota.access(),
+        gateway_core::account::QuotaAccessState::Allowed
+    );
+    assert_eq!(
+        result.projection.status,
+        gateway_admin::model::accounts::AccountStatus::Normal
+    );
+    assert_eq!(
+        recorded(&events),
+        ["store.load_account", "provider.quota", "store.load_account"]
+    );
+}
+
 #[tokio::test]
 async fn accounts_recover_should_commit_facts_then_return_normal_account() {
    let events = events();
@@ -1060,8 +1161,7 @@ async fn accounts_recover_should_commit_facts_then_return_normal_account() {
        std::time::SystemTime::now(),
        None,
    );
-    account.last_error_reason =
-        Some(gateway_core::engine::credential::AccountErrorReason::CredentialInvalid);
+    account.last_error_reason = Some(gateway_core::account::AccountErrorReason::CredentialInvalid);
    account.last_error_message = Some("invalid credential".to_owned());
    let store = FakeAccountStore::with_account(account, events.clone());
    let services = accounts_service(provider, store.clone()).await;
@@ -1083,7 +1183,7 @@ async fn accounts_recover_should_commit_facts_then_return_normal_account() {
    );
    assert_eq!(
        result.account.account.quota.access(),
-        gateway_core::engine::credential::QuotaAccessState::Allowed
+        gateway_core::account::QuotaAccessState::Allowed
    );
    assert_eq!(
        result.account.projection.status,
@@ -1116,7 +1216,7 @@ async fn accounts_update_should_commit_then_release_disabled_account_and_publish
                account_id: "acct_test".to_owned(),
                enabled: false,
                concurrency_limit: None,
-                weight: gateway_core::engine::credential::AccountWeight::DEFAULT,
+                weight: gateway_core::account::AccountWeight::DEFAULT,
                group_ids: Vec::new(),
            },
        )
@@ -1152,7 +1252,7 @@ async fn accounts_update_should_not_notify_provider_when_store_commit_fails() {
                account_id: "acct_test".to_owned(),
                enabled: false,
                concurrency_limit: None,
-                weight: gateway_core::engine::credential::AccountWeight::DEFAULT,
+                weight: gateway_core::account::AccountWeight::DEFAULT,
                group_ids: Vec::new(),
            },
        )
@@ -1193,7 +1293,7 @@ async fn accounts_batch_update_should_commit_once_and_notify_each_provider() {
                account_ids: vec!["acct_openai".to_owned(), "acct_xai".to_owned()],
                enabled: false,
                concurrency_limit: None,
-                weight: gateway_core::engine::credential::AccountWeight::DEFAULT,
+                weight: gateway_core::account::AccountWeight::DEFAULT,
                group_ids: Vec::new(),
            },
        )
@@ -1257,7 +1357,9 @@ async fn accounts_list_should_degrade_quota_failure_to_empty_window_without_drop
            key: "primary".to_owned(),
            group: "shortTerm".to_owned(),
            label: "5小时限额".to_owned(),
-            source: None,
+            limit_id: None,
+            limit_name: None,
+            role: None,
            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
            window_seconds: Some(5 * 60 * 60),
            used_percent: Some(97.0),
@@ -1386,7 +1488,9 @@ async fn accounts_list_should_not_derive_rate_limited_from_provider_quota_view()
            key: "primary".to_owned(),
            group: "shortTerm".to_owned(),
            label: "5小时限额".to_owned(),
-            source: None,
+            limit_id: None,
+            limit_name: None,
+            role: None,
            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
            window_seconds: Some(5 * 60 * 60),
            used_percent: Some(100.0),
@@ -1431,7 +1535,9 @@ async fn accounts_list_should_not_derive_exhaustion_from_provider_quota_view() {
            key: "primary".to_owned(),
            group: "shortTerm".to_owned(),
            label: "5小时限额".to_owned(),
-            source: None,
+            limit_id: None,
+            limit_name: None,
+            role: None,
            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
            window_seconds: Some(5 * 60 * 60),
            used_percent: Some(100.0),
@@ -1477,7 +1583,9 @@ async fn accounts_list_should_attach_local_usage_to_quota_windows() {
            key: "primary".to_owned(),
            group: "shortTerm".to_owned(),
            label: "5小时限额".to_owned(),
-            source: None,
+            limit_id: None,
+            limit_name: None,
+            role: None,
            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
            window_seconds: Some(5 * 60 * 60),
            used_percent: Some(97.0),
@@ -1542,7 +1650,9 @@ async fn accounts_list_should_not_attach_account_usage_to_model_specific_quota_w
                key: "core-primary".to_owned(),
                group: "weekly".to_owned(),
                label: "周额度".to_owned(),
-                source: Some("codex".to_owned()),
+                limit_id: Some("codex".to_owned()),
+                limit_name: None,
+                role: None,
                local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
                window_seconds: Some(7 * 24 * 60 * 60),
                used_percent: Some(1.0),
@@ -1554,8 +1664,10 @@ async fn accounts_list_should_not_attach_account_usage_to_model_specific_quota_w
            ProviderQuotaWindow {
                key: "codex-bengalfox-primary".to_owned(),
                group: "weekly".to_owned(),
-                label: "GPT-5.3-Codex-Spark · 周额度".to_owned(),
-                source: Some("codex_bengalfox".to_owned()),
+                label: "周额度".to_owned(),
+                limit_id: Some("codex_bengalfox".to_owned()),
+                limit_name: Some("GPT-5.3-Codex-Spark".to_owned()),
+                role: None,
                local_usage_attribution: QuotaLocalUsageAttribution::Unavailable,
                window_seconds: Some(7 * 24 * 60 * 60),
                used_percent: Some(0.0),
@@ -1650,6 +1762,90 @@ async fn accounts_refresh_provider_failure_should_not_call_store_commit() {
    );
 }

+#[tokio::test]
+async fn reset_credit_oauth_refresh_should_reuse_the_exact_consume_command() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.fail_next(ProviderAdminErrorKind::CredentialRefreshRequired);
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = accounts_service(provider.clone(), store).await;
+    let redeem_request_id =
+        uuid::Uuid::parse_str("8fbf302d-11df-4bd5-82e4-08e4b3df7874").expect("UUID v4");
+    let command = ConsumeProviderResetCredit {
+        account_id: ProviderAccountId::new("acct_test").expect("account ID"),
+        credit_id: Some("credit_1".to_owned()),
+        redeem_request_id,
+    };
+
+    let result = services
+        .accounts()
+        .consume_reset_credit(&context("reset-credit-refresh"), command.clone())
+        .await
+        .expect("consume after OAuth refresh");
+
+    assert_eq!(result.code, "reset");
+    assert_eq!(provider.reset_credit_commands(), [command.clone(), command]);
+    assert!(recorded(&events).contains(&"provider.prepare_refresh"));
+    assert!(recorded(&events).contains(&"store.commit_refresh"));
+}
+
+#[tokio::test]
+async fn reset_credit_unknown_result_should_keep_a_stable_admin_kind() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    provider.fail_next(ProviderAdminErrorKind::Ambiguous);
+    let store = FakeAccountStore::new("openai", events);
+    let services = accounts_service(provider, store).await;
+    let command = ConsumeProviderResetCredit {
+        account_id: ProviderAccountId::new("acct_test").expect("account ID"),
+        credit_id: Some("credit_1".to_owned()),
+        redeem_request_id: uuid::Uuid::parse_str("244e790c-42a3-4ec9-a45d-a32b218bc8ac")
+            .expect("UUID v4"),
+    };
+
+    let error = services
+        .accounts()
+        .consume_reset_credit(&context("reset-credit-ambiguous"), command)
+        .await
+        .expect_err("ambiguous consume result must remain classified");
+
+    assert_eq!(
+        error.kind(),
+        gateway_admin::model::AdminErrorKind::UpstreamResultUnknown
+    );
+    assert_eq!(
+        error.to_string(),
+        "上游执行结果未知，请刷新状态后再决定是否重试"
+    );
+}
+
+#[tokio::test]
+async fn accounts_refresh_should_not_expose_the_provider_failure_message() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let upstream_message = "Your refresh token has already been used.";
+    provider.fail_next_with_message(ProviderAdminErrorKind::Conflict, upstream_message);
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = accounts_service(provider, store).await;
+
+    let error = services
+        .accounts()
+        .refresh(
+            &context("refresh-provider-message"),
+            ProviderAccountId::new("acct_test").expect("account ID"),
+        )
+        .await
+        .expect_err("Provider preparation must fail");
+
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Conflict);
+    assert_eq!(error.to_string(), "Provider 资源状态冲突，请刷新后重试");
+    assert!(!error.to_string().contains(upstream_message));
+    assert_eq!(
+        recorded(&events),
+        ["store.load_account", "provider.prepare_refresh"]
+    );
+}
+
 #[tokio::test]
 async fn accounts_refresh_store_failure_should_drop_guard_after_commit_attempt() {
    let events = events();
@@ -1750,7 +1946,7 @@ pub(super) fn account_record(kind: &str) -> AccountRecord {
        next_refresh_at: Some(now + TimeDelta::minutes(30)),
        enabled: true,
        concurrency_limit: None,
-        weight: gateway_core::engine::credential::AccountWeight::DEFAULT,
+        weight: gateway_core::account::AccountWeight::DEFAULT,
        credential_state: CredentialState::Ready,
        credential_observed_at: now,
        quota: QuotaState::allowed(now.into()),
@@ -1853,12 +2049,16 @@ impl AccountProbe for FailingAccountProbe {
                Some("usage_exhausted".to_owned()),
                Some("invalid_request_error".to_owned()),
            );
-            Err(GatewayError::new(
-                GatewayErrorKind::RateLimited,
-                "upstream capacity is temporarily unavailable",
-            )
-            .with_client_visible_upstream_error(detail)
-            .into())
+            Err(AccountProbeError::new(
+                GatewayError::new(
+                    GatewayErrorKind::RateLimited,
+                    "upstream capacity is temporarily unavailable",
+                )
+                .with_client_visible_upstream_error(detail),
+                AccountProbeErrorSource::Upstream,
+                Some(UpstreamSendState::NotSent),
+                None,
+            ))
        })
    }
 }
@@ -1874,11 +2074,15 @@ impl AccountProbe for FreeModelQuotaProbe {
    ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
        Box::pin(async move {
            self.store.set_account_after_probe(account_record("xai"));
-            Err(GatewayError::new(
-                GatewayErrorKind::RateLimited,
-                "xAI free model quota is exhausted",
-            )
-            .into())
+            Err(AccountProbeError::new(
+                GatewayError::new(
+                    GatewayErrorKind::RateLimited,
+                    "xAI free model quota is exhausted",
+                ),
+                AccountProbeErrorSource::Provider,
+                Some(UpstreamSendState::NotSent),
+                None,
+            ))
        })
    }
 }
@@ -1,3 +1,4 @@
+mod account_groups;
 mod accounts;
 mod auth;
 mod backup;
@@ -21,15 +22,16 @@ use gateway_admin::{
    model::{
        MutationContext, Revision,
        account_groups::{
-            AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, DeleteAccountGroup,
-            NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+            AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+            DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
        },
        accounts::{
-            AccountListQuery, AccountPage, AccountUpdateResult, AccountUsage,
-            AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+            AccountListQuery, AccountPage, AccountRuntimeSnapshot, AccountUpdateResult,
+            AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
            BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
        },
        auth::{AdminAuditEvent, AdminSession},
+        client_distribution::CodexDesktopWindowsDownloads,
        client_keys::{
            ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, ClientKeySecret, DeleteClientKey,
            NewClientKey, SetClientKeyEnabled, UpdateClientKey,
@@ -54,10 +56,12 @@ use gateway_admin::{
    },
    ports::{
        backup::BackupStorePorts,
+        client_distribution::ClientDistributionResolver,
        provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind},
        store::{
-            AccountGroupStore, AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStorePorts,
-            AdminStoreResult, AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore,
+            AccountGroupStore, AccountRuntimeStore, AccountStore, AdminAccountStorePorts,
+            AdminStoreError, AdminStoreErrorKind, AdminStorePorts, AdminStoreResult, AuthStore,
+            ClientKeyStore, ObservabilityStore, SettingsStore,
        },
        system::{
            SystemOperationError, SystemOperationErrorKind, SystemOperations,
@@ -66,19 +70,20 @@ use gateway_admin::{
    },
 };
 use gateway_core::{
-    engine::{
-        credential::ProviderAccountId,
-        probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
-    },
+    account::ProviderAccountId,
+    engine::probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
    error::{GatewayError, GatewayErrorKind},
    policy::ClientApiKeyId,
-    routing::{ConfigRevision, ProviderKind, snapshot::SnapshotControl},
+    routing::{ConfigRevision, ProviderKind},
+    runtime::SnapshotControl,
 };

 pub(super) struct AdminHarness {
    default_password: String,
    session_ttl_minutes: u64,
    accounts: Arc<dyn AccountStore>,
+    account_runtime: Arc<dyn AccountRuntimeStore>,
+    account_groups: Arc<dyn AccountGroupStore>,
    auth: Arc<dyn AuthStore>,
    client_keys: Arc<dyn ClientKeyStore>,
    observability: Arc<dyn ObservabilityStore>,
@@ -96,6 +101,8 @@ impl AdminHarness {
            default_password: "strong-test-password".to_owned(),
            session_ttl_minutes: 60,
            accounts: unavailable.clone(),
+            account_runtime: unavailable.clone(),
+            account_groups: Arc::new(UnavailableAccountGroupStore),
            auth: Arc::new(BootstrapAuthStore::default()),
            client_keys: unavailable.clone(),
            observability: unavailable.clone(),
@@ -125,6 +132,16 @@ impl AdminHarness {
        self
    }

+    pub(super) fn account_runtime(mut self, store: Arc<dyn AccountRuntimeStore>) -> Self {
+        self.account_runtime = store;
+        self
+    }
+
+    pub(super) fn account_groups(mut self, store: Arc<dyn AccountGroupStore>) -> Self {
+        self.account_groups = store;
+        self
+    }
+
    pub(super) fn auth(mut self, store: Arc<dyn AuthStore>) -> Self {
        self.auth = store;
        self
@@ -175,8 +192,11 @@ impl AdminHarness {
                default_password: InitialAdminPassword::new(self.default_password),
            },
            AdminStorePorts::new(
-                self.accounts,
-                Arc::new(UnavailableAccountGroupStore),
+                AdminAccountStorePorts::new(
+                    self.accounts,
+                    self.account_runtime,
+                    self.account_groups,
+                ),
                self.auth,
                self.client_keys,
                self.observability,
@@ -186,6 +206,7 @@ impl AdminHarness {
            self.providers,
            Arc::new(NoopSnapshot),
            self.probe,
+            Arc::new(NoopClientDistribution),
            self.system,
        )
        .await
@@ -194,6 +215,20 @@ impl AdminHarness {
    }
 }

+struct NoopClientDistribution;
+
+#[async_trait]
+impl ClientDistributionResolver for NoopClientDistribution {
+    async fn resolve_codex_desktop_windows(&self, _: bool) -> CodexDesktopWindowsDownloads {
+        CodexDesktopWindowsDownloads {
+            resolved_at: Utc::now(),
+            cached: false,
+            warning: None,
+            packages: Vec::new(),
+        }
+    }
+}
+
 #[derive(Default)]
 struct BootstrapAuthStore {
    password_hash: Mutex<Option<String>>,
@@ -252,6 +287,13 @@ impl AccountGroupStore for UnavailableAccountGroupStore {
        Err(unavailable("account groups"))
    }

+    async fn load_account_group_members(
+        &self,
+        _: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>> {
+        Err(unavailable("account group members"))
+    }
+
    async fn create_account_group(
        &self,
        _: NewAccountGroup,
@@ -287,13 +329,18 @@ impl AccountGroupStore for UnavailableAccountGroupStore {

 #[async_trait]
 impl AccountStore for UnavailableStore {
-    async fn list_accounts(&self, _: AccountListQuery) -> AdminStoreResult<AccountPage> {
+    async fn list_accounts(
+        &self,
+        _: AccountListQuery,
+        _: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage> {
        Err(unavailable("accounts"))
    }

    async fn load_account(
        &self,
        _: &str,
+        _: AccountRuntimeSnapshot,
    ) -> AdminStoreResult<Option<gateway_admin::model::accounts::AccountPageItem>> {
        Err(unavailable("account"))
    }
@@ -410,6 +457,17 @@ impl AccountStore for UnavailableStore {
    }
 }

+#[async_trait]
+impl AccountRuntimeStore for UnavailableStore {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+
+    async fn account_runtime(&self, _: &[String]) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+}
+
 #[async_trait]
 impl ClientKeyStore for UnavailableStore {
    async fn list_client_keys(&self, _: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
@@ -478,13 +536,14 @@ impl ObservabilityStore for UnavailableStore {
        Err(unavailable("usage trend"))
    }

-    async fn usage_calculated_billing_facts(
+    fn usage_calculated_billing_facts(
        &self,
        _: TimeRange,
        _: UsageFilter,
-    ) -> AdminStoreResult<Vec<gateway_admin::model::observability::UsageCalculatedBillingFact>>
-    {
-        Err(unavailable("usage billing facts"))
+    ) -> gateway_admin::ports::store::UsageCalculatedBillingStream<'_> {
+        Box::pin(futures::stream::once(async {
+            Err(unavailable("usage billing facts"))
+        }))
    }

    async fn list_usage_records(&self, _: UsageQuery) -> AdminStoreResult<UsagePage> {
@@ -1,7 +1,10 @@
 use std::{
-    num::NonZeroU32,
    str::FromStr as _,
-    sync::{Arc, Mutex},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, AtomicUsize, Ordering},
+    },
+    time::Duration as StdDuration,
 };

 use async_trait::async_trait;
@@ -14,10 +17,10 @@ use gateway_admin::{
        observability::{
            AccountPoolMetrics, AttemptMetrics, CostCoverage, CurrencyCost, DashboardObservation,
            DashboardRuntimeSlots, DiagnosticDimension, DiagnosticObservation, Granularity,
-            HealthStatus, OpsErrorPage, OpsErrorQuery, PageNumber, RequestMetricPoint,
-            RequestMetrics, RequestOutcome, TimeRange, TrendKind, UsageBilling,
-            UsageCalculatedBillingFact, UsageDetail, UsageFilter, UsageOverview, UsagePage,
-            UsageQuery, UsageRecord, china_day_start,
+            HealthStatus, LatencyPercentiles, OpsErrorPage, OpsErrorQuery, PercentileMilliseconds,
+            RequestMetricPoint, RequestMetrics, TimeRange, TrendKind, UsageBilling,
+            UsageCalculatedBillingFact, UsageDetail, UsageFilter, UsageListRecord, UsageOverview,
+            UsagePage, UsageQuery, china_day_start,
        },
        settings::{
            AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
@@ -105,6 +108,40 @@ async fn health_timeline_should_keep_exactly_china_day_quarter_hour_slots() {
    }));
 }

+#[tokio::test]
+async fn dashboard_summary_should_derive_first_token_average_from_trend() {
+    let now = Utc::now();
+    let current_slot = quarter_hour_start(now);
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    store.replace_trend(vec![
+        health_metric_point(
+            current_slot - Duration::minutes(15),
+            RequestMetrics {
+                first_token_latency_sum_ms: 120,
+                first_token_latency_count: 2,
+                ..RequestMetrics::default()
+            },
+        ),
+        health_metric_point(
+            current_slot,
+            RequestMetrics {
+                first_token_latency_sum_ms: 180,
+                first_token_latency_count: 1,
+                ..RequestMetrics::default()
+            },
+        ),
+    ]);
+    let services = observability_services(store).await;
+
+    let summary = services
+        .observability()
+        .dashboard_summary(observation_range(now), TrendKind::Usage)
+        .await
+        .expect("dashboard summary");
+
+    assert_eq!(summary.average_first_token_latency_ms, Some(100));
+}
+
 #[tokio::test]
 async fn health_timeline_should_match_legacy_status_precedence_and_thresholds() {
    let now = Utc::now();
@@ -160,11 +197,15 @@ async fn health_timeline_should_match_legacy_status_precedence_and_thresholds()
        ),
    ];

-    for (metrics, expected_status, expected_reliability) in fixtures {
+    for (index, (metrics, expected_status, expected_reliability)) in
+        fixtures.into_iter().enumerate()
+    {
        store.replace_trend(vec![health_metric_point(current_slot, metrics)]);
+        let range_end =
+            now + Duration::seconds(i64::try_from(index).expect("fixture index fits i64") * 2);
        let timeline = services
            .observability()
-            .dashboard_summary(observation_range(now), TrendKind::Usage)
+            .dashboard_summary(observation_range(range_end), TrendKind::Usage)
            .await
            .expect("dashboard summary")
            .health_timeline;
@@ -220,6 +261,53 @@ async fn dashboard_summary_should_share_one_current_observation_time_across_runt
    assert!(summary_observed_at.is_some_and(|value| value > historical_end));
 }

+#[tokio::test]
+async fn dashboard_summary_should_coalesce_concurrent_requests_in_one_short_window() {
+    let end_bucket = Utc::now().timestamp().div_euclid(2) * 2;
+    let first_end = DateTime::from_timestamp(end_bucket, 100_000_000).expect("first end");
+    let second_end = DateTime::from_timestamp(end_bucket, 900_000_000).expect("second end");
+    let first_range = TimeRange::new(china_day_start(first_end), first_end).expect("first range");
+    let second_range =
+        TimeRange::new(china_day_start(second_end), second_end).expect("second range");
+    let store = Arc::new(FixtureObservabilityStore::new(first_range));
+    store.set_dashboard_delay(StdDuration::from_millis(20));
+    let services = observability_services(store.clone()).await;
+    let observability = services.observability();
+
+    let (first, second) = tokio::join!(
+        observability.dashboard_summary(first_range, TrendKind::Usage),
+        observability.dashboard_summary(second_range, TrendKind::Errors),
+    );
+
+    first.expect("first dashboard summary");
+    second.expect("second dashboard summary");
+    assert_eq!(store.dashboard_summary_calls(), 1);
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_reload_after_the_short_window_changes() {
+    let end_bucket = Utc::now().timestamp().div_euclid(2) * 2;
+    let first_end = DateTime::from_timestamp(end_bucket, 100_000_000).expect("first end");
+    let second_end = first_end + Duration::seconds(2);
+    let first_range = TimeRange::new(china_day_start(first_end), first_end).expect("first range");
+    let second_range =
+        TimeRange::new(china_day_start(second_end), second_end).expect("second range");
+    let store = Arc::new(FixtureObservabilityStore::new(first_range));
+    let services = observability_services(store.clone()).await;
+    let observability = services.observability();
+
+    observability
+        .dashboard_summary(first_range, TrendKind::Usage)
+        .await
+        .expect("first dashboard summary");
+    observability
+        .dashboard_summary(second_range, TrendKind::Usage)
+        .await
+        .expect("second dashboard summary");
+
+    assert_eq!(store.dashboard_summary_calls(), 2);
+}
+
 #[tokio::test]
 async fn observability_services_should_calculate_usage_insights_and_diagnostic_shares() {
    let now = Utc::now();
@@ -234,6 +322,24 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
        output_tokens: 200,
        total_tokens: 1_000,
        latency_count: 5,
+        admission_decision_count: 10,
+        admission_decision_percentiles: LatencyPercentiles {
+            p50_ms: Some(PercentileMilliseconds::new(2.0).expect("admission P50")),
+            p95_ms: Some(PercentileMilliseconds::new(5.0).expect("admission P95")),
+            p99_ms: Some(PercentileMilliseconds::new(8.0).expect("admission P99")),
+        },
+        account_selection_wait_count: 8,
+        account_selection_wait_percentiles: LatencyPercentiles {
+            p50_ms: Some(PercentileMilliseconds::new(10.0).expect("selection P50")),
+            p95_ms: Some(PercentileMilliseconds::new(40.0).expect("selection P95")),
+            p99_ms: Some(PercentileMilliseconds::new(70.0).expect("selection P99")),
+        },
+        output_throughput_p10: Some(40),
+        output_throughput_p50: Some(50),
+        output_throughput_p90: Some(60),
+        capacity_sample_count: 8,
+        capacity_utilization_avg_basis_points: Some(6_500),
+        capacity_utilization_p95_basis_points: Some(8_000),
        ..RequestMetrics::default()
    };
    store.replace_overview(UsageOverview {
@@ -294,10 +400,16 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
        .await
        .expect("usage diagnostics");

-    assert_eq!(insights.health.total_requests, 8);
+    assert_eq!(insights.health.total_requests, 10);
    assert_eq!(insights.health.failed_requests, 2);
+    assert_eq!(insights.health.success_rate, 0.75);
+    assert_eq!(insights.health.completion_rate, 1.0);
    assert_eq!(insights.granularity, Granularity::FifteenMinutes);
    assert_eq!(insights.performance.latency_coverage, 0.5);
+    assert_eq!(insights.performance.admission_decision_coverage, 1.0);
+    assert_eq!(insights.performance.account_selection_wait_coverage, 0.8);
+    assert_eq!(insights.performance.capacity_coverage, 0.8);
+    assert_eq!(insights.performance.output_throughput_p50, Some(50));
    assert_eq!(insights.cost.tokens_per_request, 100.0);
    assert_eq!(
        insights
@@ -337,8 +449,25 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
            .map(gateway_admin::model::observability::DecimalAmount::as_str),
        Some("1")
    );
+    assert_eq!(
+        insights
+            .cost
+            .no_cache_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("1.25")
+    );
+    assert_eq!(
+        insights
+            .cost
+            .tier_premium
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("0.25")
+    );
    assert_eq!(diagnostics.items[0].request_share, 0.75);
    assert_eq!(diagnostics.items[1].request_share, 0.25);
+    assert!((diagnostics.items[0].impact_score - 0.075).abs() < 1e-9);
 }

 #[tokio::test]
@@ -408,15 +537,48 @@ async fn usage_records_should_enrich_provider_reported_totals_when_pricing_match
    ));
 }

+#[tokio::test]
+async fn usage_insights_should_reject_partial_costs_when_billing_stream_fails() {
+    let now = Utc::now();
+    let range = observation_range(now);
+    let store = Arc::new(FixtureObservabilityStore::new(range));
+    store.replace_calculated_billing_facts(vec![UsageCalculatedBillingFact {
+        bucket_start: quarter_hour_start(now),
+        provider_kind: "openai".to_owned(),
+        upstream_model_id: "gpt-5.5".to_owned(),
+        service_tier: None,
+        input_tokens: Some(800),
+        output_tokens: Some(200),
+        cached_tokens: Some(0),
+        cache_write_tokens: Some(0),
+        total: CurrencyCost {
+            currency: "USD".to_owned(),
+            amount: "1.25".parse().expect("cost"),
+        },
+    }]);
+    store.billing_stream_fails.store(true, Ordering::SeqCst);
+    let services = observability_services_with_calculated_billing(store).await;
+    assert!(
+        services
+            .observability()
+            .usage_insights(range, UsageFilter::default())
+            .await
+            .is_err()
+    );
+}
+
 struct FixtureObservabilityStore {
    trend: Mutex<Vec<RequestMetricPoint>>,
    overview: Mutex<UsageOverview>,
    calculated_billing_facts: Mutex<Vec<UsageCalculatedBillingFact>>,
+    billing_stream_fails: AtomicBool,
    diagnostics: Mutex<Vec<DiagnosticObservation>>,
    runtime_slots: Mutex<Option<DashboardRuntimeSlots>>,
    summary_observed_at: Mutex<Option<DateTime<Utc>>>,
    slots_observed_at: Mutex<Option<DateTime<Utc>>>,
-    usage_records: Mutex<Vec<UsageRecord>>,
+    usage_records: Mutex<Vec<UsageListRecord>>,
+    dashboard_delay: Mutex<StdDuration>,
+    dashboard_summary_calls: AtomicUsize,
 }

 impl FixtureObservabilityStore {
@@ -430,14 +592,25 @@ impl FixtureObservabilityStore {
                providers: Vec::new(),
            }),
            calculated_billing_facts: Mutex::new(Vec::new()),
+            billing_stream_fails: AtomicBool::new(false),
            diagnostics: Mutex::new(Vec::new()),
            runtime_slots: Mutex::new(None),
            summary_observed_at: Mutex::new(None),
            slots_observed_at: Mutex::new(None),
            usage_records: Mutex::new(Vec::new()),
+            dashboard_delay: Mutex::new(StdDuration::ZERO),
+            dashboard_summary_calls: AtomicUsize::new(0),
        }
    }

+    fn set_dashboard_delay(&self, delay: StdDuration) {
+        *self.dashboard_delay.lock().expect("dashboard delay") = delay;
+    }
+
+    fn dashboard_summary_calls(&self) -> usize {
+        self.dashboard_summary_calls.load(Ordering::Relaxed)
+    }
+
    fn replace_trend(&self, trend: Vec<RequestMetricPoint>) {
        *self.trend.lock().expect("trend") = trend;
    }
@@ -471,7 +644,7 @@ impl FixtureObservabilityStore {
        )
    }

-    fn replace_usage_records(&self, records: Vec<UsageRecord>) {
+    fn replace_usage_records(&self, records: Vec<UsageListRecord>) {
        *self.usage_records.lock().expect("usage records") = records;
    }
 }
@@ -483,14 +656,17 @@ impl ObservabilityStore for FixtureObservabilityStore {
        range: TimeRange,
        observed_at: DateTime<Utc>,
    ) -> AdminStoreResult<DashboardObservation> {
+        self.dashboard_summary_calls.fetch_add(1, Ordering::Relaxed);
        *self
            .summary_observed_at
            .lock()
            .expect("summary observed at") = Some(observed_at);
+        let dashboard_delay = *self.dashboard_delay.lock().expect("dashboard delay");
+        if !dashboard_delay.is_zero() {
+            tokio::time::sleep(dashboard_delay).await;
+        }
        Ok(DashboardObservation {
            range,
-            requests: RequestMetrics::default(),
-            attempts: AttemptMetrics::default(),
            totals: Default::default(),
            provider_accounts: AccountPoolMetrics::default(),
            trend: self.trend.lock().expect("trend").clone(),
@@ -519,25 +695,33 @@ impl ObservabilityStore for FixtureObservabilityStore {
        Ok(self.trend.lock().expect("trend").clone())
    }

-    async fn usage_calculated_billing_facts(
+    fn usage_calculated_billing_facts(
        &self,
        _: TimeRange,
        _: UsageFilter,
-    ) -> AdminStoreResult<Vec<UsageCalculatedBillingFact>> {
-        Ok(self
+    ) -> gateway_admin::ports::store::UsageCalculatedBillingStream<'_> {
+        let facts = self
            .calculated_billing_facts
            .lock()
            .expect("calculated billing facts")
-            .clone())
+            .clone();
+        let error = self
+            .billing_stream_fails
+            .load(Ordering::SeqCst)
+            .then(|| Err(super::unavailable("billing stream failed")));
+        Box::pin(futures::stream::iter(
+            facts.into_iter().map(Ok).chain(error),
+        ))
    }

-    async fn list_usage_records(&self, _: UsageQuery) -> AdminStoreResult<UsagePage> {
+    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage> {
        let items = self.usage_records.lock().expect("usage records").clone();
        let total = u64::try_from(items.len()).unwrap_or(u64::MAX);
        Ok(UsagePage {
            items,
+            current_page: query.current_page,
+            page_size: query.page_size.get(),
            total,
-            next_cursor: None,
        })
    }

@@ -576,6 +760,8 @@ impl SettingsStore for FixtureSettingsStore {
            max_concurrent_per_account: 1,
            request_interval_ms: 0,
            rotation_strategy: RotationStrategy::Smart,
+            min_codex_desktop_version: None,
+            min_codex_cli_version: None,
            usage_retention_days: 31,
            ops_event_retention_days: 30,
            audit_retention_days: 30,
@@ -639,8 +825,7 @@ fn usage_query(now: DateTime<Utc>) -> UsageQuery {
    UsageQuery {
        range: observation_range(now),
        filter: UsageFilter::default(),
-        cursor: None,
-        page: PageNumber::new(NonZeroU32::new(1).expect("page number")),
+        current_page: 1,
        page_size: PageSize::new(50).expect("page size"),
    }
 }
@@ -650,19 +835,12 @@ fn total_record(
    provider_kind: Option<&str>,
    source: &str,
    now: DateTime<Utc>,
-) -> UsageRecord {
-    UsageRecord {
+) -> UsageListRecord {
+    UsageListRecord {
        id: id.to_owned(),
-        client_api_key_ref: "key_billing".to_owned(),
-        config_revision: 1,
-        routing_scope: "all".to_owned(),
-        routing_group_refs: Vec::new(),
-        routing_group_names_snapshot: Vec::new(),
-        protocol: "openai".to_owned(),
-        operation: "generate".to_owned(),
        endpoint: "/v1/responses".to_owned(),
        client_transport: "http_sse".to_owned(),
-        requested_model_id: "gpt-5.5".to_owned(),
+        requested_model_id: Some("gpt-5.5".to_owned()),
        provider_kind: provider_kind.map(str::to_owned),
        provider_account_ref: None,
        provider_account_name: None,
@@ -670,23 +848,7 @@ fn total_record(
        provider_account_authentication_kind: None,
        upstream_model_id: Some("gpt-5.5".to_owned()),
        upstream_transport: None,
-        http_version: None,
-        websocket_pool: None,
        service_tier: None,
-        provider_metadata_json: None,
-        attempt_count: 1,
-        upstream_send_state: "sent".to_owned(),
-        downstream_committed_at: None,
-        outcome: RequestOutcome::Succeeded,
-        client_status_code: Some(200),
-        upstream_status_code: Some(200),
-        client_response_id: None,
-        upstream_request_id: None,
-        upstream_response_id: None,
-        error_kind: None,
-        provider_error_code: None,
-        error_message: None,
-        retry_after_ms: None,
        input_tokens: Some(800),
        output_tokens: Some(200),
        cached_tokens: Some(0),
@@ -715,18 +877,17 @@ fn total_record(
        first_token_ms: None,
        provider_processing_ms: None,
        latency_ms: Some(100),
+        admission_decision_ms: None,
+        account_selection_wait_ms: None,
+        capacity_used_slots: None,
+        capacity_total_slots: None,
        client_ip: None,
        user_agent: None,
        reasoning_effort: None,
        reasoning_preset: None,
-        request_kind: None,
        subagent_kind: None,
        compact: false,
-        image_generation_requested: false,
-        image_generation_succeeded: None,
        started_at: now,
-        deadline_at: now,
-        completed_at: Some(now),
    }
 }

@@ -742,6 +903,9 @@ fn health_metric_point(bucket_start: DateTime<Utc>, metrics: RequestMetrics) ->

 fn diagnostic(name: &str, request_count: u64) -> DiagnosticObservation {
    DiagnosticObservation {
+        first_token_p95_ms: None,
+        non_completion_count: 0,
+        retry_count: 0,
        key: name.to_owned(),
        name: name.to_owned(),
        request_count,
@@ -1,6 +1,6 @@
 use std::sync::Arc;

-use gateway_core::engine::credential::ProviderAccountId;
+use gateway_core::account::ProviderAccountId;

 use gateway_admin::{
    AdminServices,
@@ -67,6 +67,8 @@ async fn settings_should_reject_zero_refresh_margin_before_store_call() {
                max_concurrent_per_account: 1,
                request_interval_ms: 0,
                rotation_strategy: RotationStrategy::Smart,
+                min_codex_desktop_version: None,
+                min_codex_cli_version: None,
                usage_retention_days: 31,
                ops_event_retention_days: 30,
                audit_retention_days: 30,
@@ -1,6 +1,6 @@
 use std::sync::Arc;

-use gateway_core::engine::credential::ProviderAccountId;
+use gateway_core::account::ProviderAccountId;

 use gateway_admin::{
    AdminServices,
@@ -24,7 +24,7 @@ secrecy = "0.10"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 thiserror = "2.0.18"
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "time"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "sync", "time"] }
 tower-http = { version = "0.7.0", features = ["cors", "fs", "request-id", "timeout", "trace"] }
 tracing = "0.1.44"
 url = "2.5.8"
@@ -33,7 +33,7 @@ uuid = { version = "1.23.3", features = ["v7"] }
 [dev-dependencies]
 async-trait = "0.1.89"
 axum = { version = "0.8.9", default-features = false, features = ["http1", "tokio"] }
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "net", "rt-multi-thread"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "net", "rt-multi-thread", "test-util"] }
 tokio-tungstenite = "0.29.0"
 tower = { version = "0.5.3", features = ["util"] }

@@ -3,8 +3,8 @@
 use std::collections::BTreeMap;

 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post},
@@ -22,8 +22,8 @@ use gateway_core::routing::AccountGroupId;
 use serde::{Deserialize, Serialize};

 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, PageMeta,
-    WireValidationError, wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta, WireValidationError, wire::map_admin_service_error,
 };

 const DEFAULT_PAGE_SIZE: u32 = 50;
@@ -127,7 +127,7 @@ struct AccountGroupCapacityView {
 #[serde(rename_all = "camelCase")]
 struct AccountGroupUsageView {
    today_usd: String,
-    total_usd: String,
+    retained_total_usd: String,
 }

 impl From<AccountGroupRecord> for AccountGroupView {
@@ -168,7 +168,7 @@ fn capacity_view(capacity: AccountGroupCapacity) -> AccountGroupCapacityView {
 fn usage_view(usage: AccountGroupUsage) -> AccountGroupUsageView {
    AccountGroupUsageView {
        today_usd: usage.today_usd.to_string(),
-        total_usd: usage.total_usd.to_string(),
+        retained_total_usd: usage.retained_total_usd.to_string(),
    }
 }

@@ -235,7 +235,7 @@ where
 async fn list<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<ListAccountGroupsQuery>,
+    AdminQuery(query): AdminQuery<ListAccountGroupsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -255,7 +255,7 @@ where
 async fn create<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<CreateAccountGroupRequest>,
+    AdminJson(request): AdminJson<CreateAccountGroupRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -281,7 +281,7 @@ where
 async fn update<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<UpdateAccountGroupRequest>,
+    AdminJson(request): AdminJson<UpdateAccountGroupRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -308,7 +308,7 @@ where
 async fn enable<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<AccountGroupIdRequest>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -319,7 +319,7 @@ where
 async fn disable<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<AccountGroupIdRequest>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -355,7 +355,7 @@ where
 async fn delete<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<AccountGroupIdRequest>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -387,12 +387,11 @@ fn mutation_response(
 }

 fn group_id(value: String) -> Result<AccountGroupId, AdminError> {
-    AccountGroupId::new(value).map_err(|_| AdminError::bad_request("Invalid account group ID"))
+    AccountGroupId::new(value).map_err(|_| AdminError::bad_request("账号组 ID 不合法"))
 }

 fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
-    AccountGroupColor::parse(value)
-        .ok_or_else(|| AdminError::bad_request("Invalid account group color"))
+    AccountGroupColor::parse(value).ok_or_else(|| AdminError::bad_request("账号组颜色不合法"))
 }

 fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), AdminError> {
@@ -403,15 +402,15 @@ fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), Ad
        || description
            .is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
    {
-        return Err(AdminError::bad_request("Invalid account group request"));
+        return Err(AdminError::bad_request("账号组请求不合法"));
    }
    Ok(())
 }

 fn map_wire_error(_: WireValidationError) -> AdminError {
-    AdminError::bad_request("Invalid account group query")
+    AdminError::bad_request("账号组查询参数不合法")
 }

 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Account group repository unavailable")
+    map_admin_service_error(error)
 }
@@ -0,0 +1,488 @@
+//! Provider-owned 凭据请求、命令转换与敏感材料校验。
+
+use super::*;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum AccountProvider {
+    OpenAi,
+    Xai,
+}
+
+impl AccountProvider {
+    fn parse(value: &str) -> Result<Self, WireValidationError> {
+        match value.trim() {
+            "openai" => Ok(Self::OpenAi),
+            "xai" => Ok(Self::Xai),
+            _ => Err(WireValidationError::new("provider")),
+        }
+    }
+}
+
+/// Provider-owned 账号导入请求；公共 API 不解释 `data` 内部字段。
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountImportRequest {
+    pub provider: String,
+    pub data: Value,
+}
+
+impl AccountImportRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        if !self.data.is_object()
+            || serde_json::to_vec(&self.data)
+                .map_or(true, |encoded| encoded.len() > MAX_IMPORT_DATA_BYTES)
+        {
+            return Err(WireValidationError::new("data"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, ImportCredentials), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            ImportCredentials {
+                context,
+                document: provider_document(self.data, "data")?,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct StartAccountAuthorizationRequest {
+    pub provider: String,
+    pub name: String,
+    pub account_id: Option<String>,
+}
+
+impl StartAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        require_text(&self.name, MAX_NAME_BYTES, "name")?;
+        if let Some(account_id) = self.account_id.as_deref() {
+            require_account_id(account_id, "accountId")?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, StartAuthorization), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        let reauthorization = self
+            .account_id
+            .map(ProviderAccountId::new)
+            .transpose()
+            .map_err(|_| WireValidationError::new("accountId"))?;
+        Ok((
+            provider,
+            StartAuthorization {
+                context,
+                name: self.name,
+                reauthorization,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct CompleteAccountAuthorizationRequest {
+    pub provider: String,
+    pub flow_id: String,
+    pub callback_url: String,
+}
+
+impl CompleteAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        let provider = AccountProvider::parse(&self.provider)?;
+        match provider {
+            AccountProvider::OpenAi => {
+                if !URL_SAFE_NO_PAD
+                    .decode(&self.flow_id)
+                    .is_ok_and(|decoded| decoded.len() == 32)
+                {
+                    return Err(WireValidationError::new("flowId"));
+                }
+            }
+            AccountProvider::Xai => require_wire_id(&self.flow_id, "flowId")?,
+        }
+        require_text(&self.callback_url, MAX_CALLBACK_URL_BYTES, "callbackUrl")
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, CompleteAuthorization), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            CompleteAuthorization {
+                context,
+                flow_id: self.flow_id,
+                callback_url: self.callback_url,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateAccountRequest {
+    pub account_id: String,
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+impl UpdateAccountRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        validate_wire_group_ids(&self.group_ids)?;
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<UpdateAccount, WireValidationError> {
+        self.validate()?;
+        Ok(UpdateAccount {
+            account_id: self.account_id,
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdatedAccountData {
+    pub account_id: String,
+    pub config_revision: u64,
+}
+
+impl From<AccountUpdateResult> for UpdatedAccountData {
+    fn from(result: AccountUpdateResult) -> Self {
+        Self {
+            account_id: result.account_id.to_string(),
+            config_revision: result.config_revision.get(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountDeletionRequest {
+    pub provider: String,
+    pub account_ids: Vec<String>,
+}
+
+impl AccountDeletionRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        if self.account_ids.is_empty() || self.account_ids.len() > MAX_ACCOUNT_DELETE_BATCH {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        let mut unique = BTreeSet::new();
+        for account_id in &self.account_ids {
+            require_account_id(account_id, "accountIds")?;
+            if !unique.insert(account_id.as_str()) {
+                return Err(WireValidationError::new("accountIds"));
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, CredentialDeletion), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            CredentialDeletion {
+                context,
+                account_ids: self
+                    .account_ids
+                    .into_iter()
+                    .map(ProviderAccountId::new)
+                    .collect::<Result<Vec<_>, _>>()
+                    .map_err(|_| WireValidationError::new("accountIds"))?,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RotateAccountRequest {
+    pub provider: String,
+    pub account_id: String,
+    pub access_token: String,
+    pub refresh_token: Option<String>,
+    pub id_token: Option<String>,
+}
+
+impl RotateAccountRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if AccountProvider::parse(&self.provider)? != AccountProvider::OpenAi {
+            return Err(WireValidationError::new("provider"));
+        }
+        require_account_id(&self.account_id, "accountId")?;
+        validate_oauth_material(
+            &self.access_token,
+            self.refresh_token.as_deref(),
+            self.id_token.as_deref(),
+        )
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<RotateCredential, WireValidationError> {
+        self.validate()?;
+        let mut material = Map::new();
+        material.insert("access_token".to_owned(), Value::String(self.access_token));
+        material.insert(
+            "refresh_token".to_owned(),
+            self.refresh_token.map_or(Value::Null, Value::String),
+        );
+        material.insert(
+            "id_token".to_owned(),
+            self.id_token.map_or(Value::Null, Value::String),
+        );
+        Ok(RotateCredential {
+            mutation: CredentialMutation {
+                context,
+                account_id: ProviderAccountId::new(self.account_id)
+                    .map_err(|_| WireValidationError::new("accountId"))?,
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(material)),
+        })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountImportData {
+    pub imported_count: usize,
+    pub account_ids: Vec<String>,
+}
+
+impl AccountImportData {
+    pub fn from_result(result: CredentialImportResult) -> Self {
+        let account_ids = result
+            .credential_ids
+            .into_iter()
+            .map(|account_id| account_id.to_string())
+            .collect::<Vec<_>>();
+        Self {
+            imported_count: account_ids.len(),
+            account_ids,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountAuthorizationData {
+    pub flow_id: String,
+    pub authorization_url: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+impl From<AuthorizationStarted> for AccountAuthorizationData {
+    fn from(started: AuthorizationStarted) -> Self {
+        Self {
+            flow_id: started.flow_id,
+            authorization_url: started.authorization_url,
+            expires_at: started.expires_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountMutationData {
+    pub account_id: String,
+}
+
+impl From<CredentialMutationResult> for AccountMutationData {
+    fn from(result: CredentialMutationResult) -> Self {
+        Self {
+            account_id: result.account_id.to_string(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountDeletionData {
+    pub deleted_count: usize,
+    pub account_ids: Vec<String>,
+}
+
+impl From<CredentialDeletionResult> for AccountDeletionData {
+    fn from(result: CredentialDeletionResult) -> Self {
+        let account_ids = result
+            .account_ids
+            .into_iter()
+            .map(|account_id| account_id.to_string())
+            .collect::<Vec<_>>();
+        Self {
+            deleted_count: account_ids.len(),
+            account_ids,
+        }
+    }
+}
+
+pub(super) fn require_account_id(
+    value: &str,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.trim().is_empty()
+        || value.len() > 128
+        || value.chars().any(char::is_control)
+        || !value.starts_with("acct_")
+    {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+pub(super) fn parse_concurrency_limit(
+    value: Option<u64>,
+) -> Result<Option<AccountConcurrencyLimit>, WireValidationError> {
+    value
+        .map(|value| {
+            u32::try_from(value)
+                .ok()
+                .and_then(AccountConcurrencyLimit::new)
+                .ok_or_else(|| WireValidationError::new("concurrencyLimit"))
+        })
+        .transpose()
+}
+
+pub(super) fn deserialize_required_nullable<'de, D>(
+    deserializer: D,
+) -> Result<Option<u64>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Option::<u64>::deserialize(deserializer)
+}
+
+pub(super) fn parse_account_weight(value: u64) -> Result<AccountWeight, WireValidationError> {
+    u16::try_from(value)
+        .ok()
+        .and_then(AccountWeight::new)
+        .ok_or_else(|| WireValidationError::new("weight"))
+}
+
+pub(super) fn validate_wire_group_ids(
+    values: &[String],
+) -> Result<Vec<AccountGroupId>, WireValidationError> {
+    if values.len() > MAX_ACCOUNT_GROUP_BATCH
+        || values.iter().collect::<BTreeSet<_>>().len() != values.len()
+    {
+        return Err(WireValidationError::new("groupIds"));
+    }
+    values
+        .iter()
+        .cloned()
+        .map(|value| AccountGroupId::new(value).map_err(|_| WireValidationError::new("groupIds")))
+        .collect()
+}
+
+fn provider_document(
+    value: Value,
+    field: &'static str,
+) -> Result<ProviderDocument, WireValidationError> {
+    match value {
+        Value::Object(document) => Ok(ProviderDocument::new(OpaqueProviderData::new(document))),
+        _ => Err(WireValidationError::new(field)),
+    }
+}
+
+fn require_wire_id(value: &str, field: &'static str) -> Result<(), WireValidationError> {
+    require_text(value, MAX_ID_BYTES, field)?;
+    if value.starts_with("__")
+        || !value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.' | b':'))
+    {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn require_text(
+    value: &str,
+    max_bytes: usize,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.trim().is_empty() || value.len() > max_bytes || value.chars().any(char::is_control) {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn validate_oauth_material(
+    access_token: &str,
+    refresh_token: Option<&str>,
+    id_token: Option<&str>,
+) -> Result<(), WireValidationError> {
+    if access_token.len() > MAX_ACCESS_TOKEN_BYTES
+        || !valid_visible_ascii(access_token)
+        || !valid_compact_jwt_shape(access_token)
+    {
+        return Err(WireValidationError::new("accessToken"));
+    }
+    if refresh_token.is_some_and(|token| {
+        token.len() > MAX_REFRESH_TOKEN_BYTES
+            || !valid_visible_ascii(token)
+            || token == access_token
+    }) {
+        return Err(WireValidationError::new("refreshToken"));
+    }
+    if id_token.is_some_and(|token| {
+        token.len() > MAX_ID_TOKEN_BYTES
+            || !valid_visible_ascii(token)
+            || !valid_compact_jwt_shape(token)
+    }) {
+        return Err(WireValidationError::new("idToken"));
+    }
+    Ok(())
+}
+
+fn valid_compact_jwt_shape(value: &str) -> bool {
+    let mut segments = value.split('.');
+    matches!(
+        (segments.next(), segments.next(), segments.next(), segments.next()),
+        (Some(header), Some(payload), Some(signature), None)
+            if !header.is_empty() && !payload.is_empty() && !signature.is_empty()
+    )
+}
+
+fn valid_visible_ascii(value: &str) -> bool {
+    !value.is_empty() && value.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
+}
+
+pub(super) fn provider_document_value(document: ProviderDocument) -> Value {
+    Value::Object(document.into_provider_data().into_inner())
+}
@@ -0,0 +1,573 @@
+//! 账号管理路由与 HTTP handler 编排。
+
+use super::*;
+
+/// 构造统一账号管理路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/accounts", get(list_accounts::<S>))
+        .route("/api/admin/accounts/detail", get(account_detail::<S>))
+        .route("/api/admin/accounts/export", get(export_accounts::<S>))
+        .route("/api/admin/accounts/import", post(import_accounts::<S>))
+        .route("/api/admin/accounts/refresh", post(refresh_account::<S>))
+        .route("/api/admin/accounts/recover", post(recover_account::<S>))
+        .route("/api/admin/accounts/rotate", post(rotate_account::<S>))
+        .route("/api/admin/accounts/update", post(update_account::<S>))
+        .route("/api/admin/accounts/delete", post(delete_accounts::<S>))
+        .route(
+            "/api/admin/accounts/batch-update",
+            post(batch_update_accounts::<S>),
+        )
+        .route("/api/admin/accounts/quota", get(account_quota::<S>))
+        .route(
+            "/api/admin/accounts/profile-statistics",
+            get(account_profile_statistics::<S>),
+        )
+        .route(
+            "/api/admin/accounts/profile-avatar",
+            get(account_profile_avatar::<S>),
+        )
+        .route(
+            "/api/admin/accounts/reset-credits",
+            get(account_reset_credits::<S>).post(consume_account_reset_credit::<S>),
+        )
+        .route(
+            "/api/admin/accounts/quota/refresh",
+            post(refresh_account_quota::<S>),
+        )
+        .route("/api/admin/accounts/models", get(account_models::<S>))
+        .route(
+            "/api/admin/accounts/models/refresh",
+            post(refresh_account_models::<S>),
+        )
+        .route(
+            "/api/admin/accounts/connection-test",
+            get(test_account_connection::<S>),
+        )
+        .route(
+            "/api/admin/accounts/oauth/start",
+            post(start_account_authorization::<S>),
+        )
+        .route(
+            "/api/admin/accounts/oauth/complete",
+            post(complete_account_authorization::<S>),
+        )
+}
+
+async fn batch_update_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<BatchUpdateAccountsRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .batch_update(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BatchUpdatedAccountsData::from(result)),
+    ))
+}
+
+async fn list_accounts<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ListQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = query.validate().map_err(map_wire_error)?;
+    let page = command.page;
+    let page_size = command.page_size.get();
+    let result = state
+        .admin_services()
+        .accounts()
+        .list(command)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_page_data(result, page, page_size, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_detail<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn export_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountExportQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let ids = query.into_ids().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .export(&auth.context().mutation_context(), ids)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountExportData::from_result(result);
+    let mut response = AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)).into_response();
+    response
+        .headers_mut()
+        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+    Ok(response)
+}
+
+async fn import_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountImportRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .import_document(command)
+                .await
+        }
+        AccountProvider::Xai => state.admin_services().xai().import_document(command).await,
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountImportData::from_result(result)),
+    ))
+}
+
+async fn start_account_authorization<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<StartAccountAuthorizationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .start_authorization(command)
+                .await
+        }
+        AccountProvider::Xai => {
+            state
+                .admin_services()
+                .xai()
+                .start_authorization(command)
+                .await
+        }
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountAuthorizationData::from(result)),
+    ))
+}
+
+async fn complete_account_authorization<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<CompleteAccountAuthorizationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .complete_authorization(command)
+                .await
+        }
+        AccountProvider::Xai => {
+            state
+                .admin_services()
+                .xai()
+                .complete_authorization(command)
+                .await
+        }
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountMutationData::from(result)),
+    ))
+}
+
+async fn rotate_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RotateAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .openai()
+        .rotate(command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountMutationData::from(result)),
+    ))
+}
+
+async fn update_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .update(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(UpdatedAccountData::from(result)),
+    ))
+}
+
+async fn delete_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountDeletionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => state.admin_services().openai().delete(command).await,
+        AccountProvider::Xai => state.admin_services().xai().delete(command).await,
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountDeletionData::from(result)),
+    ))
+}
+
+async fn refresh_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountRefreshRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .refresh(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_refresh_data(result, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn recover_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .recover(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_refresh_data(result, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_quota<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_profile_statistics<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .profile_statistics(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountProfileStatisticsData::from(result)),
+    ))
+}
+
+async fn account_profile_avatar<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountProfileAvatarQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let avatar = state
+        .admin_services()
+        .accounts()
+        .profile_avatar(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(profile_avatar_response(avatar))
+}
+
+/// 将 Provider 头像流投影为受保护的同源 HTTP 响应。
+#[must_use]
+pub fn profile_avatar_response(avatar: ProviderProfileAvatar) -> Response {
+    let ProviderProfileAvatar {
+        content_type,
+        content_length,
+        etag,
+        body,
+    } = avatar;
+    let mut response = Response::new(Body::from_stream(body));
+    *response.status_mut() = StatusCode::OK;
+    let headers = response.headers_mut();
+    headers.insert(
+        header::CONTENT_TYPE,
+        content_type
+            .and_then(|value| HeaderValue::from_str(&value).ok())
+            .unwrap_or_else(|| HeaderValue::from_static("application/octet-stream")),
+    );
+    if let Some(value) =
+        content_length.and_then(|length| HeaderValue::from_str(&length.to_string()).ok())
+    {
+        headers.insert(header::CONTENT_LENGTH, value);
+    }
+    if let Some(value) = etag.and_then(|value| HeaderValue::from_str(&value).ok()) {
+        headers.insert(header::ETAG, value);
+    }
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("private, max-age=3600"),
+    );
+    headers.insert(
+        HeaderName::from_static("x-content-type-options"),
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        HeaderName::from_static("cross-origin-resource-policy"),
+        HeaderValue::from_static("same-origin"),
+    );
+    headers.insert(
+        HeaderName::from_static("content-security-policy"),
+        HeaderValue::from_static("sandbox; default-src 'none'"),
+    );
+    response
+}
+
+async fn refresh_account_quota<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, true)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_reset_credits<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .reset_credits(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountResetCreditsData::from(result)),
+    ))
+}
+
+async fn consume_account_reset_credit<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountResetCreditConsumeRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .consume_reset_credit(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountResetCreditResultData::from(result)),
+    ))
+}
+
+async fn account_models<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .models(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_models_data(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn refresh_account_models<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .models(&account_id, true)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_models_data(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn test_account_connection<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountTestQuery>,
+) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (account_id, upstream_model) = query.into_command().map_err(map_wire_error)?;
+    let stream = state
+        .admin_services()
+        .accounts()
+        .test_connection(account_id, upstream_model)
+        .await
+        .map_err(map_service_error)?
+        .map(|event| {
+            let event = AccountConnectionTestEvent::from(event);
+            let data = serde_json::to_string(&event.data).unwrap_or_else(|_| "{}".to_owned());
+            Ok(Event::default().data(data))
+        });
+    Ok(Sse::new(stream).keep_alive(KeepAlive::default()))
+}
@@ -0,0 +1,81 @@
+//! 管理端账号目录的 HTTP 合同、凭据动作、路由处理与安全响应投影。
+
+use std::{collections::BTreeSet, convert::Infallible, fmt};
+
+use axum::{
+    Router,
+    body::Body,
+    extract::State,
+    http::{HeaderName, HeaderValue, StatusCode, header},
+    response::{
+        IntoResponse, Response,
+        sse::{Event, KeepAlive, Sse},
+    },
+    routing::{get, post},
+};
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use chrono::{DateTime, FixedOffset, Utc};
+use futures::{Stream, StreamExt as _};
+use gateway_admin::model::{
+    AdminError as AdminServiceError, PageSize,
+    accounts::{
+        AccountConcurrencyLimit, AccountConnectionTestEvent as DomainConnectionTestEvent,
+        AccountCost, AccountGroupFilter, AccountListQuery, AccountModelUsage, AccountSort,
+        AccountSortField, AccountStatus as DomainAccountStatus, AccountUpdateResult, AccountUsage,
+        AccountWeight, AccountsUpdateResult, BatchUpdateAccounts, SortDirection, UpdateAccount,
+    },
+    provider_credentials::{
+        AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
+        AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+        CredentialDeletion, CredentialDeletionResult, CredentialImportResult, CredentialMutation,
+        CredentialMutationResult, ImportCredentials, ProviderDocument, ProviderModels,
+        ProviderProfileActivityInsights, ProviderProfileAvatar, ProviderProfileDailyUsage,
+        ProviderProfileInvocation, ProviderProfileStatistics, ProviderProfileStatisticsSummary,
+        ProviderQuota, ProviderQuotaWindow, ProviderResetCredit, ProviderResetCreditResult,
+        ProviderResetCredits, RotateCredential, StartAuthorization,
+    },
+};
+use gateway_core::{
+    account::{OpaqueProviderData, ProviderAccountId},
+    routing::{AccountGroupId, ProviderKind, UpstreamModelId},
+};
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::{Map, Value};
+use uuid::{Uuid, Version};
+
+use super::presenter::{format_compact_number, format_decimal_currency, format_number};
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta, WireValidationError,
+};
+
+const DEFAULT_PAGE_SIZE: u32 = 50;
+const MAX_PAGE_SIZE: u32 = 200;
+const MAX_SEARCH_BYTES: usize = 256;
+const MAX_ID_BYTES: usize = 256;
+const MAX_NAME_BYTES: usize = 512;
+const MAX_IMPORT_DATA_BYTES: usize = 64 * 1024 * 1024;
+const MAX_ACCESS_TOKEN_BYTES: usize = 16 * 1024;
+const MAX_REFRESH_TOKEN_BYTES: usize = 64 * 1024;
+const MAX_ID_TOKEN_BYTES: usize = 16 * 1024;
+const MAX_CALLBACK_URL_BYTES: usize = 64 * 1024;
+const MAX_ACCOUNT_DELETE_BATCH: usize = 200;
+const MAX_ACCOUNT_GROUP_BATCH: usize = 1000;
+const MAX_AVATAR_VERSION_BYTES: usize = 32;
+
+mod credentials;
+mod handlers;
+mod presenter;
+mod wire;
+
+pub use credentials::*;
+pub use handlers::{profile_avatar_response, router};
+pub(super) use presenter::quota_window_view;
+pub use wire::*;
+
+use credentials::{
+    AccountProvider, deserialize_required_nullable, parse_account_weight, parse_concurrency_limit,
+    provider_document_value, require_account_id, validate_wire_group_ids,
+};
+use presenter::*;
+use wire::BatchUpdatedAccountsData;
@@ -0,0 +1,417 @@
+//! Admin 领域结果到安全 HTTP wire 的展示投影。
+
+use super::*;
+
+pub(super) fn account_page_data(
+    result: AccountDirectoryPage,
+    page: u32,
+    page_size: u16,
+    now: DateTime<Utc>,
+) -> AccountPageData {
+    let total_pages = if result.total == 0 {
+        0
+    } else {
+        u32::try_from(result.total.div_ceil(u64::from(page_size))).unwrap_or(u32::MAX)
+    };
+    AccountPageData {
+        items: result
+            .items
+            .into_iter()
+            .map(|item| account_view(item, now))
+            .collect(),
+        page: PageMeta::new(page, u32::from(page_size), result.total, total_pages),
+        summary: AccountSummaryView {
+            total: result.summary.total,
+            normal: result.summary.normal,
+            quota_exhausted: result.summary.quota_exhausted,
+            rate_limited: result.summary.rate_limited,
+            disabled: result.summary.disabled,
+            error: result.summary.error,
+        },
+    }
+}
+
+pub(super) fn account_refresh_data(
+    result: AccountRefreshResult,
+    now: DateTime<Utc>,
+) -> AccountRefreshData {
+    AccountRefreshData {
+        account: account_view(result.account, now),
+    }
+}
+
+pub(super) fn account_models_data(result: ProviderModels) -> AccountModelsData {
+    AccountModelsData {
+        models: result
+            .models
+            .into_iter()
+            .map(|model| {
+                let id = model.id.to_string();
+                AccountModelView {
+                    label: id.clone(),
+                    id,
+                }
+            })
+            .collect(),
+    }
+}
+
+pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> AccountView {
+    let AccountDirectoryItem {
+        account,
+        projection,
+        usage,
+        quota,
+    } = item;
+    let status = projection.status.as_str().to_owned();
+    let rate_limited_until = projection.rate_limited_until.map(DateTime::<Utc>::from);
+    let expires_at = account.access_token_expires_at.as_ref().map(china_rfc3339);
+    let added_at = china_rfc3339(&account.created_at);
+    let updated_at = china_rfc3339(&account.updated_at);
+    let (quota, refresh_token_expires_at) = account_quota_view(quota, rate_limited_until, now);
+    AccountView {
+        id: account.id.clone(),
+        name: account.name,
+        provider: account.provider_kind.to_string(),
+        groups: account
+            .groups
+            .into_iter()
+            .map(|group| AccountGroupRefView {
+                id: group.id.to_string(),
+                name: group.name,
+                color: group.color.as_str().to_owned(),
+                enabled: group.enabled,
+            })
+            .collect(),
+        resource_ref: account.id,
+        email: account.email,
+        account_id: account.upstream_account_id,
+        user_id: account.upstream_user_id,
+        label: None,
+        plan_type: account.plan_type,
+        authentication_kind: account.authentication_kind,
+        has_refresh_token: account.has_refresh_token,
+        status,
+        error_reason: projection
+            .error_reason
+            .map(|reason| reason.as_str().to_owned()),
+        error_message: projection.error_message,
+        enabled: account.enabled,
+        concurrency_limit: account.concurrency_limit.map(|limit| limit.get()),
+        weight: account.weight.get(),
+        access_token_expires_at: expires_at,
+        access_token_expires_at_display: account
+            .access_token_expires_at
+            .as_ref()
+            .map(china_datetime),
+        refresh_token_expires_at,
+        next_refresh_at: account.next_refresh_at.map(|value| china_rfc3339(&value)),
+        added_at,
+        added_at_display: china_datetime(&account.created_at),
+        updated_at,
+        updated_at_display: china_datetime(&account.updated_at),
+        quota,
+        usage: account_usage_view(usage, now),
+    }
+}
+
+pub(super) fn account_quota_view(
+    mut quota: ProviderQuota,
+    rate_limited_until: Option<DateTime<Utc>>,
+    now: DateTime<Utc>,
+) -> (AccountQuotaView, Option<String>) {
+    quota.apply_limit_reached_display();
+    let refresh_token_expires_at = quota
+        .refresh_token_expires_at
+        .map(|value| china_rfc3339(&value));
+    let refreshed_at_display = quota
+        .observed_at
+        .map_or_else(|| "—".to_owned(), |value| relative_time(value, now));
+    let windows = quota.windows.into_iter().map(quota_window_view).collect();
+    let rate_limited_until = rate_limited_until.map(|until| china_datetime(&until));
+    (
+        AccountQuotaView {
+            refreshed_at_display,
+            limit_reached: quota.limit_reached,
+            rate_limited_until,
+            windows,
+        },
+        refresh_token_expires_at,
+    )
+}
+
+pub(crate) fn quota_window_view(window: ProviderQuotaWindow) -> AccountQuotaWindowView {
+    let ProviderQuotaWindow {
+        key,
+        group,
+        label,
+        limit_id,
+        limit_name,
+        role,
+        local_usage_attribution: _,
+        window_seconds,
+        used_percent,
+        reset_at,
+        limit_reached,
+        local_usage,
+        provider_data: _,
+    } = window;
+    let label_display = limit_name
+        .as_ref()
+        .map_or_else(|| label.clone(), |name| format!("{name} · {label}"));
+    AccountQuotaWindowView {
+        label_display,
+        window_label_display: label,
+        key,
+        group,
+        limit_id,
+        limit_name,
+        role: role.map(|value| value.as_str().to_owned()),
+        window_seconds,
+        used_percent,
+        used_percent_display: used_percent
+            .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
+        limit_reached,
+        local_usage: local_usage.as_ref().map(quota_local_usage),
+        reset_at_display: reset_at.map_or_else(|| "—".to_owned(), |value| china_datetime(&value)),
+    }
+}
+
+pub(super) fn quota_local_usage(usage: &AccountUsage) -> Value {
+    let total_tokens = usage.total_tokens.unwrap_or_default();
+    serde_json::json!({
+        "requestCount": usage.request_count,
+        "requestCountDisplay": format_number(usage.request_count),
+        "inputTokens": usage.input_tokens.unwrap_or_default(),
+        "inputTokensDisplay": display_optional_tokens(usage.input_tokens),
+        "outputTokens": usage.output_tokens.unwrap_or_default(),
+        "outputTokensDisplay": display_optional_tokens(usage.output_tokens),
+        "cachedTokens": usage.cached_tokens.unwrap_or_default(),
+        "cachedTokensDisplay": display_optional_tokens(usage.cached_tokens),
+        "imageInputTokens": usage.image_input_tokens.unwrap_or_default(),
+        "imageInputTokensDisplay": display_optional_tokens(usage.image_input_tokens),
+        "imageOutputTokens": usage.image_output_tokens.unwrap_or_default(),
+        "imageOutputTokensDisplay": display_optional_tokens(usage.image_output_tokens),
+        "imageRequestCount": usage.image_request_count,
+        "imageRequestFailedCount": usage.image_request_failed_count,
+        "totalTokens": total_tokens,
+        "totalTokensDisplay": format_compact_number(total_tokens),
+        "requestBuckets": usage.request_buckets.iter().map(|bucket| serde_json::json!({
+            "bucketStart": bucket.bucket_start,
+            "requestCount": bucket.request_count,
+        })).collect::<Vec<_>>(),
+    })
+}
+
+pub(super) fn account_usage_view(
+    usage: Option<AccountUsage>,
+    now: DateTime<Utc>,
+) -> AccountUsageView {
+    let Some(usage) = usage else {
+        return empty_account_usage();
+    };
+    let known_count = usage
+        .cost_coverage
+        .provider_reported_count
+        .saturating_add(usage.cost_coverage.calculated_count);
+    let cost_estimate_status = if known_count == 0 {
+        "unknown"
+    } else if usage.cost_coverage.unavailable_count > 0 {
+        "partial"
+    } else {
+        "known"
+    };
+    AccountUsageView {
+        request_count: Some(usage.request_count),
+        request_count_display: format_number(usage.request_count),
+        input_tokens: usage.input_tokens,
+        input_tokens_display: display_optional_tokens(usage.input_tokens),
+        output_tokens: usage.output_tokens,
+        output_tokens_display: display_optional_tokens(usage.output_tokens),
+        cached_tokens: usage.cached_tokens,
+        cached_tokens_display: display_optional_tokens(usage.cached_tokens),
+        reasoning_tokens: usage.reasoning_tokens,
+        reasoning_tokens_display: display_optional_tokens(usage.reasoning_tokens),
+        image_input_tokens: usage.image_input_tokens,
+        image_input_tokens_display: display_optional_tokens(usage.image_input_tokens),
+        image_output_tokens: usage.image_output_tokens,
+        image_output_tokens_display: display_optional_tokens(usage.image_output_tokens),
+        image_request_count: Some(usage.image_request_count),
+        image_request_count_display: format_number(usage.image_request_count),
+        image_request_failed_count: Some(usage.image_request_failed_count),
+        image_request_failed_count_display: format_number(usage.image_request_failed_count),
+        total_tokens: usage.total_tokens,
+        total_tokens_display: display_optional_tokens(usage.total_tokens),
+        created_tokens: usage.cache_write_tokens,
+        created_tokens_display: display_optional_tokens(usage.cache_write_tokens),
+        read_tokens: usage.cached_tokens,
+        read_tokens_display: display_optional_tokens(usage.cached_tokens),
+        last_used_at: usage.last_used_at.map(|value| china_rfc3339(&value)),
+        last_used_at_display: usage
+            .last_used_at
+            .map_or_else(|| "—".to_owned(), |value| relative_time(value, now)),
+        cost_estimate_status: cost_estimate_status.to_owned(),
+        known_cost_count: Some(known_count),
+        partial_cost_count: Some(u64::from(cost_estimate_status == "partial")),
+        unknown_cost_count: Some(usage.cost_coverage.unavailable_count),
+        costs: usage.costs.iter().map(account_currency_cost_view).collect(),
+        models: usage
+            .models
+            .into_iter()
+            .map(|model| account_model_usage_view(model, now))
+            .collect(),
+    }
+}
+
+pub(super) fn account_model_usage_view(
+    usage: AccountModelUsage,
+    now: DateTime<Utc>,
+) -> ModelUsageView {
+    let known_count = usage
+        .cost_coverage
+        .provider_reported_count
+        .saturating_add(usage.cost_coverage.calculated_count);
+    let cost_estimate_status = if known_count == 0 {
+        "unknown"
+    } else if usage.cost_coverage.unavailable_count > 0 {
+        "partial"
+    } else {
+        "known"
+    };
+    let usd = usage
+        .costs
+        .iter()
+        .find(|cost| cost.currency.eq_ignore_ascii_case("USD"));
+    ModelUsageView {
+        model: usage.model,
+        request_count: usage.request_count,
+        request_count_display: format_number(usage.request_count),
+        success_rate: (usage.request_count > 0)
+            .then(|| usage.success_count as f64 * 100.0 / usage.request_count as f64),
+        success_rate_display: if usage.request_count == 0 {
+            "—".to_owned()
+        } else {
+            format!(
+                "{:.1}%",
+                usage.success_count as f64 * 100.0 / usage.request_count as f64
+            )
+        },
+        input_tokens: usage.input_tokens,
+        input_tokens_display: display_optional_tokens(usage.input_tokens),
+        output_tokens: usage.output_tokens,
+        output_tokens_display: display_optional_tokens(usage.output_tokens),
+        cached_tokens: usage.cached_tokens,
+        cached_tokens_display: display_optional_tokens(usage.cached_tokens),
+        image_input_tokens: usage.image_input_tokens,
+        image_input_tokens_display: display_optional_tokens(usage.image_input_tokens),
+        image_output_tokens: usage.image_output_tokens,
+        image_output_tokens_display: display_optional_tokens(usage.image_output_tokens),
+        image_request_count: usage.image_request_count,
+        image_request_count_display: format_number(usage.image_request_count),
+        image_request_failed_count: usage.image_request_failed_count,
+        image_request_failed_count_display: format_number(usage.image_request_failed_count),
+        total_tokens: usage.total_tokens,
+        total_tokens_display: display_optional_tokens(usage.total_tokens),
+        billing_amount_usd: usd.map(|cost| cost.amount.as_str().to_owned()),
+        billing_amount_usd_display: usd.map_or_else(
+            || "—".to_owned(),
+            |cost| format_decimal_currency(cost.amount.as_str(), "USD"),
+        ),
+        cost_estimate_status: cost_estimate_status.to_owned(),
+        known_cost_count: known_count,
+        partial_cost_count: u64::from(cost_estimate_status == "partial"),
+        unknown_cost_count: usage.cost_coverage.unavailable_count,
+        costs: usage.costs.iter().map(account_currency_cost_view).collect(),
+        last_used_at: china_rfc3339(&usage.last_used_at),
+        last_used_at_display: relative_time(usage.last_used_at, now),
+    }
+}
+
+pub(super) fn account_currency_cost_view(cost: &AccountCost) -> CurrencyCostView {
+    CurrencyCostView {
+        currency: cost.currency.clone(),
+        estimated_amount: cost.amount.as_str().to_owned(),
+        estimated_amount_display: format_decimal_currency(cost.amount.as_str(), &cost.currency),
+    }
+}
+
+pub(super) fn display_optional_tokens(value: Option<u64>) -> String {
+    value.map_or_else(|| "—".to_owned(), format_compact_number)
+}
+
+pub(super) fn empty_account_usage() -> AccountUsageView {
+    AccountUsageView {
+        request_count: None,
+        request_count_display: "—".to_owned(),
+        input_tokens: None,
+        input_tokens_display: "—".to_owned(),
+        output_tokens: None,
+        output_tokens_display: "—".to_owned(),
+        cached_tokens: None,
+        cached_tokens_display: "—".to_owned(),
+        reasoning_tokens: None,
+        reasoning_tokens_display: "—".to_owned(),
+        image_input_tokens: None,
+        image_input_tokens_display: "—".to_owned(),
+        image_output_tokens: None,
+        image_output_tokens_display: "—".to_owned(),
+        image_request_count: None,
+        image_request_count_display: "—".to_owned(),
+        image_request_failed_count: None,
+        image_request_failed_count_display: "—".to_owned(),
+        total_tokens: None,
+        total_tokens_display: "—".to_owned(),
+        created_tokens: None,
+        created_tokens_display: "—".to_owned(),
+        read_tokens: None,
+        read_tokens_display: "—".to_owned(),
+        last_used_at: None,
+        last_used_at_display: "—".to_owned(),
+        cost_estimate_status: "unavailable".to_owned(),
+        known_cost_count: None,
+        partial_cost_count: None,
+        unknown_cost_count: None,
+        costs: Vec::new(),
+        models: Vec::new(),
+    }
+}
+
+pub(super) fn relative_time(value: DateTime<Utc>, now: DateTime<Utc>) -> String {
+    let elapsed = now.signed_duration_since(value);
+    if elapsed.num_seconds() < 0 {
+        return china_datetime(&value);
+    }
+    if elapsed.num_seconds() < 60 {
+        return "刚刚".to_owned();
+    }
+    if elapsed.num_minutes() < 60 {
+        return format!("{} 分钟前", elapsed.num_minutes());
+    }
+    if elapsed.num_hours() < 24 {
+        return format!("{} 小时前", elapsed.num_hours());
+    }
+    format!("{} 天前", elapsed.num_days())
+}
+
+pub(super) fn china_offset() -> FixedOffset {
+    FixedOffset::east_opt(8 * 60 * 60).expect("UTC+8 is a valid fixed offset")
+}
+
+pub(super) fn china_rfc3339(value: &DateTime<Utc>) -> String {
+    value.with_timezone(&china_offset()).to_rfc3339()
+}
+
+pub(super) fn china_datetime(value: &DateTime<Utc>) -> String {
+    value
+        .with_timezone(&china_offset())
+        .format("%Y-%m-%d %H:%M:%S")
+        .to_string()
+}
+
+pub(super) fn map_wire_error(error: WireValidationError) -> AdminError {
+    AdminError::bad_request(format!("{} 字段不合法", error.field()))
+}
+
+pub(super) fn map_service_error(error: AdminServiceError) -> AdminError {
+    super::super::wire::map_admin_service_error(error)
+}
@@ -0,0 +1,840 @@
+//! 账号管理请求、响应与查询 wire contract。
+
+use super::*;
+
+/// 账号列表查询参数。
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ListQuery {
+    pub page: Option<u32>,
+    pub page_size: Option<u32>,
+    pub provider: Option<String>,
+    pub group_id: Option<String>,
+    pub search: Option<String>,
+    pub status: Option<String>,
+    pub sort_by: Option<String>,
+    pub sort_direction: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct BatchUpdateAccountsRequest {
+    pub account_ids: Vec<String>,
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct BatchUpdatedAccountsData {
+    account_ids: Vec<String>,
+    config_revision: u64,
+}
+
+impl From<AccountsUpdateResult> for BatchUpdatedAccountsData {
+    fn from(result: AccountsUpdateResult) -> Self {
+        Self {
+            account_ids: result
+                .account_ids
+                .into_iter()
+                .map(|id| id.to_string())
+                .collect(),
+            config_revision: result.config_revision.get(),
+        }
+    }
+}
+
+impl BatchUpdateAccountsRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if self.account_ids.is_empty()
+            || self.account_ids.len() > MAX_ACCOUNT_GROUP_BATCH
+            || self
+                .account_ids
+                .iter()
+                .any(|id| require_account_id(id, "accountIds").is_err())
+            || self.account_ids.iter().collect::<BTreeSet<_>>().len() != self.account_ids.len()
+        {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        validate_wire_group_ids(&self.group_ids)?;
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<BatchUpdateAccounts, WireValidationError> {
+        self.validate()?;
+        Ok(BatchUpdateAccounts {
+            account_ids: self.account_ids,
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+impl ListQuery {
+    /// 解析并校验全部 wire 字段，生成 Admin 查询命令。
+    pub fn validate(self) -> Result<AccountListQuery, WireValidationError> {
+        let page = self.page.unwrap_or(1);
+        if page == 0 {
+            return Err(WireValidationError::new("page"));
+        }
+        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
+        if page_size == 0 || page_size > MAX_PAGE_SIZE {
+            return Err(WireValidationError::new("pageSize"));
+        }
+        let provider_kind = parse_provider(self.provider.as_deref().unwrap_or("all"))?;
+        let group_filter = match self.group_id.as_deref().map(str::trim) {
+            None | Some("") => None,
+            Some("ungrouped") => Some(AccountGroupFilter::Ungrouped),
+            Some(value) => Some(AccountGroupFilter::Group(
+                AccountGroupId::new(value.to_owned())
+                    .map_err(|_| WireValidationError::new("groupId"))?,
+            )),
+        };
+        let search = self
+            .search
+            .map(|value| value.trim().to_owned())
+            .filter(|value| !value.is_empty());
+        if search.as_deref().is_some_and(|value| {
+            value.len() > MAX_SEARCH_BYTES || value.chars().any(char::is_control)
+        }) {
+            return Err(WireValidationError::new("search"));
+        }
+        let status = match self.status.as_deref().map(str::trim) {
+            None | Some("") => None,
+            Some(value) => Some(
+                DomainAccountStatus::parse(&value.to_ascii_lowercase())
+                    .ok_or_else(|| WireValidationError::new("status"))?,
+            ),
+        };
+        let sort = match (self.sort_by.as_deref(), self.sort_direction.as_deref()) {
+            (None, None) => None,
+            (Some(field), Some(direction)) => Some(AccountSort {
+                field: parse_sort_field(field).ok_or_else(|| WireValidationError::new("sortBy"))?,
+                direction: parse_sort_direction(direction)
+                    .ok_or_else(|| WireValidationError::new("sortDirection"))?,
+            }),
+            _ => return Err(WireValidationError::new("sort")),
+        };
+        Ok(AccountListQuery {
+            page,
+            page_size: PageSize::new(
+                u16::try_from(page_size).map_err(|_| WireValidationError::new("pageSize"))?,
+            )
+            .map_err(|_| WireValidationError::new("pageSize"))?,
+            provider_kind,
+            group_filter,
+            search,
+            status,
+            sort,
+        })
+    }
+}
+
+fn parse_provider(value: &str) -> Result<Option<ProviderKind>, WireValidationError> {
+    let value = value.trim();
+    if value.is_empty() || value.eq_ignore_ascii_case("all") {
+        return Ok(None);
+    }
+    ProviderKind::new(value.to_owned())
+        .map(Some)
+        .map_err(|_| WireValidationError::new("provider"))
+}
+
+fn parse_sort_field(value: &str) -> Option<AccountSortField> {
+    match value.trim() {
+        "email" => Some(AccountSortField::Email),
+        "status" => Some(AccountSortField::Status),
+        "planType" => Some(AccountSortField::PlanType),
+        "usage" => Some(AccountSortField::Usage),
+        "lastUsedAt" => Some(AccountSortField::LastUsedAt),
+        "expiresAt" => Some(AccountSortField::ExpiresAt),
+        _ => None,
+    }
+}
+
+fn parse_sort_direction(value: &str) -> Option<SortDirection> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "asc" => Some(SortDirection::Asc),
+        "desc" => Some(SortDirection::Desc),
+        _ => None,
+    }
+}
+
+/// 账号列表响应数据。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountPageData {
+    pub items: Vec<AccountView>,
+    pub page: PageMeta,
+    pub summary: AccountSummaryView,
+}
+
+/// 账号概览计数。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountSummaryView {
+    pub total: u64,
+    pub normal: u64,
+    pub quota_exhausted: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
+}
+
+/// 一条安全账号视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountView {
+    pub id: String,
+    pub name: String,
+    pub provider: String,
+    pub groups: Vec<AccountGroupRefView>,
+    pub resource_ref: String,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub user_id: Option<String>,
+    pub label: Option<String>,
+    pub plan_type: Option<String>,
+    pub authentication_kind: String,
+    pub has_refresh_token: bool,
+    pub status: String,
+    /// `status == "error"` 时的具体原因；其余状态为 `null`。
+    pub error_reason: Option<String>,
+    /// 最近一次失败的上游错误描述；仅错误状态存在。
+    pub error_message: Option<String>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<u32>,
+    pub weight: u16,
+    pub access_token_expires_at: Option<String>,
+    pub access_token_expires_at_display: Option<String>,
+    pub refresh_token_expires_at: Option<String>,
+    pub next_refresh_at: Option<String>,
+    pub added_at: String,
+    pub added_at_display: String,
+    pub updated_at: String,
+    pub updated_at_display: String,
+    pub quota: AccountQuotaView,
+    pub usage: AccountUsageView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountGroupRefView {
+    pub id: String,
+    pub name: String,
+    pub color: String,
+    pub enabled: bool,
+}
+
+/// Provider quota 安全视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaView {
+    pub refreshed_at_display: String,
+    pub limit_reached: bool,
+    /// 429 临时限流（Redis 冷却）到期时间展示；非限流中为 `null`。
+    pub rate_limited_until: Option<String>,
+    pub windows: Vec<AccountQuotaWindowView>,
+}
+
+/// 一个 quota 时间窗口。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaWindowView {
+    pub key: String,
+    pub group: String,
+    pub limit_id: Option<String>,
+    pub limit_name: Option<String>,
+    pub role: Option<String>,
+    pub window_seconds: Option<u64>,
+    pub label_display: String,
+    pub window_label_display: String,
+    pub used_percent: Option<f64>,
+    pub used_percent_display: String,
+    pub limit_reached: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub local_usage: Option<serde_json::Value>,
+    pub reset_at_display: String,
+}
+
+/// 账号观测用量。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountUsageView {
+    pub request_count: Option<u64>,
+    pub request_count_display: String,
+    pub input_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens: Option<u64>,
+    pub output_tokens_display: String,
+    pub cached_tokens: Option<u64>,
+    pub cached_tokens_display: String,
+    pub reasoning_tokens: Option<u64>,
+    pub reasoning_tokens_display: String,
+    pub image_input_tokens: Option<u64>,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens: Option<u64>,
+    pub image_output_tokens_display: String,
+    pub image_request_count: Option<u64>,
+    pub image_request_count_display: String,
+    pub image_request_failed_count: Option<u64>,
+    pub image_request_failed_count_display: String,
+    pub total_tokens: Option<u64>,
+    pub total_tokens_display: String,
+    pub created_tokens: Option<u64>,
+    pub created_tokens_display: String,
+    pub read_tokens: Option<u64>,
+    pub read_tokens_display: String,
+    pub last_used_at: Option<String>,
+    pub last_used_at_display: String,
+    pub cost_estimate_status: String,
+    pub known_cost_count: Option<u64>,
+    pub partial_cost_count: Option<u64>,
+    pub unknown_cost_count: Option<u64>,
+    pub costs: Vec<CurrencyCostView>,
+    pub models: Vec<ModelUsageView>,
+}
+
+/// 凭据在单个上游模型上的观测用量。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ModelUsageView {
+    pub model: String,
+    pub request_count: u64,
+    pub request_count_display: String,
+    pub success_rate: Option<f64>,
+    pub success_rate_display: String,
+    pub input_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens: Option<u64>,
+    pub output_tokens_display: String,
+    pub cached_tokens: Option<u64>,
+    pub cached_tokens_display: String,
+    pub image_input_tokens: Option<u64>,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens: Option<u64>,
+    pub image_output_tokens_display: String,
+    pub image_request_count: u64,
+    pub image_request_count_display: String,
+    pub image_request_failed_count: u64,
+    pub image_request_failed_count_display: String,
+    pub total_tokens: Option<u64>,
+    pub total_tokens_display: String,
+    pub billing_amount_usd: Option<String>,
+    pub billing_amount_usd_display: String,
+    pub cost_estimate_status: String,
+    pub known_cost_count: u64,
+    pub partial_cost_count: u64,
+    pub unknown_cost_count: u64,
+    pub costs: Vec<CurrencyCostView>,
+    pub last_used_at: String,
+    pub last_used_at_display: String,
+}
+
+/// 单一货币的可查询成本。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CurrencyCostView {
+    pub currency: String,
+    pub estimated_amount: String,
+    pub estimated_amount_display: String,
+}
+
+/// 账号详情类 GET 的固定 ID query。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountIdQuery {
+    pub account_id: String,
+}
+
+impl AccountIdQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 头像 GET 的固定 query；`version` 只参与浏览器缓存键，不进入上游请求。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountProfileAvatarQuery {
+    pub account_id: String,
+    pub version: Option<String>,
+}
+
+impl AccountProfileAvatarQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.version.as_deref().is_some_and(|version| {
+            version.is_empty()
+                || version.len() > MAX_AVATAR_VERSION_BYTES
+                || !version.bytes().all(|byte| byte.is_ascii_alphanumeric())
+        }) {
+            return Err(WireValidationError::new("version"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 敏感导出的固定 query；IDs 使用逗号分隔，禁止隐式导出全部账号。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountExportQuery {
+    pub account_ids: String,
+    pub confirm: String,
+}
+
+impl AccountExportQuery {
+    pub fn into_ids(self) -> Result<Vec<ProviderAccountId>, WireValidationError> {
+        if self.confirm != "export_sensitive_accounts" {
+            return Err(WireValidationError::new("confirm"));
+        }
+        let ids = self
+            .account_ids
+            .split(',')
+            .map(str::trim)
+            .filter(|id| !id.is_empty())
+            .map(ToOwned::to_owned)
+            .collect::<Vec<_>>();
+        if ids.is_empty()
+            || ids.len() > 200
+            || ids
+                .iter()
+                .any(|id| require_account_id(id, "accountIds").is_err())
+        {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        let unique = ids.iter().collect::<BTreeSet<_>>();
+        if unique.len() != ids.len() {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        ids.into_iter()
+            .map(|id| {
+                ProviderAccountId::new(id).map_err(|_| WireValidationError::new("accountIds"))
+            })
+            .collect()
+    }
+}
+
+/// 账号运行期动作。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountActionRequest {
+    pub account_id: String,
+}
+
+impl AccountActionRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 主动额度重置卡消费请求。幂等键由 UI 生成并在不确定重试时复用，与官方一致。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountResetCreditConsumeRequest {
+    pub account_id: String,
+    #[serde(default)]
+    pub credit_id: Option<String>,
+    pub redeem_request_id: String,
+}
+
+impl AccountResetCreditConsumeRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.credit_id.as_deref().is_some_and(|value| {
+            let value = value.trim();
+            value.is_empty() || value.len() > 512 || value.chars().any(char::is_control)
+        }) {
+            return Err(WireValidationError::new("creditId"));
+        }
+        let value = self.redeem_request_id.trim();
+        let redeem_request_id =
+            Uuid::parse_str(value).map_err(|_| WireValidationError::new("redeemRequestId"))?;
+        if redeem_request_id.get_version() != Some(Version::Random)
+            || redeem_request_id.hyphenated().to_string() != value
+        {
+            return Err(WireValidationError::new("redeemRequestId"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<ConsumeProviderResetCredit, WireValidationError> {
+        self.validate()?;
+        Ok(ConsumeProviderResetCredit {
+            account_id: ProviderAccountId::new(self.account_id)
+                .map_err(|_| WireValidationError::new("accountId"))?,
+            credit_id: self.credit_id.map(|value| value.trim().to_owned()),
+            redeem_request_id: Uuid::parse_str(&self.redeem_request_id)
+                .map_err(|_| WireValidationError::new("redeemRequestId"))?,
+        })
+    }
+}
+
+/// 手工 OAuth 刷新会变更持久 credential。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountRefreshRequest {
+    pub account_id: String,
+}
+
+impl AccountRefreshRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_command(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 连接测试 query；测试仍经唯一 Core/Provider 模型请求路径执行。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountTestQuery {
+    pub account_id: String,
+    pub model_id: String,
+}
+
+impl AccountTestQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.model_id.trim().is_empty() || self.model_id.chars().any(char::is_control) {
+            return Err(WireValidationError::new("modelId"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+    ) -> Result<(ProviderAccountId, UpstreamModelId), WireValidationError> {
+        self.validate()?;
+        Ok((
+            ProviderAccountId::new(self.account_id)
+                .map_err(|_| WireValidationError::new("accountId"))?,
+            UpstreamModelId::new(self.model_id).map_err(|_| WireValidationError::new("modelId"))?,
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountModelView {
+    pub id: String,
+    pub label: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountModelsData {
+    pub models: Vec<AccountModelView>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountRefreshData {
+    pub account: AccountView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountQuotaData {
+    pub account: AccountView,
+}
+
+/// Provider 官方个人资料统计响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileStatisticsData {
+    pub display_name: Option<String>,
+    pub username: Option<String>,
+    pub image_url: Option<String>,
+    pub has_stats_error: bool,
+    pub summary: AccountProfileStatisticsSummaryView,
+    pub daily_usage: Option<Vec<AccountProfileDailyUsageView>>,
+    pub activity_insights: AccountProfileActivityInsightsView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileStatisticsSummaryView {
+    pub total_text_tokens: Option<u64>,
+    pub peak_tokens: Option<u64>,
+    pub longest_task_duration_ms: Option<u64>,
+    pub current_streak_days: Option<u64>,
+    pub longest_streak_days: Option<u64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileDailyUsageView {
+    pub date: String,
+    pub tokens: u64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileActivityInsightsView {
+    pub fast_mode_percent: Option<f64>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_effort_percent: Option<f64>,
+    pub skills_explored: Option<u64>,
+    pub total_skills_used: Option<u64>,
+    pub total_threads: Option<u64>,
+    pub invocations: Option<Vec<AccountProfileInvocationView>>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileInvocationView {
+    #[serde(rename = "type")]
+    pub invocation_type: String,
+    pub plugin_id: Option<String>,
+    pub plugin_name: Option<String>,
+    pub skill_id: Option<String>,
+    pub skill_name: Option<String>,
+    pub usage_count: Option<u64>,
+}
+
+impl From<ProviderProfileStatistics> for AccountProfileStatisticsData {
+    fn from(statistics: ProviderProfileStatistics) -> Self {
+        Self {
+            display_name: statistics.display_name,
+            username: statistics.username,
+            image_url: statistics.image_url,
+            has_stats_error: statistics.has_stats_error,
+            summary: profile_statistics_summary_view(statistics.summary),
+            daily_usage: statistics
+                .daily_usage
+                .map(|daily| daily.into_iter().map(profile_daily_usage_view).collect()),
+            activity_insights: profile_activity_insights_view(statistics.activity_insights),
+        }
+    }
+}
+
+const fn profile_statistics_summary_view(
+    summary: ProviderProfileStatisticsSummary,
+) -> AccountProfileStatisticsSummaryView {
+    AccountProfileStatisticsSummaryView {
+        total_text_tokens: summary.total_text_tokens,
+        peak_tokens: summary.peak_tokens,
+        longest_task_duration_ms: summary.longest_task_duration_ms,
+        current_streak_days: summary.current_streak_days,
+        longest_streak_days: summary.longest_streak_days,
+    }
+}
+
+fn profile_daily_usage_view(daily: ProviderProfileDailyUsage) -> AccountProfileDailyUsageView {
+    AccountProfileDailyUsageView {
+        date: daily.date.to_string(),
+        tokens: daily.tokens,
+    }
+}
+
+fn profile_activity_insights_view(
+    insights: ProviderProfileActivityInsights,
+) -> AccountProfileActivityInsightsView {
+    AccountProfileActivityInsightsView {
+        fast_mode_percent: insights.fast_mode_percent,
+        reasoning_effort: insights.reasoning_effort,
+        reasoning_effort_percent: insights.reasoning_effort_percent,
+        skills_explored: insights.skills_explored,
+        total_skills_used: insights.total_skills_used,
+        total_threads: insights.total_threads,
+        invocations: insights.invocations.map(|invocations| {
+            invocations
+                .into_iter()
+                .map(profile_invocation_view)
+                .collect()
+        }),
+    }
+}
+
+fn profile_invocation_view(invocation: ProviderProfileInvocation) -> AccountProfileInvocationView {
+    AccountProfileInvocationView {
+        invocation_type: invocation.invocation_type,
+        plugin_id: invocation.plugin_id,
+        plugin_name: invocation.plugin_name,
+        skill_id: invocation.skill_id,
+        skill_name: invocation.skill_name,
+        usage_count: invocation.usage_count,
+    }
+}
+
+/// 主动额度重置卡列表响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditsData {
+    pub available_count: u64,
+    pub credits: Vec<AccountResetCreditView>,
+}
+
+/// 一张安全主动额度重置卡视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditView {
+    pub id: String,
+    pub status: Option<String>,
+    pub title: Option<String>,
+    pub expires_at: Option<String>,
+    pub reset_type: Option<String>,
+}
+
+/// 主动额度重置卡消费响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditResultData {
+    pub code: String,
+    pub credit: Option<AccountResetCreditView>,
+}
+
+impl From<ProviderResetCredit> for AccountResetCreditView {
+    fn from(credit: ProviderResetCredit) -> Self {
+        Self {
+            id: credit.id,
+            status: credit.status,
+            title: credit.title,
+            expires_at: credit.expires_at.map(|value| value.to_rfc3339()),
+            reset_type: credit.reset_type,
+        }
+    }
+}
+
+impl From<ProviderResetCredits> for AccountResetCreditsData {
+    fn from(credits: ProviderResetCredits) -> Self {
+        Self {
+            available_count: credits.available_count,
+            credits: credits
+                .credits
+                .into_iter()
+                .map(AccountResetCreditView::from)
+                .collect(),
+        }
+    }
+}
+
+impl From<ProviderResetCreditResult> for AccountResetCreditResultData {
+    fn from(result: ProviderResetCreditResult) -> Self {
+        Self {
+            code: result.code,
+            credit: result.credit.map(AccountResetCreditView::from),
+        }
+    }
+}
+
+/// Provider-owned 明文导出文档；Debug 永远不输出内部 JSON。
+#[derive(Serialize)]
+#[serde(transparent)]
+pub struct AccountExportData(Value);
+
+impl AccountExportData {
+    #[must_use]
+    pub const fn new(value: Value) -> Self {
+        Self(value)
+    }
+
+    pub(super) fn from_result(bundle: AccountExportBundle) -> Self {
+        let documents = bundle
+            .documents
+            .into_iter()
+            .map(|document| {
+                serde_json::json!({
+                    "provider": document.provider_kind.to_string(),
+                    "document": provider_document_value(document.document),
+                })
+            })
+            .collect::<Vec<_>>();
+        Self::new(serde_json::json!({
+            "exportedAt": bundle.exported_at.to_rfc3339(),
+            "documents": documents,
+        }))
+    }
+}
+
+impl fmt::Debug for AccountExportData {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AccountExportData(<redacted>)")
+    }
+}
+
+pub struct AccountConnectionTestEvent {
+    pub data: Value,
+}
+
+impl From<DomainConnectionTestEvent> for AccountConnectionTestEvent {
+    fn from(event: DomainConnectionTestEvent) -> Self {
+        let data = match event {
+            DomainConnectionTestEvent::Started { model } => serde_json::json!({
+                "type": "test_start",
+                "model": model,
+                "text": "正在连接上游 Responses"
+            }),
+            DomainConnectionTestEvent::Request {
+                model,
+                input_text,
+                stream,
+                store,
+            } => serde_json::json!({
+                "type": "request",
+                "payload": {
+                    "model": model,
+                    "input": [{
+                        "role": "user",
+                        "content": [{ "type": "input_text", "text": input_text }]
+                    }],
+                    "stream": stream,
+                    "store": store
+                }
+            }),
+            DomainConnectionTestEvent::Content { text } => {
+                serde_json::json!({ "type": "content", "text": text })
+            }
+            DomainConnectionTestEvent::Completed => serde_json::json!({
+                "type": "test_complete",
+                "success": true
+            }),
+            DomainConnectionTestEvent::Failed {
+                source,
+                gateway_error_code,
+                send_state,
+                message,
+                provider_error_code,
+                provider_error_type,
+                upstream_status,
+                upstream_content_type,
+                upstream_body,
+            } => serde_json::json!({
+                "type": "error",
+                "source": source.as_str(),
+                "gatewayErrorCode": gateway_error_code.as_str(),
+                "sendState": send_state.map(gateway_core::upstream::UpstreamSendState::as_str),
+                "error": message,
+                "providerErrorCode": provider_error_code,
+                "providerErrorType": provider_error_type,
+                "upstreamStatus": upstream_status,
+                "upstreamContentType": upstream_content_type,
+                "upstreamBody": upstream_body
+            }),
+        };
+        Self { data }
+    }
+}
@@ -3,7 +3,7 @@
 use std::fmt;

 use axum::{
-    Json, Router,
+    Router,
    extract::{FromRequestParts, State},
    http::{HeaderMap, HeaderValue, StatusCode, header::SET_COOKIE, request::Parts},
    response::{IntoResponse, Response},
@@ -16,7 +16,7 @@ use gateway_admin::{
 use serde::{Deserialize, Serialize};
 use tower_http::request_id::RequestId;

-use super::{AdminEnvelope, AdminError, AdminResponse};
+use super::{AdminEnvelope, AdminError, AdminJson, AdminResponse};

 const REQUEST_ID_HEADER: &str = "x-request-id";
 const ADMIN_SESSION_COOKIE: &str = "cpr_admin_session";
@@ -37,11 +37,6 @@ impl AdminAuth {
    pub const fn context(&self) -> &AdminRequestContext {
        &self.context
    }
-
-    #[must_use]
-    pub fn into_context(self) -> AdminRequestContext {
-        self.context
-    }
 }

 impl<S> FromRequestParts<S> for AdminAuth
@@ -52,8 +47,7 @@ where

    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
        let principal = require_admin_auth(state, &parts.headers).await?;
-        let request_id = admin_request_id(parts)
-            .ok_or_else(|| AdminError::internal("Missing admin request context"))?;
+        let request_id = admin_request_id(parts).ok_or_else(AdminError::internal)?;
        Ok(Self {
            context: AdminRequestContext {
                principal,
@@ -90,7 +84,7 @@ where
    {
        Ok(Some(admin_user_id)) => Ok(admin_user_id),
        Ok(None) => Err(AdminError::admin_session_required()),
-        Err(_) => Err(AdminError::internal("Failed to validate admin session")),
+        Err(_) => Err(AdminError::internal()),
    }
 }

@@ -107,7 +101,7 @@ where
        {
            Ok(true) => Ok(AdminPrincipal::ApiKey),
            Ok(false) => Err(AdminError::invalid_admin_api_key()),
-            Err(_) => Err(AdminError::internal("Failed to validate admin API key")),
+            Err(_) => Err(AdminError::internal()),
        };
    }

@@ -209,7 +203,7 @@ where

 async fn login<S>(
    State(state): State<S>,
-    Json(payload): Json<AdminLoginRequest>,
+    AdminJson(payload): AdminJson<AdminLoginRequest>,
 ) -> Result<Response, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -232,8 +226,7 @@ where
    );
    response.headers_mut().insert(
        SET_COOKIE,
-        HeaderValue::from_str(&cookie)
-            .map_err(|_| AdminError::internal("Failed to create admin session cookie"))?,
+        HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,
    );
    Ok(response)
 }
@@ -250,7 +243,7 @@ where
        .auth()
        .validate_session(admin_session_cookie(&headers).as_deref())
        .await
-        .map_err(|_| AdminError::internal("Failed to validate admin session"))?;
+        .map_err(|_| AdminError::internal())?;
    Ok(AdminResponse::new(
        StatusCode::OK,
        AdminEnvelope::ok(AdminSessionStatusData::new(authenticated)),
@@ -270,8 +263,7 @@ where
    let cookie = format!("{ADMIN_SESSION_COOKIE}=; {ADMIN_SESSION_COOKIE_ATTRS}; Max-Age=0");
    response.headers_mut().insert(
        SET_COOKIE,
-        HeaderValue::from_str(&cookie)
-            .map_err(|_| AdminError::internal("Failed to clear admin session cookie"))?,
+        HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,
    );
    Ok(response)
 }
@@ -287,6 +279,6 @@ fn admin_session_cookie(headers: &HeaderMap) -> Option<String> {
 fn map_login_error(error: LoginError) -> AdminError {
    match error {
        LoginError::InvalidCredentials => AdminError::invalid_admin_credentials(),
-        LoginError::Unavailable => AdminError::internal("Failed to create admin session"),
+        LoginError::Unavailable => AdminError::internal(),
    }
 }
@@ -3,8 +3,8 @@
 //! 路径统一位于 `/api/admin/settings/backups/*`，内部由独立 `BackupService` 承担业务。

 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post},
@@ -18,8 +18,8 @@ use secrecy::{ExposeSecret as _, SecretString};
 use serde::{Deserialize, Serialize};

 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminPageData, AdminResponse, AdminSessionState,
-    PageMeta, wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminPageData, AdminQuery, AdminResponse,
+    AdminSessionState, PageMeta, wire::map_admin_service_error,
 };

 /// 备份设置视图；`secretAccessKey` 返回已保存的明文凭据，由前端掩码显示。
@@ -256,7 +256,7 @@ where
 async fn update_backup_storage<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<UpdateBackupStorageRequest>,
+    AdminJson(request): AdminJson<UpdateBackupStorageRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -304,7 +304,7 @@ where
 async fn update_backup_schedule<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<UpdateBackupScheduleRequest>,
+    AdminJson(request): AdminJson<UpdateBackupScheduleRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -331,28 +331,28 @@ where
 async fn backup_records<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<BackupRecordsQuery>,
+    AdminQuery(query): AdminQuery<BackupRecordsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
 {
    let page_size = gateway_admin::model::PageSize::new(query.page_size.unwrap_or(20))
-        .map_err(|_| AdminError::bad_request("Invalid pageSize"))?;
+        .map_err(|_| AdminError::bad_request("pageSize 不合法"))?;
    let page = query.page.unwrap_or(1);
    if page == 0 {
-        return Err(AdminError::bad_request("Invalid page"));
+        return Err(AdminError::bad_request("page 不合法"));
    }
    let status = match query.status.as_deref() {
        None => None,
        Some(value) => BackupStatus::parse(value)
            .map(Some)
-            .ok_or_else(|| AdminError::bad_request("Invalid status"))?,
+            .ok_or_else(|| AdminError::bad_request("status 不合法"))?,
    };
    let trigger = match query.trigger.as_deref() {
        None => None,
        Some(value) => BackupTriggerKind::parse(value)
            .map(Some)
-            .ok_or_else(|| AdminError::bad_request("Invalid trigger"))?,
+            .ok_or_else(|| AdminError::bad_request("trigger 不合法"))?,
    };
    let domain_query = gateway_admin::model::backup::BackupRecordListQuery {
        page,
@@ -386,7 +386,7 @@ where
 async fn create_backup<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    body: Option<Json<CreateBackupRequest>>,
+    body: Option<AdminJson<CreateBackupRequest>>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -417,7 +417,7 @@ pub struct CreateBackupRequest {
 async fn download_backup_url<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<BackupIdRequest>,
+    AdminJson(request): AdminJson<BackupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -437,7 +437,7 @@ where
 async fn delete_backup<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<BackupIdRequest>,
+    AdminJson(request): AdminJson<BackupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -455,5 +455,5 @@ where
 }

 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Backup service unavailable")
+    map_admin_service_error(error)
 }
@@ -17,16 +17,16 @@ use gateway_core::{
 use serde::{Deserialize, Serialize};

 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
    http::{HeaderValue, StatusCode, header::CACHE_CONTROL},
    response::{IntoResponse, Response},
    routing::{get, post},
 };

 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, WireValidationError,
-    wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    WireValidationError, wire::map_admin_service_error,
 };

 const MAX_CURSOR_BYTES: usize = 512;
@@ -669,7 +669,7 @@ where
 async fn list_client_keys<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<ListClientKeysQuery>,
+    AdminQuery(query): AdminQuery<ListClientKeysQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -680,15 +680,14 @@ where
        .list(query.into_command().map_err(map_wire_error)?)
        .await
        .map_err(map_service_error)?;
-    let data = ClientKeyListData::try_from(result)
-        .map_err(|_| AdminError::internal("Failed to encode client key cursor"))?;
+    let data = ClientKeyListData::try_from(result).map_err(|_| AdminError::internal())?;
    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }

 async fn create_client_key<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(payload): Json<CreateClientKeyRequest>,
+    AdminJson(payload): AdminJson<CreateClientKeyRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -709,7 +708,7 @@ where
 async fn reveal_client_key<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<ClientKeyIdQuery>,
+    AdminQuery(query): AdminQuery<ClientKeyIdQuery>,
 ) -> Result<Response, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -735,7 +734,7 @@ where
 async fn update_client_key<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(payload): Json<UpdateClientKeyRequest>,
+    AdminJson(payload): AdminJson<UpdateClientKeyRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -753,7 +752,7 @@ where
 async fn disable_client_key<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(payload): Json<ClientKeyMutationRequest>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -774,7 +773,7 @@ where
 async fn enable_client_key<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(payload): Json<ClientKeyMutationRequest>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -795,7 +794,7 @@ where
 async fn delete_client_key<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(payload): Json<ClientKeyMutationRequest>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -822,13 +821,14 @@ fn mutation_response(

 fn map_wire_error(error: WireValidationError) -> AdminError {
    match error.field() {
-        "cursor" => AdminError::bad_request("Invalid client key cursor"),
-        "clientKeyRevealNotFound" => AdminError::not_found("Client API key was not found"),
-        "clientKeyMutationNotFound" => AdminError::not_found("client API key was not found"),
-        _ => AdminError::bad_request("Invalid client API key request"),
+        "cursor" => AdminError::bad_request("Client API Key 游标不合法"),
+        "clientKeyRevealNotFound" | "clientKeyMutationNotFound" => {
+            AdminError::not_found("Client API Key 不存在")
+        }
+        _ => AdminError::bad_request("Client API Key 请求不合法"),
    }
 }

 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Configuration repository unavailable")
+    map_admin_service_error(error)
 }
@@ -0,0 +1,87 @@
+//! 管理端 JSON 与 Query extractor 的稳定 rejection 映射。
+
+use axum::{
+    Json,
+    extract::{
+        FromRequest, FromRequestParts, OptionalFromRequest, Query, Request,
+        rejection::{JsonRejection, QueryRejection},
+    },
+    http::{StatusCode, request::Parts},
+};
+use serde::de::DeserializeOwned;
+
+use super::AdminError;
+
+/// 将 Axum JSON rejection 收口为管理端错误信封。
+pub struct AdminJson<T>(pub T);
+
+impl<T, S> FromRequest<S> for AdminJson<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request(request: Request, state: &S) -> Result<Self, Self::Rejection> {
+        <Json<T> as FromRequest<S>>::from_request(request, state)
+            .await
+            .map(|Json(value)| Self(value))
+            .map_err(map_json_rejection)
+    }
+}
+
+impl<T, S> OptionalFromRequest<S> for AdminJson<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request(request: Request, state: &S) -> Result<Option<Self>, Self::Rejection> {
+        <Json<T> as OptionalFromRequest<S>>::from_request(request, state)
+            .await
+            .map(|value| value.map(|Json(value)| Self(value)))
+            .map_err(map_json_rejection)
+    }
+}
+
+/// 将 Axum Query rejection 收口为管理端错误信封。
+pub struct AdminQuery<T>(pub T);
+
+impl<T, S> FromRequestParts<S> for AdminQuery<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        Query::<T>::from_request_parts(parts, state)
+            .await
+            .map(|Query(value)| Self(value))
+            .map_err(map_query_rejection)
+    }
+}
+
+fn map_json_rejection(rejection: JsonRejection) -> AdminError {
+    let status = rejection.status();
+    match rejection {
+        JsonRejection::JsonSyntaxError(_) => AdminError::malformed_json(),
+        JsonRejection::JsonDataError(_) => {
+            AdminError::invalid_request(StatusCode::UNPROCESSABLE_ENTITY, "请求字段不合法")
+        }
+        JsonRejection::MissingJsonContentType(_) => AdminError::invalid_request(
+            StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            "请求必须使用 application/json",
+        ),
+        JsonRejection::BytesRejection(_) if status == StatusCode::PAYLOAD_TOO_LARGE => {
+            AdminError::invalid_request(status, "请求体过大")
+        }
+        JsonRejection::BytesRejection(_) => AdminError::internal(),
+        _ => AdminError::invalid_request(status, "请求体不合法"),
+    }
+}
+
+fn map_query_rejection(_: QueryRejection) -> AdminError {
+    AdminError::bad_request("请求参数不合法")
+}
@@ -5,6 +5,7 @@ use axum::{
    http::{HeaderValue, header},
    middleware,
    response::Response,
+    routing::any,
 };

 pub mod account_groups;
@@ -12,6 +13,7 @@ pub mod accounts;
 pub mod auth;
 pub mod backups;
 pub mod client_keys;
+mod extract;
 pub mod observability;
 pub mod presenter;
 pub mod settings;
@@ -19,6 +21,7 @@ pub mod system;
 pub mod wire;

 pub use auth::{AdminAuth, AdminSessionState};
+pub use extract::{AdminJson, AdminQuery};
 pub use wire::{
    ADMIN_OK_CODE, ADMIN_OK_MESSAGE, AdminEnvelope, AdminError, AdminErrorBody, AdminErrorCode,
    AdminPageData, AdminResponse, PageMeta, WireValidationError,
@@ -38,12 +41,24 @@ where
        .merge(observability::router::<S>())
        .merge(settings::router::<S>())
        .merge(system::router::<S>())
+        .method_not_allowed_fallback(method_not_allowed)
+        .route("/api/admin", any(admin_not_found))
+        .route("/api/admin/{*path}", any(admin_not_found))
        .layer(middleware::map_response(no_store))
 }

+async fn method_not_allowed() -> AdminError {
+    AdminError::method_not_allowed()
+}
+
+async fn admin_not_found() -> AdminError {
+    AdminError::admin_route_not_found()
+}
+
 async fn no_store(mut response: Response) -> Response {
    response
        .headers_mut()
-        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+        .entry(header::CACHE_CONTROL)
+        .or_insert(HeaderValue::from_static("no-store"));
    response
 }
@@ -1,15 +1,8 @@
 //! Dashboard、用量与诊断查询的 wire 映射和固定路由。

-use std::{collections::BTreeMap, num::NonZeroU32};
+use std::collections::BTreeMap;

-use axum::{
-    Router,
-    extract::{Query, State},
-    http::StatusCode,
-    response::IntoResponse,
-    routing::get,
-};
-use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use axum::{Router, extract::State, http::StatusCode, response::IntoResponse, routing::get};
 use chrono::{DateTime, Duration, Utc};
 use gateway_admin::model::{PageSize as DomainPageSize, observability as domain};
 use serde::{Deserialize, Serialize};
@@ -17,7 +10,7 @@ use serde_json::Value;

 use super::presenter::{format_compact_number, format_decimal_currency, format_number};
 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, PageMeta,
+    AdminAuth, AdminEnvelope, AdminError, AdminQuery, AdminResponse, AdminSessionState,
    WireValidationError, wire::map_admin_service_error,
 };

@@ -17,6 +17,21 @@ pub(crate) fn display_duration(value: Option<u64>) -> String {
    }
 }

+fn display_duration_f64(value: Option<f64>) -> String {
+    let Some(value) = value.filter(|value| value.is_finite() && *value >= 0.0) else {
+        return "—".to_owned();
+    };
+    if value < 1_000.0 {
+        format!("{value:.0} ms")
+    } else if value < 60_000.0 {
+        format!("{:.2} s", value / 1_000.0)
+    } else if value < 3_600_000.0 {
+        format!("{:.1} min", value / 60_000.0)
+    } else {
+        format!("{:.1} h", value / 3_600_000.0)
+    }
+}
+
 pub(crate) fn display_rate(value: f64) -> String {
    if value.is_finite() {
        format!("{:.1}%", value * 100.0)
@@ -25,6 +40,10 @@ pub(crate) fn display_rate(value: f64) -> String {
    }
 }

+fn basis_points_rate(value: u64) -> f64 {
+    value as f64 / 10_000.0
+}
+
 pub(crate) fn china_datetime(value: &DateTime<Utc>) -> String {
    (*value + Duration::hours(8))
        .format("%Y-%m-%d %H:%M:%S")
@@ -127,6 +146,43 @@ pub(crate) fn token_details(record: &domain::UsageRecord) -> TokenDetailsView {
    }
 }

+pub(crate) fn usage_list_token_details(record: &domain::UsageListRecord) -> TokenDetailsView {
+    TokenDetailsView {
+        input_tokens: record.input_tokens,
+        output_tokens: record.output_tokens,
+        cached_tokens: record.cached_tokens,
+        cache_write_tokens: record.cache_write_tokens,
+        reasoning_tokens: record.reasoning_tokens,
+        image_input_tokens: record.image_input_tokens,
+        image_output_tokens: record.image_output_tokens,
+        total_tokens: record.total_tokens,
+        input_tokens_display: record
+            .input_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        output_tokens_display: record
+            .output_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        cached_tokens_display: record
+            .cached_tokens
+            .map_or_else(|| "-".to_owned(), format_compact_number),
+        cache_write_tokens_display: record
+            .cache_write_tokens
+            .map_or_else(|| "-".to_owned(), format_compact_number),
+        reasoning_tokens_display: record
+            .reasoning_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        image_input_tokens_display: record
+            .image_input_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        image_output_tokens_display: record
+            .image_output_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        total_tokens_display: record
+            .total_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+    }
+}
+
 pub(crate) fn format_money(cost: &domain::CurrencyCost) -> String {
    format_decimal_currency(cost.amount.as_str(), &cost.currency)
 }
@@ -142,11 +198,19 @@ pub(crate) fn format_service_tier(service_tier: Option<&str>) -> String {
    match service_tier {
        Some("priority" | "fast") => "Fast".to_owned(),
        Some("flex") => "Flex".to_owned(),
-        Some("default") | None => "Default".to_owned(),
-        Some(other) => other.to_owned(),
+        Some("default" | "standard") | None => "Standard".to_owned(),
+        Some(other) => capitalize_first(other),
    }
 }

+fn capitalize_first(value: &str) -> String {
+    let mut chars = value.chars();
+    chars
+        .next()
+        .map(|first| first.to_uppercase().chain(chars).collect())
+        .unwrap_or_default()
+}
+
 pub(crate) fn billing_view(billing: Option<&domain::UsageBilling>) -> Option<BillingView> {
    match billing? {
        domain::UsageBilling::Total { total, .. } => Some(BillingView {
@@ -180,6 +244,57 @@ pub(crate) fn billing_view(billing: Option<&domain::UsageBilling>) -> Option<Bil
    }
 }

+pub(crate) fn usage_list_record_view(record: domain::UsageListRecord) -> UsageListRecordView {
+    let token_details = usage_list_token_details(&record);
+    let billing = billing_view(record.billing.as_ref());
+    let created_at_display = china_datetime(&record.started_at);
+    let model = record
+        .upstream_model_id
+        .clone()
+        .or_else(|| record.requested_model_id.clone());
+    UsageListRecordView {
+        id: record.id,
+        provider: record.provider_kind,
+        authentication_kind: record.provider_account_authentication_kind,
+        account_id: record.provider_account_ref,
+        account_email: record.provider_account_email,
+        account_name: record.provider_account_name,
+        route: record.endpoint,
+        model,
+        requested_model: record.requested_model_id,
+        upstream_model: record.upstream_model_id,
+        service_tier: record.service_tier,
+        client_transport: record.client_transport,
+        upstream_transport: record.upstream_transport,
+        reasoning_effort: record.reasoning_effort,
+        reasoning_preset: record.reasoning_preset,
+        subagent_kind: record.subagent_kind,
+        compact: record.compact,
+        token_details,
+        billing,
+        latency_details: UsageLatencyDetailsView {
+            admission_decision_ms: record.admission_decision_ms,
+            account_selection_wait_ms: record.account_selection_wait_ms,
+            capacity_used_slots: record.capacity_used_slots,
+            capacity_total_slots: record.capacity_total_slots,
+            transport_decision_wait_ms: record.transport_decision_wait_ms,
+            ws_connect_ms: record.connect_ms,
+            upstream_headers_ms: record.headers_ms,
+            first_event_ms: record.first_event_ms,
+            first_reasoning_ms: record.first_reasoning_ms,
+            first_text_ms: record.first_text_ms,
+            first_token_ms: record.first_token_ms,
+            openai_processing_ms: record.provider_processing_ms,
+        },
+        first_token_latency_ms: record.first_token_ms,
+        latency_ms: record.latency_ms,
+        created_at: record.started_at,
+        created_at_display,
+        client_ip: record.client_ip,
+        user_agent: record.user_agent,
+    }
+}
+
 pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView {
    let tokens = token_details(&record);
    let billing = billing_view(record.billing.as_ref());
@@ -222,11 +337,7 @@ pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView
    let model = record
        .upstream_model_id
        .clone()
-        .unwrap_or_else(|| record.requested_model_id.clone());
-    let transport = record
-        .upstream_transport
-        .clone()
-        .or_else(|| Some(record.client_transport.clone()));
+        .or_else(|| record.requested_model_id.clone());
    let metadata = provider_metadata_fields(record.provider_metadata_json.as_deref());
    UsageRecordView {
        id: record.id.clone(),
@@ -243,11 +354,12 @@ pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView
        account_name: record.provider_account_name,
        route: record.endpoint,
        model,
-        requested_model: Some(record.requested_model_id),
+        requested_model: record.requested_model_id,
        upstream_model: record.upstream_model_id,
        service_tier: record.service_tier,
        status_code,
-        transport,
+        client_transport: record.client_transport,
+        upstream_transport: record.upstream_transport,
        protocol: record.protocol.clone(),
        http_version: record.http_version.clone(),
        client_status_code: record.client_status_code.map(i64::from),
@@ -259,6 +371,10 @@ pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView
        image_generation_requested: record.image_generation_requested,
        image_generation_succeeded: record.image_generation_succeeded,
        latency_details: UsageLatencyDetailsView {
+            admission_decision_ms: record.admission_decision_ms,
+            account_selection_wait_ms: record.account_selection_wait_ms,
+            capacity_used_slots: record.capacity_used_slots,
+            capacity_total_slots: record.capacity_total_slots,
            transport_decision_wait_ms: record.transport_decision_wait_ms,
            ws_connect_ms: record.connect_ms,
            upstream_headers_ms: record.headers_ms,
@@ -318,6 +434,8 @@ pub(crate) fn provider_metadata_fields(value: Option<&str>) -> BTreeMap<String,
        "requestKind",
        "subagentKind",
        "transport",
+        "clientTransport",
+        "upstreamTransport",
        "httpVersion",
        "clientStatusCode",
        "upstreamStatusCode",
@@ -351,9 +469,7 @@ pub(crate) fn usage_attempt_view(attempt: domain::UsageAttempt) -> UsageAttemptV
        provider: attempt
            .provider_kind
            .unwrap_or_else(|| "unknown".to_owned()),
-        model: attempt
-            .upstream_model_id
-            .unwrap_or_else(|| "unknown".to_owned()),
+        model: attempt.upstream_model_id,
        transport: attempt
            .upstream_transport
            .unwrap_or_else(|| "unknown".to_owned()),
@@ -389,6 +505,8 @@ pub(crate) fn usage_attempt_view(attempt: domain::UsageAttempt) -> UsageAttemptV

 pub(crate) fn usage_detail_view(detail: domain::UsageDetail) -> UsageRecordDetailView {
    UsageRecordDetailView {
+        trace: detail.trace,
+        related_requests: detail.related_requests,
        request: usage_record_view(detail.request),
        attempts: detail
            .attempts
@@ -399,31 +517,13 @@ pub(crate) fn usage_detail_view(detail: domain::UsageDetail) -> UsageRecordDetai
    }
 }

-pub(crate) fn page_meta(page: u32, page_size: u16, total: u64) -> PageMeta {
-    let page_size_u64 = u64::from(page_size);
-    let total_pages = total.saturating_add(page_size_u64 - 1) / page_size_u64;
-    PageMeta::new(
-        page,
-        u32::from(page_size),
-        total,
-        u32::try_from(total_pages).unwrap_or(u32::MAX),
-    )
-}
-
-pub(crate) fn usage_page_view(
-    page: domain::UsagePage,
-    page_number: u32,
-    page_size: u16,
-) -> Result<PageData<UsageRecordView>, WireValidationError> {
-    Ok(PageData {
-        items: page.items.into_iter().map(usage_record_view).collect(),
-        page: page_meta(page_number, page_size, page.total),
-        next_cursor: page
-            .next_cursor
-            .as_ref()
-            .map(encode_observability_cursor)
-            .transpose()?,
-    })
+pub(crate) fn usage_page_view(page: domain::UsagePage) -> PageData<UsageListRecordView> {
+    PageData {
+        items: page.items.into_iter().map(usage_list_record_view).collect(),
+        current_page: page.current_page,
+        page_size: page.page_size,
+        total: page.total,
+    }
 }

 pub(crate) fn ops_error_view(error: domain::OpsError) -> OpsErrorView {
@@ -433,50 +533,77 @@ pub(crate) fn ops_error_view(error: domain::OpsError) -> OpsErrorView {
        .or(error.provider_account_name.as_ref())
        .or(error.provider_account_ref.as_ref())
        .cloned();
+    let model = error
+        .upstream_model_id
+        .clone()
+        .or_else(|| error.requested_model_id.clone());
    OpsErrorView {
        id: error.event_id,
        request_id: error.request_id,
        client_api_key_id: error.client_api_key_ref,
        kind: error.component.clone(),
+        operation: error.operation,
+        protocol: error.protocol,
+        client_transport: error.client_transport,
        provider: error.provider_kind,
        authentication_kind: error.provider_account_authentication_kind,
        account_id: error.provider_account_ref,
+        account_name: error.provider_account_name,
+        account_email: error.provider_account_email,
        route: error.endpoint.unwrap_or_else(|| "—".to_owned()),
-        model: error.upstream_model_id,
+        model,
+        requested_model: error.requested_model_id,
+        upstream_model: error.upstream_model_id,
+        service_tier: error.service_tier,
        client_status_code: error.client_status_code.map(i64::from),
        upstream_status_code: error.upstream_status_code.map(i64::from),
        transport: error.upstream_transport,
        attempt_index: error.attempt_index,
        failure_class: error.failure_kind,
+        upstream_send_state: error.upstream_send_state,
+        provider_error_code: error.provider_error_code,
        response_id: error.client_response_id,
        upstream_request_id: error.upstream_request_id,
        latency_ms: error.latency_ms,
+        client_ip: error.client_ip,
+        user_agent: error.user_agent,
+        reasoning_effort: error.reasoning_effort,
+        reasoning_preset: error.reasoning_preset,
+        request_kind: error.request_kind,
+        subagent_kind: error.subagent_kind,
+        compact: error.compact,
        message: error.message,
+        raw_upstream_error: error.raw_upstream_error,
        metadata: OpsErrorMetadataView {
            source: error.source,
            component: error.component,
            attempt_id: None,
            account_label,
+            continuation_affinity_hash: error.continuation_affinity_hash,
+            continuation_previous_response_id_hash: error.continuation_previous_response_id_hash,
+            continuation_unavailable_reason: error.continuation_unavailable_reason,
+            upstream_connection_id: error.upstream_connection_id,
+            upstream_connection_exit_reason: error.upstream_connection_exit_reason,
+            upstream_connection_age_ms: error.upstream_connection_age_ms,
+            upstream_connection_idle_ms: error.upstream_connection_idle_ms,
+            recovery_request_id: error.recovery_request_id,
+            recovered_at: error.recovered_at,
+            recovery_attempt_count: error.recovery_attempt_count,
+            recovery_retry_delay_ms: error.recovery_retry_delay_ms,
+            recovery_total_latency_ms: error.recovery_total_latency_ms,
        },
        created_at: error.occurred_at,
        created_at_display: china_datetime(&error.occurred_at),
    }
 }

-pub(crate) fn ops_page_view(
-    page: domain::OpsErrorPage,
-    page_number: u32,
-    page_size: u16,
-) -> Result<PageData<OpsErrorView>, WireValidationError> {
-    Ok(PageData {
+pub(crate) fn ops_page_view(page: domain::OpsErrorPage) -> PageData<OpsErrorView> {
+    PageData {
        items: page.items.into_iter().map(ops_error_view).collect(),
-        page: page_meta(page_number, page_size, page.total),
-        next_cursor: page
-            .next_cursor
-            .as_ref()
-            .map(encode_observability_cursor)
-            .transpose()?,
-    })
+        current_page: page.current_page,
+        page_size: page.page_size,
+        total: page.total,
+    }
 }

 pub(crate) fn trend_point_view(point: domain::TrendPoint) -> TrendPointView {
@@ -508,6 +635,36 @@ pub(crate) fn trend_point_view(point: domain::TrendPoint) -> TrendPointView {
        success_rate: success_rate_value
            .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
        success_rate_value,
+        first_token_p50_ms: point
+            .metrics
+            .first_token_latency_percentiles
+            .p50_ms
+            .map(|value| value.as_f64()),
+        first_token_p95_ms: point
+            .metrics
+            .first_token_latency_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        latency_p95_ms: point
+            .metrics
+            .latency_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        output_throughput_p50: point.metrics.output_throughput_p50,
+        admission_decision_p95_ms: point
+            .metrics
+            .admission_decision_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        account_selection_wait_p95_ms: point
+            .metrics
+            .account_selection_wait_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        capacity_utilization: point
+            .metrics
+            .capacity_utilization_p95_basis_points
+            .map(basis_points_rate),
    }
 }

@@ -535,18 +692,20 @@ pub(crate) fn trend_summary_view(
        ],
        TrendKind::Latency => vec![
            TrendSummaryView {
-                label: "平均".to_owned(),
-                value: display_duration(summary.average_latency_ms),
+                label: "首字 P95".to_owned(),
+                value: display_duration_f64(summary.peak_first_token_p95_ms),
                ratio: None,
            },
            TrendSummaryView {
-                label: "最高".to_owned(),
-                value: display_duration(summary.max_latency_ms),
+                label: "总耗时 P95".to_owned(),
+                value: display_duration_f64(summary.peak_latency_p95_ms),
                ratio: None,
            },
            TrendSummaryView {
-                label: "最低".to_owned(),
-                value: display_duration(summary.min_latency_ms),
+                label: "吞吐 P50".to_owned(),
+                value: summary
+                    .minimum_output_throughput_p50
+                    .map_or_else(|| "—".to_owned(), |value| format!("{value} tok/s")),
                ratio: None,
            },
        ],
@@ -706,6 +865,28 @@ pub(crate) fn dashboard_view(
    } = observation;
    let mut account_usage_views = Vec::with_capacity(account_usage.len());
    for credential in account_usage {
+        let local_requests = credential
+            .quota_window
+            .as_ref()
+            .filter(|window| window.used_percent.is_none())
+            .and_then(|window| window.local_usage.as_ref())
+            .map(|usage| usage.request_count);
+        let (metric_label, metric_value) = match local_requests {
+            Some(count) => (
+                "次数".to_owned(),
+                if count > 0 {
+                    format_compact_number(count)
+                } else {
+                    "—".to_owned()
+                },
+            ),
+            None => (
+                "今日 Token".to_owned(),
+                credential
+                    .total_tokens
+                    .map_or_else(|| "—".to_owned(), format_compact_number),
+            ),
+        };
        account_usage_views.push(DashboardAccountUsageView {
            id: credential.account_id.clone(),
            provider: credential.provider_kind.clone(),
@@ -728,24 +909,27 @@ pub(crate) fn dashboard_view(
                })
                .collect(),
            quota_used_percent: credential.quota_used_percent,
+            usage_window: credential
+                .quota_window
+                .map(crate::admin::accounts::quota_window_view),
+            metric_label,
+            metric_value,
            last_used: relative_time(credential.last_used_at, range.end),
        });
    }
+    let unavailable_accounts = provider_accounts
+        .total
+        .saturating_sub(provider_accounts.normal);
+
    DashboardDataView {
        cards: DashboardCardsView {
            credentials: DashboardCredentialsCardView {
-                total: format_compact_number(provider_accounts.total),
+                total: provider_accounts.total.to_string(),
                total_value: provider_accounts.total,
-                available: format_compact_number(provider_accounts.normal),
+                available: provider_accounts.normal.to_string(),
                available_value: provider_accounts.normal,
-                unavailable: format_compact_number(
-                    provider_accounts
-                        .total
-                        .saturating_sub(provider_accounts.normal),
-                ),
-                unavailable_value: provider_accounts
-                    .total
-                    .saturating_sub(provider_accounts.normal),
+                unavailable: unavailable_accounts.to_string(),
+                unavailable_value: unavailable_accounts,
            },
            traffic: DashboardTrafficCardView {
                today_requests: format_compact_number(today.request_count),
@@ -775,7 +959,10 @@ pub(crate) fn dashboard_view(
        health_timeline: health_timeline_view(health_timeline),
        wire_profiles: wire_profiles.into_iter().map(wire_profile_view).collect(),
        account_usage: account_usage_views,
-        usage_records: recent_requests.into_iter().map(usage_record_view).collect(),
+        usage_records: recent_requests
+            .into_iter()
+            .map(usage_list_record_view)
+            .collect(),
        pool_summary: DashboardPoolSummaryView {
            total: provider_accounts.total,
            normal: provider_accounts.normal,
@@ -817,6 +1004,7 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
        .map(|point| OverviewHealthPointView {
            bucket: point.bucket_start,
            label: china_label(point.bucket_start, "%m-%d %H:%M"),
+            total_requests: point.total_requests,
            success_requests: point.success_requests,
            failed_requests: point.failed_requests,
            cancelled_requests: point.cancelled_requests,
@@ -847,6 +1035,31 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
                .first_token_latency_percentiles
                .p99_ms
                .map(|value| value.as_f64()),
+            admission_decision_p50_ms: point
+                .admission_decision_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            admission_decision_p95_ms: point
+                .admission_decision_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p50_ms: point
+                .account_selection_wait_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p95_ms: point
+                .account_selection_wait_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            output_throughput_p10: point.output_throughput_p10,
+            output_throughput_p50: point.output_throughput_p50,
+            output_throughput_p90: point.output_throughput_p90,
+            capacity_utilization: point
+                .capacity_utilization_avg_basis_points
+                .map(basis_points_rate),
+            capacity_utilization_p95: point
+                .capacity_utilization_p95_basis_points
+                .map(basis_points_rate),
        })
        .collect();
    let cost_points = insights
@@ -862,6 +1075,8 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
            total_tokens: point.total_tokens,
            estimated_cost: point.estimated_cost.as_ref().map(ToString::to_string),
            standard_cost: point.standard_cost.as_ref().map(ToString::to_string),
+            no_cache_cost: point.no_cache_cost.as_ref().map(ToString::to_string),
+            cache_savings: point.cache_savings.as_ref().map(ToString::to_string),
            cached_token_rate: point.cached_token_rate,
            cache_hit_request_rate: point.cache_hit_request_rate,
        })
@@ -876,6 +1091,7 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
            incomplete_requests: insights.health.incomplete_requests,
            caller_error_requests: insights.health.caller_error_requests,
            success_rate: insights.health.success_rate,
+            completion_rate: insights.health.completion_rate,
            request_change_rate: None,
            success_rate_change: None,
            points: health_points,
@@ -911,8 +1127,42 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
                .first_token_latency_percentiles
                .p99_ms
                .map(|value| value.as_f64()),
+            admission_decision_p50_ms: insights
+                .performance
+                .admission_decision_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            admission_decision_p95_ms: insights
+                .performance
+                .admission_decision_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p50_ms: insights
+                .performance
+                .account_selection_wait_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p95_ms: insights
+                .performance
+                .account_selection_wait_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            output_throughput_p10: insights.performance.output_throughput_p10,
+            output_throughput_p50: insights.performance.output_throughput_p50,
+            output_throughput_p90: insights.performance.output_throughput_p90,
+            capacity_utilization: insights
+                .performance
+                .capacity_utilization_avg_basis_points
+                .map(basis_points_rate),
+            capacity_utilization_p95: insights
+                .performance
+                .capacity_utilization_p95_basis_points
+                .map(basis_points_rate),
            latency_coverage: insights.performance.latency_coverage,
            first_token_coverage: insights.performance.first_token_coverage,
+            admission_decision_coverage: insights.performance.admission_decision_coverage,
+            account_selection_wait_coverage: insights.performance.account_selection_wait_coverage,
+            capacity_coverage: insights.performance.capacity_coverage,
            points: performance_points,
        },
        cost: OverviewCostView {
@@ -926,11 +1176,27 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
                .standard_cost
                .as_ref()
                .map(ToString::to_string),
+            no_cache_cost: insights
+                .cost
+                .no_cache_cost
+                .as_ref()
+                .map(ToString::to_string),
+            cache_savings: insights
+                .cost
+                .cache_savings
+                .as_ref()
+                .map(ToString::to_string),
+            tier_premium: insights.cost.tier_premium.as_ref().map(ToString::to_string),
            cost_per_request: insights
                .cost
                .cost_per_request
                .as_ref()
                .map(ToString::to_string),
+            cost_per_successful_request: insights
+                .cost
+                .cost_per_successful_request
+                .as_ref()
+                .map(ToString::to_string),
            tokens_per_request: insights.cost.tokens_per_request,
            cached_token_rate: insights.cost.cached_token_rate,
            cache_hit_request_rate: insights.cost.cache_hit_request_rate,
@@ -988,6 +1254,12 @@ pub(crate) fn diagnostics_view(
                request_share: item.request_share,
                average_latency_ms: item.average_latency_ms,
                latency_p95_ms: item.latency_p95_ms,
+                first_token_p95_ms: item.first_token_p95_ms,
+                non_completion_count: item.non_completion_count,
+                non_completion_rate: item.non_completion_rate,
+                retry_count: item.retry_count,
+                retry_rate: item.retry_rate,
+                impact_score: item.impact_score,
                estimated_cost: item.estimated_cost.as_ref().map(ToString::to_string),
                attempt_count: item.attempt_count,
                total_tokens: item.total_tokens,
@@ -997,21 +1269,21 @@ pub(crate) fn diagnostics_view(
 }

 pub(crate) fn map_wire_error(error: WireValidationError) -> AdminError {
+    if error.field() == "timeRange" {
+        return AdminError::invalid_time_range();
+    }
    let message = match error.field() {
-        "timeRange" => "Invalid time range",
-        "statusCode" => "Status code must be between 100 and 599",
-        "attemptIndex" => "Attempt index is out of range",
-        "kind" => "Invalid dashboard trend kind",
-        "dimension" => "Invalid diagnostics dimension",
-        "outcome" => "Invalid Observability query",
-        "id" => "Usage record ID is required",
-        "page" | "pageSize" => "Invalid Observability query",
-        "cursor" => "Invalid observability cursor",
-        _ => "Invalid observability query",
+        "statusCode" => "statusCode 必须在 100 到 599 之间",
+        "attemptIndex" => "attemptIndex 超出有效范围",
+        "kind" => "Dashboard 趋势类型不合法",
+        "dimension" => "诊断维度不合法",
+        "id" => "用量记录 ID 不能为空",
+        "cursor" => "观测数据游标不合法",
+        _ => "观测查询参数不合法",
    };
    AdminError::bad_request(message)
 }

 pub(crate) fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Observability repository unavailable")
+    map_admin_service_error(error)
 }
@@ -2,14 +2,10 @@

 use super::*;

-use base64::Engine as _;
-
 /// 观测列表默认页大小。
 pub const DEFAULT_PAGE_SIZE: u16 = 50;
 /// 观测列表允许的最大页大小。
 pub const MAX_PAGE_SIZE: u16 = 100;
-/// 游标编码在 HTTP 层解码前允许的最大长度。
-pub const MAX_CURSOR_BYTES: usize = 1024;

 /// Dashboard 查询参数。
 #[derive(Clone, Default, Deserialize)]
@@ -31,9 +27,8 @@ impl DashboardQuery {
 #[derive(Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct UsageQuery {
-    pub page: Option<u32>,
+    pub current_page: Option<u32>,
    pub page_size: Option<u16>,
-    pub cursor: Option<String>,
    pub kind: Option<String>,
    pub outcome: Option<String>,
    pub client_api_key_id: Option<String>,
@@ -53,22 +48,17 @@ pub struct UsageQuery {
 }

 impl UsageQuery {
-    /// 校验分页字段，不改变仓储层的分页 owner。
-    pub fn validate_page(&self) -> Result<(u32, u16), WireValidationError> {
-        let page = self.page.unwrap_or(1);
-        if page == 0 {
-            return Err(WireValidationError::new("page"));
+    /// 校验 Element Plus 风格的页码分页字段。
+    pub fn validate_pagination(&self) -> Result<(u32, u16), WireValidationError> {
+        let current_page = self.current_page.unwrap_or(1);
+        if current_page == 0 {
+            return Err(WireValidationError::new("currentPage"));
        }
        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
        if page_size == 0 || page_size > MAX_PAGE_SIZE {
            return Err(WireValidationError::new("pageSize"));
        }
-        Ok((page, page_size))
-    }
-
-    /// 校验游标的 wire 边界；编码和排序语义由应用层负责。
-    pub fn validate_cursor(&self) -> Result<(), WireValidationError> {
-        validate_cursor(self.cursor.as_deref())
+        Ok((current_page, page_size))
    }
 }

@@ -110,22 +100,19 @@ impl DiagnosticsQuery {
 #[derive(Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct OpsQuery {
-    pub page: Option<u32>,
+    pub current_page: Option<u32>,
    pub page_size: Option<u16>,
-    pub cursor: Option<String>,
    pub kind: Option<String>,
    pub client_api_key_id: Option<String>,
    pub provider: Option<String>,
    pub request_id: Option<String>,
    pub account_id: Option<String>,
-    pub route: Option<String>,
    pub model: Option<String>,
    pub status_code: Option<i64>,
    pub client_status_code: Option<i64>,
    pub upstream_status_code: Option<i64>,
    pub transport: Option<String>,
    pub attempt_index: Option<i64>,
-    pub failure_class: Option<String>,
    pub response_id: Option<String>,
    pub upstream_request_id: Option<String>,
    pub search: Option<String>,
@@ -134,22 +121,17 @@ pub struct OpsQuery {
 }

 impl OpsQuery {
-    /// 校验分页字段。
-    pub fn validate_page(&self) -> Result<(u32, u16), WireValidationError> {
-        let page = self.page.unwrap_or(1);
-        if page == 0 {
-            return Err(WireValidationError::new("page"));
+    /// 校验 Element Plus 风格的页码分页字段。
+    pub fn validate_pagination(&self) -> Result<(u32, u16), WireValidationError> {
+        let current_page = self.current_page.unwrap_or(1);
+        if current_page == 0 {
+            return Err(WireValidationError::new("currentPage"));
        }
        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
        if page_size == 0 || page_size > MAX_PAGE_SIZE {
            return Err(WireValidationError::new("pageSize"));
        }
-        Ok((page, page_size))
-    }
-
-    /// 校验游标的 wire 边界。
-    pub fn validate_cursor(&self) -> Result<(), WireValidationError> {
-        validate_cursor(self.cursor.as_deref())
+        Ok((current_page, page_size))
    }
 }

@@ -258,13 +240,6 @@ pub(crate) fn require_text(value: &str, field: &'static str) -> Result<(), WireV
    }
 }

-pub(crate) fn validate_cursor(value: Option<&str>) -> Result<(), WireValidationError> {
-    if value.is_some_and(|value| value.is_empty() || value.len() > MAX_CURSOR_BYTES) {
-        return Err(WireValidationError::new("cursor"));
-    }
-    Ok(())
-}
-
 pub(crate) fn trimmed(value: Option<&str>) -> Option<&str> {
    value.map(str::trim).filter(|value| !value.is_empty())
 }
@@ -345,37 +320,20 @@ pub(crate) fn usage_filter(query: &UsageQuery) -> Result<domain::UsageFilter, Wi
    })
 }

-pub(crate) fn usage_command(
-    query: &UsageQuery,
-) -> Result<(domain::UsageQuery, u32, u16), WireValidationError> {
-    let (page, page_size) = query.validate_page()?;
-    query.validate_cursor()?;
-    let page_number = NonZeroU32::new(page)
-        .map(domain::PageNumber::new)
-        .ok_or_else(|| WireValidationError::new("page"))?;
+pub(crate) fn usage_command(query: &UsageQuery) -> Result<domain::UsageQuery, WireValidationError> {
+    let (current_page, page_size) = query.validate_pagination()?;
    let page_size_value =
        DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
-    Ok((
-        domain::UsageQuery {
-            range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
-            filter: usage_filter(query)?,
-            cursor: decode_observability_cursor(query.cursor.as_deref())?,
-            page: page_number,
-            page_size: page_size_value,
-        },
-        page,
-        page_size,
-    ))
+    Ok(domain::UsageQuery {
+        range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
+        filter: usage_filter(query)?,
+        current_page,
+        page_size: page_size_value,
+    })
 }

-pub(crate) fn ops_command(
-    query: &OpsQuery,
-) -> Result<(domain::OpsErrorQuery, u32, u16), WireValidationError> {
-    let (page, page_size) = query.validate_page()?;
-    query.validate_cursor()?;
-    let page_number = NonZeroU32::new(page)
-        .map(domain::PageNumber::new)
-        .ok_or_else(|| WireValidationError::new("page"))?;
+pub(crate) fn ops_command(query: &OpsQuery) -> Result<domain::OpsErrorQuery, WireValidationError> {
+    let (current_page, page_size) = query.validate_pagination()?;
    let page_size_value =
        DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
    let status_code = parse_status(
@@ -384,66 +342,25 @@ pub(crate) fn ops_command(
            .or(query.client_status_code)
            .or(query.status_code),
    )?;
-    Ok((
-        domain::OpsErrorQuery {
-            range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
-            filter: domain::OpsErrorFilter {
-                client_api_key_ref: non_empty(query.client_api_key_id.clone()),
-                request_id: non_empty(query.request_id.clone()),
-                provider_kind: non_empty(query.provider.clone()),
-                provider_account_ref: non_empty(query.account_id.clone()),
-                operation: non_empty(query.route.clone()).or_else(|| non_empty(query.kind.clone())),
-                model: non_empty(query.model.clone()),
-                transport: non_empty(query.transport.clone()),
-                attempt_index: parse_attempt_index(query.attempt_index)?,
-                response_id: non_empty(query.response_id.clone()),
-                upstream_request_id: non_empty(query.upstream_request_id.clone()),
-                failure_kind: non_empty(query.failure_class.clone()),
-                status_code,
-                search: non_empty(query.search.clone()),
-            },
-            cursor: decode_observability_cursor(query.cursor.as_deref())?,
-            page: page_number,
-            page_size: page_size_value,
+    Ok(domain::OpsErrorQuery {
+        range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
+        filter: domain::OpsErrorFilter {
+            client_api_key_ref: non_empty(query.client_api_key_id.clone()),
+            request_id: non_empty(query.request_id.clone()),
+            provider_kind: non_empty(query.provider.clone()),
+            provider_account_ref: non_empty(query.account_id.clone()),
+            operation: non_empty(query.kind.clone()),
+            model: non_empty(query.model.clone()),
+            transport: non_empty(query.transport.clone()),
+            attempt_index: parse_attempt_index(query.attempt_index)?,
+            response_id: non_empty(query.response_id.clone()),
+            upstream_request_id: non_empty(query.upstream_request_id.clone()),
+            status_code,
+            search: non_empty(query.search.clone()),
        },
-        page,
-        page_size,
-    ))
-}
-
-pub(crate) fn decode_observability_cursor(
-    value: Option<&str>,
-) -> Result<Option<domain::ObservabilityCursor>, WireValidationError> {
-    value
-        .map(|encoded| {
-            if encoded.is_empty() || encoded.len() > MAX_CURSOR_BYTES {
-                return Err(WireValidationError::new("cursor"));
-            }
-            let bytes = URL_SAFE_NO_PAD
-                .decode(encoded)
-                .map_err(|_| WireValidationError::new("cursor"))?;
-            let wire: CursorWire =
-                serde_json::from_slice(&bytes).map_err(|_| WireValidationError::new("cursor"))?;
-            if wire.stable_id.trim().is_empty() {
-                return Err(WireValidationError::new("cursor"));
-            }
-            Ok(domain::ObservabilityCursor {
-                observed_at: wire.observed_at,
-                stable_id: wire.stable_id,
-            })
-        })
-        .transpose()
-}
-
-pub(crate) fn encode_observability_cursor(
-    cursor: &domain::ObservabilityCursor,
-) -> Result<String, WireValidationError> {
-    let bytes = serde_json::to_vec(&CursorWire {
-        observed_at: cursor.observed_at,
-        stable_id: cursor.stable_id.clone(),
+        current_page,
+        page_size: page_size_value,
    })
-    .map_err(|_| WireValidationError::new("cursor"))?;
-    Ok(URL_SAFE_NO_PAD.encode(bytes))
 }

 pub(crate) fn non_empty(value: Option<String>) -> Option<String> {
@@ -32,7 +32,7 @@ where
 pub(crate) async fn dashboard_summary<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<DashboardQuery>,
+    AdminQuery(query): AdminQuery<DashboardQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -56,7 +56,7 @@ where
 pub(crate) async fn dashboard_trend<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<DashboardQuery>,
+    AdminQuery(query): AdminQuery<DashboardQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -79,27 +79,26 @@ where
 pub(crate) async fn usage_records<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<UsageQuery>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
 {
-    let (command, page, page_size) = usage_command(&query).map_err(map_wire_error)?;
+    let command = usage_command(&query).map_err(map_wire_error)?;
    let result = state
        .admin_services()
        .observability()
        .usage_records(command)
        .await
        .map_err(map_service_error)?;
-    let data = usage_page_view(result, page, page_size)
-        .map_err(|_| AdminError::internal("Failed to encode observability cursor"))?;
+    let data = usage_page_view(result);
    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }

 pub(crate) async fn usage_record_detail<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<DetailQuery>,
+    AdminQuery(query): AdminQuery<DetailQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -120,7 +119,7 @@ where
 pub(crate) async fn usage_records_summary<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<UsageQuery>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -143,7 +142,7 @@ where
 pub(crate) async fn usage_insights_overview<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<UsageQuery>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -166,7 +165,7 @@ where
 pub(crate) async fn usage_insights_diagnostics<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<DiagnosticsQuery>,
+    AdminQuery(query): AdminQuery<DiagnosticsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -196,19 +195,18 @@ where
 pub(crate) async fn ops_errors<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<OpsQuery>,
+    AdminQuery(query): AdminQuery<OpsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
 {
-    let (command, page, page_size) = ops_command(&query).map_err(map_wire_error)?;
+    let command = ops_command(&query).map_err(map_wire_error)?;
    let result = state
        .admin_services()
        .observability()
        .ops_errors(command)
        .await
        .map_err(map_service_error)?;
-    let data = ops_page_view(result, page, page_size)
-        .map_err(|_| AdminError::internal("Failed to encode observability cursor"))?;
+    let data = ops_page_view(result);
    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }
@@ -2,21 +2,14 @@

 use super::*;

-/// 观测列表游标的稳定 wire 形状。
-#[derive(Clone, Serialize, serde::Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct CursorWire {
-    pub observed_at: DateTime<Utc>,
-    pub stable_id: String,
-}
-
 /// 观测列表响应数据。
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PageData<T> {
    pub items: Vec<T>,
-    pub page: PageMeta,
-    pub next_cursor: Option<String>,
+    pub current_page: u32,
+    pub page_size: u16,
+    pub total: u64,
 }

 /// Token 详情展示。
@@ -77,7 +70,39 @@ pub struct BillingView {
    pub multiplier_display: String,
 }

-/// 单条逻辑请求展示。
+/// 使用记录表格的窄展示。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageListRecordView {
+    pub id: String,
+    pub provider: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub account_id: Option<String>,
+    pub account_email: Option<String>,
+    pub account_name: Option<String>,
+    pub route: String,
+    pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
+    pub client_transport: String,
+    pub upstream_transport: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: bool,
+    pub token_details: TokenDetailsView,
+    pub billing: Option<BillingView>,
+    pub latency_details: UsageLatencyDetailsView,
+    pub first_token_latency_ms: Option<u64>,
+    pub latency_ms: Option<u64>,
+    pub created_at: DateTime<Utc>,
+    pub created_at_display: String,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+}
+
+/// 单条逻辑请求详情展示。
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UsageRecordView {
@@ -94,12 +119,13 @@ pub struct UsageRecordView {
    pub account_email: Option<String>,
    pub account_name: Option<String>,
    pub route: String,
-    pub model: String,
+    pub model: Option<String>,
    pub requested_model: Option<String>,
    pub upstream_model: Option<String>,
    pub service_tier: Option<String>,
    pub status_code: Option<i64>,
-    pub transport: Option<String>,
+    pub client_transport: String,
+    pub upstream_transport: Option<String>,
    pub protocol: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub http_version: Option<String>,
@@ -157,6 +183,14 @@ pub struct WebSocketPoolMetadataView {
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UsageLatencyDetailsView {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub admission_decision_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub account_selection_wait_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capacity_used_slots: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capacity_total_slots: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub transport_decision_wait_ms: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
@@ -183,7 +217,7 @@ pub struct UsageAttemptView {
    pub attempt_index: u32,
    pub trigger: String,
    pub provider: String,
-    pub model: String,
+    pub model: Option<String>,
    pub transport: String,
    pub send_state: String,
    pub outcome: String,
@@ -213,6 +247,8 @@ pub struct UsageAttemptView {
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UsageRecordDetailView {
+    pub trace: Option<serde_json::Value>,
+    pub related_requests: Vec<serde_json::Value>,
    #[serde(flatten)]
    pub request: UsageRecordView,
    pub attempts: Vec<UsageAttemptView>,
@@ -256,6 +292,13 @@ pub struct TrendPointView {
    pub min_latency_value: Option<u64>,
    pub success_rate: String,
    pub success_rate_value: Option<f64>,
+    pub first_token_p50_ms: Option<f64>,
+    pub first_token_p95_ms: Option<f64>,
+    pub latency_p95_ms: Option<f64>,
+    pub output_throughput_p50: Option<u64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub capacity_utilization: Option<f64>,
 }

 /// Dashboard 趋势摘要。
@@ -334,6 +377,9 @@ pub struct DashboardAccountUsageView {
    pub request_count: u64,
    pub request_buckets: Vec<DashboardAccountRequestBucketView>,
    pub quota_used_percent: Option<f64>,
+    pub usage_window: Option<crate::admin::accounts::AccountQuotaWindowView>,
+    pub metric_label: String,
+    pub metric_value: String,
    pub last_used: String,
 }

@@ -510,7 +556,7 @@ pub struct DashboardDataView {
    pub health_timeline: HealthTimelineView,
    pub wire_profiles: Vec<DashboardWireProfileView>,
    pub account_usage: Vec<DashboardAccountUsageView>,
-    pub usage_records: Vec<UsageRecordView>,
+    pub usage_records: Vec<UsageListRecordView>,
    pub pool_summary: DashboardPoolSummaryView,
    pub capacity_info: DashboardCapacityInfoView,
    pub rotation_strategy: String,
@@ -537,6 +583,7 @@ pub struct UsageSummaryView {
 pub struct OverviewHealthPointView {
    pub bucket: DateTime<Utc>,
    pub label: String,
+    pub total_requests: u64,
    pub success_requests: u64,
    pub failed_requests: u64,
    pub cancelled_requests: u64,
@@ -556,6 +603,7 @@ pub struct OverviewHealthView {
    pub incomplete_requests: u64,
    pub caller_error_requests: u64,
    pub success_rate: f64,
+    pub completion_rate: f64,
    pub request_change_rate: Option<f64>,
    pub success_rate_change: Option<f64>,
    pub points: Vec<OverviewHealthPointView>,
@@ -573,6 +621,15 @@ pub struct OverviewPerformancePointView {
    pub first_token_p50_ms: Option<f64>,
    pub first_token_p95_ms: Option<f64>,
    pub first_token_p99_ms: Option<f64>,
+    pub admission_decision_p50_ms: Option<f64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p50_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization: Option<f64>,
+    pub capacity_utilization_p95: Option<f64>,
 }

 /// 洞察性能摘要。
@@ -585,8 +642,20 @@ pub struct OverviewPerformanceView {
    pub first_token_p50_ms: Option<f64>,
    pub first_token_p95_ms: Option<f64>,
    pub first_token_p99_ms: Option<f64>,
+    pub admission_decision_p50_ms: Option<f64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p50_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization: Option<f64>,
+    pub capacity_utilization_p95: Option<f64>,
    pub latency_coverage: f64,
    pub first_token_coverage: f64,
+    pub admission_decision_coverage: f64,
+    pub account_selection_wait_coverage: f64,
+    pub capacity_coverage: f64,
    pub points: Vec<OverviewPerformancePointView>,
 }

@@ -602,6 +671,8 @@ pub struct OverviewCostPointView {
    pub total_tokens: u64,
    pub estimated_cost: Option<String>,
    pub standard_cost: Option<String>,
+    pub no_cache_cost: Option<String>,
+    pub cache_savings: Option<String>,
    pub cached_token_rate: f64,
    pub cache_hit_request_rate: Option<f64>,
 }
@@ -612,7 +683,11 @@ pub struct OverviewCostPointView {
 pub struct OverviewCostView {
    pub estimated_cost: Option<String>,
    pub standard_cost: Option<String>,
+    pub no_cache_cost: Option<String>,
+    pub cache_savings: Option<String>,
+    pub tier_premium: Option<String>,
    pub cost_per_request: Option<String>,
+    pub cost_per_successful_request: Option<String>,
    pub tokens_per_request: f64,
    pub cached_token_rate: f64,
    pub cache_hit_request_rate: Option<f64>,
@@ -661,6 +736,12 @@ pub struct DiagnosticItemView {
    pub request_share: f64,
    pub average_latency_ms: Option<u64>,
    pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub non_completion_rate: f64,
+    pub retry_count: u64,
+    pub retry_rate: f64,
+    pub impact_score: f64,
    pub estimated_cost: Option<String>,
    pub attempt_count: u64,
    pub total_tokens: u64,
@@ -682,20 +763,39 @@ pub struct OpsErrorView {
    pub request_id: Option<String>,
    pub client_api_key_id: Option<String>,
    pub kind: String,
+    pub operation: String,
+    pub protocol: Option<String>,
+    pub client_transport: Option<String>,
    pub provider: Option<String>,
    pub authentication_kind: Option<String>,
    pub account_id: Option<String>,
+    pub account_name: Option<String>,
+    pub account_email: Option<String>,
    pub route: String,
    pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
    pub client_status_code: Option<i64>,
    pub upstream_status_code: Option<i64>,
    pub transport: Option<String>,
    pub attempt_index: Option<u32>,
    pub failure_class: String,
+    pub upstream_send_state: Option<String>,
+    pub provider_error_code: Option<String>,
    pub response_id: Option<String>,
    pub upstream_request_id: Option<String>,
    pub latency_ms: Option<u64>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: Option<bool>,
    pub message: String,
+    /// 上游错误正文或 WebSocket close/error frame 原文；不做脱敏。
+    pub raw_upstream_error: Option<String>,
    pub metadata: OpsErrorMetadataView,
    pub created_at: DateTime<Utc>,
    pub created_at_display: String,
@@ -709,4 +809,16 @@ pub struct OpsErrorMetadataView {
    pub component: String,
    pub attempt_id: Option<String>,
    pub account_label: Option<String>,
+    pub continuation_affinity_hash: Option<String>,
+    pub continuation_previous_response_id_hash: Option<String>,
+    pub continuation_unavailable_reason: Option<String>,
+    pub upstream_connection_id: Option<String>,
+    pub upstream_connection_exit_reason: Option<String>,
+    pub upstream_connection_age_ms: Option<u64>,
+    pub upstream_connection_idle_ms: Option<u64>,
+    pub recovery_request_id: Option<String>,
+    pub recovered_at: Option<DateTime<Utc>>,
+    pub recovery_attempt_count: u32,
+    pub recovery_retry_delay_ms: Option<u64>,
+    pub recovery_total_latency_ms: Option<u64>,
 }
@@ -1,9 +1,9 @@
 //! Admin API 的展示层辅助：数值格式化。
 //!
-//! 按 docs/project-redundancy-boundary-audit.md BE-02 的目标，display 字段最终
-//! 迁移到前端；过渡期统一由本模块提供，避免 accounts/observability 各自维护。
+//! 当前 wire 仍保留 display 字段；统一由本模块提供，避免 accounts/observability
+//! 各自维护格式化规则。

-use gateway_core::accounting::Decimal;
+use gateway_core::metering::Decimal;

 /// 千分位格式化。
 #[must_use]
@@ -3,22 +3,26 @@
 use std::{collections::BTreeMap, fmt};

 use axum::{
-    Json, Router,
+    Router,
    extract::State,
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post},
 };
 use chrono::{DateTime, Utc};
+use gateway_admin::model::client_distribution::{
+    ClientDownloadPackage, CodexDesktopWindowsDownloads,
+};
 use gateway_admin::model::settings::{
    ModelMappings as DomainModelMappings, ReplaceRuntimeSettings, RotationStrategy, RuntimeSettings,
 };
+use gateway_core::policy::CodexClientVersion;
 use gateway_core::routing::{PublicModelId, UpstreamModelId};
 use serde::{Deserialize, Serialize};

 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, WireValidationError,
-    wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    WireValidationError, wire::map_admin_service_error,
 };

 /// 客户端模型到上游模型的全局精确映射。
@@ -34,6 +38,8 @@ pub struct RuntimeSettingsView {
    pub max_concurrent_per_account: u64,
    pub request_interval_ms: u64,
    pub rotation_strategy: String,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
    pub usage_retention_days: u64,
    pub ops_event_retention_days: u64,
    pub audit_retention_days: u64,
@@ -50,6 +56,8 @@ pub struct UpdateRuntimeSettingsRequest {
    pub max_concurrent_per_account: u64,
    pub request_interval_ms: u64,
    pub rotation_strategy: String,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
    pub usage_retention_days: u64,
    pub ops_event_retention_days: u64,
    pub audit_retention_days: u64,
@@ -75,6 +83,14 @@ impl UpdateRuntimeSettingsRequest {
        if RotationStrategy::parse(&self.rotation_strategy).is_none() {
            return Err(WireValidationError::new("rotationStrategy"));
        }
+        validate_optional_client_version(
+            self.min_codex_desktop_version.as_deref(),
+            "minCodexDesktopVersion",
+        )?;
+        validate_optional_client_version(
+            self.min_codex_cli_version.as_deref(),
+            "minCodexCliVersion",
+        )?;
        Ok(())
    }

@@ -90,6 +106,8 @@ impl UpdateRuntimeSettingsRequest {
            request_interval_ms: self.request_interval_ms,
            rotation_strategy: RotationStrategy::parse(&self.rotation_strategy)
                .ok_or_else(|| WireValidationError::new("rotationStrategy"))?,
+            min_codex_desktop_version: self.min_codex_desktop_version,
+            min_codex_cli_version: self.min_codex_cli_version,
            usage_retention_days: u32::try_from(self.usage_retention_days)
                .map_err(|_| WireValidationError::new("settingsUsageRetentionOverflow"))?,
            ops_event_retention_days: u32::try_from(self.ops_event_retention_days)
@@ -109,6 +127,8 @@ impl From<RuntimeSettings> for RuntimeSettingsView {
            max_concurrent_per_account: u64::from(settings.max_concurrent_per_account),
            request_interval_ms: settings.request_interval_ms,
            rotation_strategy: settings.rotation_strategy.as_str().to_owned(),
+            min_codex_desktop_version: settings.min_codex_desktop_version,
+            min_codex_cli_version: settings.min_codex_cli_version,
            usage_retention_days: u64::from(settings.usage_retention_days),
            ops_event_retention_days: u64::from(settings.ops_event_retention_days),
            audit_retention_days: u64::from(settings.audit_retention_days),
@@ -145,6 +165,58 @@ pub struct DeletedAdminApiKey {
    pub message: &'static str,
 }

+#[derive(Debug, Clone, Copy, Default, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+struct ClientDownloadsQuery {
+    refresh: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ClientDownloadPackageView {
+    architecture: String,
+    source: String,
+    version: Option<String>,
+    file_name: String,
+    size_bytes: Option<u64>,
+    download_url: String,
+    expires_at: Option<DateTime<Utc>>,
+}
+
+impl From<ClientDownloadPackage> for ClientDownloadPackageView {
+    fn from(package: ClientDownloadPackage) -> Self {
+        Self {
+            architecture: package.architecture.as_str().to_owned(),
+            source: package.source.as_str().to_owned(),
+            version: package.version,
+            file_name: package.file_name,
+            size_bytes: package.size_bytes,
+            download_url: package.download_url,
+            expires_at: package.expires_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct CodexDesktopWindowsDownloadsView {
+    resolved_at: DateTime<Utc>,
+    cached: bool,
+    warning: Option<String>,
+    packages: Vec<ClientDownloadPackageView>,
+}
+
+impl From<CodexDesktopWindowsDownloads> for CodexDesktopWindowsDownloadsView {
+    fn from(downloads: CodexDesktopWindowsDownloads) -> Self {
+        Self {
+            resolved_at: downloads.resolved_at,
+            cached: downloads.cached,
+            warning: downloads.warning,
+            packages: downloads.packages.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
 impl Default for DeletedAdminApiKey {
    fn default() -> Self {
        Self {
@@ -161,6 +233,10 @@ where
    Router::new()
        .route("/api/admin/settings", get(settings::<S>))
        .route("/api/admin/settings/update", post(update_settings::<S>))
+        .route(
+            "/api/admin/settings/client-downloads/codex-desktop/windows",
+            get(codex_desktop_windows_downloads::<S>),
+        )
        .route(
            "/api/admin/settings/admin-api-key",
            get(admin_api_key_status::<S>),
@@ -175,6 +251,25 @@ where
        )
 }

+async fn codex_desktop_windows_downloads<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ClientDownloadsQuery>,
+) -> impl IntoResponse
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let downloads = state
+        .admin_services()
+        .client_distribution()
+        .codex_desktop_windows(query.refresh)
+        .await;
+    AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(CodexDesktopWindowsDownloadsView::from(downloads)),
+    )
+}
+
 async fn settings<S>(
    _auth: AdminAuth,
    State(state): State<S>,
@@ -197,7 +292,7 @@ where
 async fn update_settings<S>(
    auth: AdminAuth,
    State(state): State<S>,
-    Json(request): Json<UpdateRuntimeSettingsRequest>,
+    AdminJson(request): AdminJson<UpdateRuntimeSettingsRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -322,18 +417,30 @@ fn valid_model_name(value: &str, max_len: usize) -> bool {
        && !value.bytes().any(|byte| byte.is_ascii_control())
 }

+fn validate_optional_client_version(
+    value: Option<&str>,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.is_some_and(|value| CodexClientVersion::parse(value).is_err()) {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
 fn map_wire_error(error: WireValidationError) -> AdminError {
    let message = match error.field() {
-        "settingsRefreshConcurrencyOverflow" => "Invalid refreshConcurrency".to_owned(),
-        "settingsMaxConcurrencyOverflow" => "Invalid maxConcurrentPerAccount".to_owned(),
-        "settingsUsageRetentionOverflow" => "Invalid usageRetentionDays".to_owned(),
-        "settingsOpsRetentionOverflow" => "Invalid opsEventRetentionDays".to_owned(),
-        "settingsAuditRetentionOverflow" => "Invalid auditRetentionDays".to_owned(),
-        field => format!("Invalid field: {field}"),
+        "settingsRefreshConcurrencyOverflow" => "refreshConcurrency 不合法".to_owned(),
+        "settingsMaxConcurrencyOverflow" => "maxConcurrentPerAccount 不合法".to_owned(),
+        "settingsUsageRetentionOverflow" => "usageRetentionDays 不合法".to_owned(),
+        "settingsOpsRetentionOverflow" => "opsEventRetentionDays 不合法".to_owned(),
+        "settingsAuditRetentionOverflow" => "auditRetentionDays 不合法".to_owned(),
+        "minCodexDesktopVersion" => "Codex Desktop 最低版本格式不合法".to_owned(),
+        "minCodexCliVersion" => "Codex CLI 最低版本格式不合法".to_owned(),
+        field => format!("{field} 字段不合法"),
    };
    AdminError::bad_request(message)
 }

 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Settings repository unavailable")
+    map_admin_service_error(error)
 }
@@ -5,8 +5,8 @@
 use std::convert::Infallible;

 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
    http::StatusCode,
    response::{
        IntoResponse,
@@ -23,7 +23,7 @@ use gateway_admin::model::system::{
 use serde::{Deserialize, Serialize};

 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
    wire::map_admin_service_error,
 };

@@ -251,7 +251,7 @@ where
 async fn update_detail<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    Query(query): Query<UpdateDetailQuery>,
+    AdminQuery(query): AdminQuery<UpdateDetailQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -290,7 +290,7 @@ where
 async fn perform_update<S>(
    _auth: AdminAuth,
    State(state): State<S>,
-    payload: Option<Json<UpdateRequest>>,
+    payload: Option<AdminJson<UpdateRequest>>,
 ) -> Result<impl IntoResponse, AdminError>
 where
    S: AdminSessionState + Send + Sync,
@@ -298,7 +298,7 @@ where
    let result = state
        .admin_services()
        .system()
-        .perform_update(payload.map(|Json(value)| value.into_target_version()))
+        .perform_update(payload.map(|AdminJson(value)| value.into_target_version()))
        .await
        .map_err(map_system_error)?;
    let SystemOperationAccepted::Update {
@@ -309,7 +309,7 @@ where
        target_version,
    } = result
    else {
-        return Err(AdminError::internal("Invalid system update result"));
+        return Err(AdminError::internal());
    };
    Ok(AdminResponse::new(
        StatusCode::OK,
@@ -361,7 +361,7 @@ where
        need_restart,
    } = result
    else {
-        return Err(AdminError::internal("Invalid system rollback result"));
+        return Err(AdminError::internal());
    };
    Ok(AdminResponse::new(
        StatusCode::OK,
@@ -391,7 +391,7 @@ where
        message,
    } = result
    else {
-        return Err(AdminError::internal("Invalid system restart result"));
+        return Err(AdminError::internal());
    };
    Ok(AdminResponse::new(
        StatusCode::OK,
@@ -477,5 +477,5 @@ const fn update_event_level_name(level: SystemUpdateEventLevel) -> &'static str
 }

 fn map_system_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "System operation unavailable")
+    map_admin_service_error(error)
 }
@@ -116,6 +116,8 @@ impl AdminErrorCode {
    pub const USAGE_RECORD_ACCOUNTS: Self = Self(50002);
    /// 上游网关失败。
    pub const BAD_GATEWAY: Self = Self(50201);
+    /// 不可逆上游操作的执行结果未知。
+    pub const UPSTREAM_RESULT_UNKNOWN: Self = Self(50202);
    /// 依赖的服务暂不可用。
    pub const SERVICE_UNAVAILABLE: Self = Self(50301);

@@ -165,6 +167,89 @@ pub struct AdminError {
    body: AdminErrorBody,
 }

+#[derive(Debug, Clone, Copy)]
+struct AdminErrorSpec {
+    status: StatusCode,
+    code: AdminErrorCode,
+    message: &'static str,
+}
+
+impl AdminErrorSpec {
+    const fn new(status: StatusCode, code: AdminErrorCode, message: &'static str) -> Self {
+        Self {
+            status,
+            code,
+            message,
+        }
+    }
+}
+
+const MALFORMED_JSON: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_REQUEST,
+    AdminErrorCode::MALFORMED_JSON,
+    "请求体不是合法 JSON",
+);
+const BAD_REQUEST: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_REQUEST,
+    AdminErrorCode::BAD_REQUEST,
+    "请求参数不合法",
+);
+const INVALID_TIME_RANGE: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_REQUEST,
+    AdminErrorCode::INVALID_TIME_RANGE,
+    "时间范围不合法",
+);
+const SESSION_REQUIRED: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::UNAUTHORIZED,
+    AdminErrorCode::SESSION_REQUIRED,
+    "需要管理员登录",
+);
+const INVALID_CREDENTIALS: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::UNAUTHORIZED,
+    AdminErrorCode::INVALID_CREDENTIALS,
+    "管理员用户名或密码错误",
+);
+const INVALID_API_KEY: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::UNAUTHORIZED,
+    AdminErrorCode::INVALID_API_KEY,
+    "管理 API Key 无效",
+);
+const ADMIN_ROUTE_NOT_FOUND: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::NOT_FOUND,
+    AdminErrorCode::NOT_FOUND,
+    "管理接口不存在",
+);
+const METHOD_NOT_ALLOWED: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::METHOD_NOT_ALLOWED,
+    AdminErrorCode::BAD_REQUEST,
+    "请求方法不受支持",
+);
+const TOO_MANY_LOGIN_ATTEMPTS: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::TOO_MANY_REQUESTS,
+    AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
+    "登录尝试过多，请稍后重试",
+);
+const INTERNAL: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::INTERNAL_SERVER_ERROR,
+    AdminErrorCode::INTERNAL,
+    "服务内部错误",
+);
+const BAD_GATEWAY: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_GATEWAY,
+    AdminErrorCode::BAD_GATEWAY,
+    "上游服务请求失败",
+);
+const UPSTREAM_RESULT_UNKNOWN: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::BAD_GATEWAY,
+    AdminErrorCode::UPSTREAM_RESULT_UNKNOWN,
+    "上游执行结果未知，请刷新状态后再决定是否重试",
+);
+const SERVICE_UNAVAILABLE: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::SERVICE_UNAVAILABLE,
+    AdminErrorCode::SERVICE_UNAVAILABLE,
+    "依赖服务暂不可用",
+);
+
 impl AdminError {
    fn new(status: StatusCode, code: AdminErrorCode, message: impl Into<String>) -> Self {
        Self {
@@ -173,44 +258,48 @@ impl AdminError {
        }
    }

+    fn from_spec(spec: AdminErrorSpec) -> Self {
+        Self::new(spec.status, spec.code, spec.message)
+    }
+
+    pub fn malformed_json() -> Self {
+        Self::from_spec(MALFORMED_JSON)
+    }
+
+    pub fn invalid_request(status: StatusCode, message: &'static str) -> Self {
+        Self::new(status, BAD_REQUEST.code, message)
+    }
+
+    pub fn invalid_time_range() -> Self {
+        Self::from_spec(INVALID_TIME_RANGE)
+    }
+
+    pub fn admin_route_not_found() -> Self {
+        Self::from_spec(ADMIN_ROUTE_NOT_FOUND)
+    }
+
+    pub fn method_not_allowed() -> Self {
+        Self::from_spec(METHOD_NOT_ALLOWED)
+    }
+
    pub fn bad_request(message: impl Into<String>) -> Self {
-        Self::new(
-            StatusCode::BAD_REQUEST,
-            AdminErrorCode::BAD_REQUEST,
-            message,
-        )
+        Self::new(BAD_REQUEST.status, BAD_REQUEST.code, message)
    }

    pub fn admin_session_required() -> Self {
-        Self::new(
-            StatusCode::UNAUTHORIZED,
-            AdminErrorCode::SESSION_REQUIRED,
-            "Admin session required",
-        )
+        Self::from_spec(SESSION_REQUIRED)
    }

    pub fn invalid_admin_credentials() -> Self {
-        Self::new(
-            StatusCode::UNAUTHORIZED,
-            AdminErrorCode::INVALID_CREDENTIALS,
-            "Invalid admin credentials",
-        )
+        Self::from_spec(INVALID_CREDENTIALS)
    }

    pub fn invalid_admin_api_key() -> Self {
-        Self::new(
-            StatusCode::UNAUTHORIZED,
-            AdminErrorCode::INVALID_API_KEY,
-            "Invalid admin API key",
-        )
+        Self::from_spec(INVALID_API_KEY)
    }

    pub fn too_many_login_attempts() -> Self {
-        Self::new(
-            StatusCode::TOO_MANY_REQUESTS,
-            AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
-            "Too many admin login attempts",
-        )
+        Self::from_spec(TOO_MANY_LOGIN_ATTEMPTS)
    }

    pub fn conflict(message: impl Into<String>) -> Self {
@@ -221,47 +310,37 @@ impl AdminError {
        Self::new(StatusCode::NOT_FOUND, AdminErrorCode::NOT_FOUND, message)
    }

-    pub fn internal(message: impl Into<String>) -> Self {
-        Self::new(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            AdminErrorCode::INTERNAL,
-            message,
-        )
+    pub fn internal() -> Self {
+        Self::from_spec(INTERNAL)
    }

-    pub fn bad_gateway(message: impl Into<String>) -> Self {
-        Self::new(
-            StatusCode::BAD_GATEWAY,
-            AdminErrorCode::BAD_GATEWAY,
-            message,
-        )
+    pub fn bad_gateway() -> Self {
+        Self::from_spec(BAD_GATEWAY)
    }

-    pub fn service_unavailable(message: impl Into<String>) -> Self {
-        Self::new(
-            StatusCode::SERVICE_UNAVAILABLE,
-            AdminErrorCode::SERVICE_UNAVAILABLE,
-            message,
-        )
+    pub fn upstream_result_unknown() -> Self {
+        Self::from_spec(UPSTREAM_RESULT_UNKNOWN)
+    }
+
+    pub fn service_unavailable() -> Self {
+        Self::from_spec(SERVICE_UNAVAILABLE)
    }
 }

 /// 把管理用例的稳定错误分类映射到既有 HTTP 错误 contract。
-pub(crate) fn map_admin_service_error(
-    error: gateway_admin::model::AdminError,
-    unavailable_message: &'static str,
-) -> AdminError {
+pub(crate) fn map_admin_service_error(error: gateway_admin::model::AdminError) -> AdminError {
    use gateway_admin::model::AdminErrorKind;

    match error.kind() {
-        AdminErrorKind::Invalid => AdminError::bad_request(error.to_string()),
+        AdminErrorKind::Invalid => AdminError::bad_request(error.message()),
        AdminErrorKind::Unauthorized => AdminError::admin_session_required(),
-        AdminErrorKind::NotFound => AdminError::not_found(error.to_string()),
-        AdminErrorKind::Conflict => AdminError::conflict(error.to_string()),
+        AdminErrorKind::NotFound => AdminError::not_found(error.message()),
+        AdminErrorKind::Conflict => AdminError::conflict(error.message()),
        AdminErrorKind::RateLimited => AdminError::too_many_login_attempts(),
-        AdminErrorKind::BadGateway => AdminError::bad_gateway(error.to_string()),
-        AdminErrorKind::Unavailable => AdminError::service_unavailable(unavailable_message),
-        AdminErrorKind::Internal => AdminError::internal(error.to_string()),
+        AdminErrorKind::BadGateway => AdminError::bad_gateway(),
+        AdminErrorKind::UpstreamResultUnknown => AdminError::upstream_result_unknown(),
+        AdminErrorKind::Unavailable => AdminError::service_unavailable(),
+        AdminErrorKind::Internal => AdminError::internal(),
    }
 }

@@ -1,4 +1,4 @@
-//! `/healthz` 对 Core、Store 与 Host worker 健康事实的聚合。
+//! `/healthz` 对 Core、Store 与 Host 关键 worker 健康事实的聚合。

 use std::sync::Arc;
 use std::time::Duration;
@@ -6,8 +6,10 @@ use std::time::Duration;
 use axum::{extract::State, http::StatusCode};
 use futures::future::join_all;
 use gateway_core::health::{
-    HealthProbe, HealthState, WorkerHealthSnapshot, WorkerHealthSource, WorkerRuntimeState,
+    HealthProbe, HealthState, WorkerHealthKey, WorkerHealthSnapshot, WorkerHealthSource,
+    WorkerRuntimeState,
 };
+use gateway_core::task::WorkerKind;

 use crate::ApiState;

@@ -32,7 +34,13 @@ impl HealthStatus {
    }

    pub(crate) async fn healthy(&self) -> bool {
-        if !self.workers.snapshot().iter().all(worker_is_healthy) {
+        if !self
+            .workers
+            .snapshot()
+            .iter()
+            .filter(|worker| worker_affects_healthz(worker))
+            .all(worker_is_healthy)
+        {
            return false;
        }
        let checks = self.probes.iter().map(|probe| probe.check());
@@ -54,6 +62,16 @@ pub(crate) async fn healthz(State(state): State<ApiState>) -> StatusCode {
    }
 }

+fn worker_affects_healthz(worker: &WorkerHealthSnapshot) -> bool {
+    let WorkerHealthKey::Task(id) = &worker.key else {
+        return false;
+    };
+    !matches!(
+        id.kind(),
+        WorkerKind::OAuthRefresh | WorkerKind::QuotaCatalogHealth
+    )
+}
+
 fn worker_is_healthy(worker: &WorkerHealthSnapshot) -> bool {
    match worker.state {
        WorkerRuntimeState::Disabled | WorkerRuntimeState::Standby => true,
@@ -180,13 +180,16 @@ pub fn initialize(
                "request",
                request_id = %request_id,
                method = %request.method().as_str(),
-                uri = %request
-                    .uri()
-                    .path_and_query()
-                    .map(axum::http::uri::PathAndQuery::as_str)
-                    .unwrap_or_default(),
+                uri = %request.uri().path(),
            )
        }
+    })
+    .on_request(|_request: &Request<_>, _span: &tracing::Span| {
+        tracing::info!(target: "request_trace", stage = "http.received", "HTTP request received");
+    })
+    .on_response(|response: &axum::http::Response<_>, latency: Duration, _span: &tracing::Span| {
+        tracing::info!(target: "request_trace", stage = "http.response", status = response.status().as_u16(),
+            headers_ms = latency.as_millis(), "HTTP response headers ready");
    });
    let router = router
        .layer(PropagateRequestIdLayer::new(request_id_header.clone()))
@@ -5,9 +5,13 @@ use axum::{
    response::{IntoResponse, Response},
 };
 use gateway_core::engine::execution::AuthenticatedClient;
+use gateway_core::policy::{ClientVersionRejection, CodexClientKind, CodexClientVersion};

 use super::{
-    error::{missing_client_api_key_response, runtime_unavailable_response},
+    error::{
+        client_version_rejection_response, missing_client_api_key_response,
+        runtime_unavailable_response,
+    },
    service::OpenAiService,
 };

@@ -26,6 +30,44 @@ pub enum ClientApiKeyAuthError {
    RuntimeUnavailable,
 }

+/// Client API Key 或最低版本准入失败。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ClientAccessError {
+    Authentication(ClientApiKeyAuthError),
+    Version(ClientVersionRejection),
+}
+
+impl From<ClientApiKeyAuthError> for ClientAccessError {
+    fn from(error: ClientApiKeyAuthError) -> Self {
+        Self::Authentication(error)
+    }
+}
+
+impl From<ClientVersionRejection> for ClientAccessError {
+    fn from(error: ClientVersionRejection) -> Self {
+        Self::Version(error)
+    }
+}
+
+/// 从有界请求头中识别出的客户端及其可选合法版本。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct IdentifiedCodexClient {
+    kind: CodexClientKind,
+    version: Option<CodexClientVersion>,
+}
+
+impl IdentifiedCodexClient {
+    #[must_use]
+    pub const fn kind(&self) -> CodexClientKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub const fn version(&self) -> Option<&CodexClientVersion> {
+        self.version.as_ref()
+    }
+}
+
 impl ClientApiKeyAuthError {
    /// 返回可用于日志和指标的稳定失败原因。
    #[must_use]
@@ -67,19 +109,121 @@ pub fn bearer_client_api_key(headers: &HeaderMap) -> Result<&str, ClientApiKeyAu
 pub(crate) fn authenticate_client(
    service: &OpenAiService,
    headers: &HeaderMap,
-) -> Result<AuthenticatedClient, ClientApiKeyAuthError> {
-    bearer_client_api_key(headers).and_then(|key| service.authenticate(key))
+) -> Result<AuthenticatedClient, ClientAccessError> {
+    let key = bearer_client_api_key(headers)?;
+    let client = service.authenticate(key)?;
+    if let Some(identified) = identify_codex_client(headers) {
+        client
+            .snapshot()
+            .min_codex_client_versions()
+            .enforce(identified.kind(), identified.version())?;
+    }
+    Ok(client)
 }

-pub(crate) fn authentication_error_response(error: ClientApiKeyAuthError) -> Response {
-    log_client_api_key_auth_failure(error);
-    if error == ClientApiKeyAuthError::RuntimeUnavailable {
-        runtime_unavailable_response().into_response()
-    } else {
-        missing_client_api_key_response().into_response()
+pub(crate) fn client_access_error_response(error: ClientAccessError) -> Response {
+    match error {
+        ClientAccessError::Authentication(error) => {
+            log_client_api_key_auth_failure(error);
+            if error == ClientApiKeyAuthError::RuntimeUnavailable {
+                runtime_unavailable_response().into_response()
+            } else {
+                missing_client_api_key_response().into_response()
+            }
+        }
+        ClientAccessError::Version(error) => {
+            tracing::info!(
+                client = error.kind().as_str(),
+                current_version = error.current().map(ToString::to_string),
+                min_version = %error.min(),
+                "Codex client version requirement rejected request"
+            );
+            client_version_rejection_response(&error).into_response()
+        }
    }
 }

+/// Desktop 优先于其内嵌的 CLI/Core 标记；未知客户端保持兼容并返回 `None`。
+#[must_use]
+pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClient> {
+    const MAXIMUM_HEADER_LENGTH: usize = 4096;
+
+    let originator = bounded_ascii_header(headers, "originator", MAXIMUM_HEADER_LENGTH);
+    let user_agent = bounded_ascii_header(headers, "user-agent", MAXIMUM_HEADER_LENGTH);
+    let is_desktop = originator.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
+        || user_agent.is_some_and(|value| contains_ascii_case_insensitive(value, "Codex Desktop"));
+    if is_desktop {
+        let explicit_version = bounded_ascii_header(headers, "version", MAXIMUM_HEADER_LENGTH);
+        let version = match explicit_version {
+            Some(value) => CodexClientVersion::parse(value).ok(),
+            None => user_agent
+                .and_then(desktop_version_from_user_agent)
+                .and_then(|value| CodexClientVersion::parse(value).ok()),
+        };
+        return Some(IdentifiedCodexClient {
+            kind: CodexClientKind::Desktop,
+            version,
+        });
+    }
+
+    let user_agent = user_agent?;
+    for product in user_agent.split(|character: char| {
+        character.is_ascii_whitespace() || matches!(character, '(' | ')' | ';' | ',' | '[' | ']')
+    }) {
+        for prefix in ["codex_cli_rs", "codex-cli"] {
+            if product.eq_ignore_ascii_case(prefix) {
+                return Some(IdentifiedCodexClient {
+                    kind: CodexClientKind::Cli,
+                    version: None,
+                });
+            }
+            let Some((name, version)) = product.split_once('/') else {
+                continue;
+            };
+            if name.eq_ignore_ascii_case(prefix) {
+                return Some(IdentifiedCodexClient {
+                    kind: CodexClientKind::Cli,
+                    version: CodexClientVersion::parse(version).ok(),
+                });
+            }
+        }
+    }
+    None
+}
+
+fn bounded_ascii_header<'a>(
+    headers: &'a HeaderMap,
+    name: &'static str,
+    maximum_length: usize,
+) -> Option<&'a str> {
+    let value = headers.get(name)?.to_str().ok()?;
+    if !value.is_ascii() {
+        return None;
+    }
+    Some(&value[..value.len().min(maximum_length)])
+}
+
+fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
+    let marker = "Codex Desktop;";
+    let start = find_ascii_case_insensitive(user_agent, marker)? + marker.len();
+    let version = user_agent[start..]
+        .trim_start()
+        .split([')', ' ', ';', ','])
+        .next()?;
+    (!version.is_empty()).then_some(version)
+}
+
+fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
+    find_ascii_case_insensitive(haystack, needle).is_some()
+}
+
+fn find_ascii_case_insensitive(haystack: &str, needle: &str) -> Option<usize> {
+    haystack
+        .as_bytes()
+        .windows(needle.len())
+        .position(|window| window.eq_ignore_ascii_case(needle.as_bytes()))
+}
+
 fn log_client_api_key_auth_failure(error: ClientApiKeyAuthError) {
    match error {
        ClientApiKeyAuthError::RuntimeUnavailable => {
@@ -0,0 +1,124 @@
+//! OpenAI Provider 原生非流式 JSON 端点的公共交付边界。
+
+use axum::{
+    body::{Body, Bytes},
+    http::{HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
+    response::{IntoResponse, Response},
+};
+use gateway_core::engine::execution::StartedExecution;
+use gateway_core::event::{ProviderEvent, ProviderResponseHeader};
+
+use super::{
+    error::{engine_error_response, protocol_error_response},
+    responses::{PendingExecution, ProtocolError, ProtocolErrorBody},
+};
+
+/// 收集一个 Provider 原生 JSON 响应，并在 Core commit 后按原始 bytes 交付。
+pub(super) async fn collect_raw_json_response(started: StartedExecution) -> Response {
+    let mut execution = PendingExecution::new(started.session);
+    let Some(session) = execution.session_mut() else {
+        return invalid_upstream_response();
+    };
+    let events = match session.collect_uncommitted().await {
+        Ok(events) => events,
+        Err(error) => {
+            let response = engine_error_response(&error);
+            return execution.record_response_status(response).await;
+        }
+    };
+    let body = match raw_json_body(events) {
+        Some(body) => body,
+        None => {
+            let response = invalid_upstream_response();
+            let response = execution.record_response_status(response).await;
+            execution.cancel_and_finalize().await;
+            return response;
+        }
+    };
+    let status = session
+        .response_status_code()
+        .and_then(|status| StatusCode::from_u16(status).ok())
+        .filter(StatusCode::is_success)
+        .unwrap_or(StatusCode::OK);
+    let response_headers = session.response_headers().to_vec();
+    let response = json_body_response(body, status, &response_headers);
+    let Some(session) = execution.session_mut() else {
+        return invalid_upstream_response();
+    };
+    if let Err(error) = session.commit_downstream(Some(status.as_u16())).await {
+        execution.cancel_and_finalize().await;
+        let response = engine_error_response(&error);
+        return execution.record_response_status(response).await;
+    }
+    if !session.is_finalized() {
+        execution.cancel_and_finalize().await;
+        return invalid_upstream_response();
+    }
+    execution.disarm();
+    response
+}
+
+fn raw_json_body(events: Vec<ProviderEvent>) -> Option<Bytes> {
+    let mut body = None;
+    for event in events {
+        let (_, wire) = event.into_parts();
+        let Some(wire) = wire.filter(|wire| wire.protocol() == "openai") else {
+            continue;
+        };
+        let Some(raw) = wire.into_raw_json_body() else {
+            continue;
+        };
+        if body.replace(raw).is_some() {
+            return None;
+        }
+    }
+    body
+}
+
+fn json_body_response(
+    body: Bytes,
+    status: StatusCode,
+    response_headers: &[ProviderResponseHeader],
+) -> Response {
+    let mut response = Response::new(Body::from(body));
+    *response.status_mut() = status;
+    response
+        .headers_mut()
+        .insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+    apply_response_headers(response, response_headers)
+}
+
+fn apply_response_headers(
+    mut response: Response,
+    response_headers: &[ProviderResponseHeader],
+) -> Response {
+    let connection_options = super::responses::response_connection_options(response_headers);
+    for header in response_headers {
+        if !super::responses::response_header_is_forwardable(header.name(), &connection_options) {
+            continue;
+        }
+        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+            continue;
+        };
+        let Ok(value) = HeaderValue::from_bytes(header.value()) else {
+            continue;
+        };
+        response.headers_mut().append(name, value);
+    }
+    response
+}
+
+fn invalid_upstream_response() -> Response {
+    protocol_error_response(
+        StatusCode::BAD_GATEWAY,
+        ProtocolErrorBody {
+            error: ProtocolError {
+                kind: "server_error",
+                code: "invalid_upstream_response",
+                message: "The gateway could not forward the upstream JSON response.".to_owned(),
+                param: None,
+            },
+        },
+    )
+    .into_response()
+}
@@ -9,6 +9,7 @@ use axum::{
 use gateway_core::{
    engine::EngineError,
    error::{GatewayError, GatewayErrorKind},
+    policy::{ClientVersionRejection, CodexClientKind},
 };
 use serde_json::{Value, json};

@@ -58,6 +59,47 @@ pub fn runtime_unavailable_response() -> (StatusCode, Json<Value>) {
    )
 }

+/// 已识别 Codex 客户端不满足最低版本要求。
+pub fn client_version_rejection_response(
+    rejection: &ClientVersionRejection,
+) -> (StatusCode, Json<Value>) {
+    let client_label = match rejection.kind() {
+        CodexClientKind::Desktop => "Codex Desktop",
+        CodexClientKind::Cli => "Codex CLI",
+    };
+    let (message, code, current_version) = match rejection.current() {
+        Some(current) => (
+            format!(
+                "{client_label} {current} is below the minimum required version {}. Upgrade {client_label} and retry.",
+                rejection.min()
+            ),
+            "client_version_too_old",
+            Some(current.to_string()),
+        ),
+        None => (
+            format!(
+                "A valid {client_label} version is required. Upgrade to version {} or newer and retry.",
+                rejection.min()
+            ),
+            "client_version_unavailable",
+            None,
+        ),
+    };
+    (
+        StatusCode::UPGRADE_REQUIRED,
+        Json(json!({
+            "error": {
+                "message": message,
+                "type": "invalid_request_error",
+                "code": code,
+                "client": rejection.kind().as_str(),
+                "current_version": current_version,
+                "min_version": rejection.min().to_string()
+            }
+        })),
+    )
+}
+
 /// 对外模型不存在。
 pub fn model_not_found_response() -> (StatusCode, Json<Value>) {
    openai_error_response(
@@ -0,0 +1,119 @@
+//! Codex Images 非流式 HTTP adapter。
+
+use std::net::SocketAddr;
+
+use axum::{
+    body::Bytes,
+    extract::{Extension, State, connect_info::ConnectInfo},
+    http::HeaderMap,
+    response::Response,
+};
+use gateway_core::error::{GatewayError, GatewayErrorKind};
+use gateway_core::operation::{ImageRequest, ImageRequestKind, Operation, RawJsonPayload};
+use serde_json::Value;
+
+use crate::ApiState;
+use crate::openai::{
+    auth::{authenticate_client, client_access_error_response},
+    endpoint::collect_raw_json_response,
+    error::gateway_error_response,
+    responses::{OpenAiRequestHeaders, request_client_context},
+};
+
+const OPENAI_PROTOCOL: &str = "openai";
+const IMAGE_TURN_ID_CONTEXT_KEY: &str = "image_turn_id";
+
+/// `POST /v1/images/generations`。
+pub(crate) async fn image_generations(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    handle_image_request(
+        state,
+        connect_info,
+        headers,
+        body,
+        ImageRequestKind::Generation,
+        "/v1/images/generations",
+    )
+    .await
+}
+
+/// `POST /v1/images/edits`。
+pub(crate) async fn image_edits(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    handle_image_request(
+        state,
+        connect_info,
+        headers,
+        body,
+        ImageRequestKind::Edit,
+        "/v1/images/edits",
+    )
+    .await
+}
+
+async fn handle_image_request(
+    state: ApiState,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+    kind: ImageRequestKind,
+    endpoint: &'static str,
+) -> Response {
+    let service = state.openai();
+    let client = match authenticate_client(service, &headers) {
+        Ok(client) => client,
+        Err(error) => return client_access_error_response(error),
+    };
+    let (client_ip, user_agent) = request_client_context(
+        &headers,
+        connect_info.map(|Extension(ConnectInfo(address))| address),
+    );
+    let operation = match image_operation(body, &headers, kind) {
+        Ok(operation) => operation,
+        Err(error) => return gateway_error_response(&error),
+    };
+    let started = match service
+        .start_provider_endpoint(client, operation, client_ip, user_agent, endpoint)
+        .await
+    {
+        Ok(started) => started,
+        Err(error) => return gateway_error_response(&error),
+    };
+    collect_raw_json_response(started).await
+}
+
+fn image_operation(
+    body: Bytes,
+    headers: &HeaderMap,
+    kind: ImageRequestKind,
+) -> Result<Operation, GatewayError> {
+    let mut context = OpenAiRequestHeaders::from_headers(headers).session_context();
+    if let Some(turn_id) = headers
+        .get("x-codex-image-turn-id")
+        .and_then(|value| value.to_str().ok())
+    {
+        context.insert(
+            IMAGE_TURN_ID_CONTEXT_KEY.to_owned(),
+            Value::String(turn_id.to_owned()),
+        );
+    }
+    let payload = RawJsonPayload::new(OPENAI_PROTOCOL, body)
+        .map_err(|_| {
+            GatewayError::new(
+                GatewayErrorKind::Internal,
+                "OpenAI protocol identifier is invalid",
+            )
+        })?
+        .with_context(context);
+    Ok(Operation::GenerateImage(ImageRequest::from_raw_json(
+        kind, payload,
+    )))
+}
@@ -0,0 +1,5 @@
+//! OpenAI/Codex Images JSON 透明 adapter。
+
+mod http;
+
+pub(crate) use http::{image_edits, image_generations};
@@ -1,8 +1,11 @@
 //! OpenAI 客户端协议 adapter。

 pub mod auth;
+mod endpoint;
 pub mod error;
+pub mod images;
 pub mod models;
 pub mod responses;
 pub mod router;
+pub mod search;
 pub(crate) mod service;
@@ -13,7 +13,7 @@ use serde_json::{Value, json};
 use crate::ApiState;

 use super::{
-    auth::{authenticate_client, authentication_error_response},
+    auth::{authenticate_client, client_access_error_response},
    error::model_not_found_response,
 };

@@ -34,7 +34,7 @@ pub(crate) async fn models(
    let service = state.openai();
    let client = match authenticate_client(service, &headers) {
        Ok(client) => client,
-        Err(error) => return authentication_error_response(error),
+        Err(error) => return client_access_error_response(error),
    };

    if query
@@ -81,7 +81,7 @@ pub(crate) async fn model_detail(
    let service = state.openai();
    let client = match authenticate_client(service, &headers) {
        Ok(client) => client,
-        Err(error) => return authentication_error_response(error),
+        Err(error) => return client_access_error_response(error),
    };
    let Ok(public_model) = PublicModelId::new(model_id) else {
        return model_not_found_response().into_response();
@@ -97,50 +97,6 @@ pub(crate) async fn model_detail(
        .into_response()
 }

-/// `GET /v1/models/catalog`。
-///
-/// 新架构的目录由 core 按客户端 Provider 范围裁剪；这里不读取或重建任一
-/// Provider 的 wire catalog，只恢复 Codex 客户端依赖的稳定展示合同。
-pub(crate) async fn model_catalog(State(state): State<ApiState>, headers: HeaderMap) -> Response {
-    let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
-        Ok(client) => client,
-        Err(error) => return authentication_error_response(error),
-    };
-    let models = service
-        .public_models(&client)
-        .into_iter()
-        .map(|model| catalog_model_json(model.as_str()))
-        .collect::<Vec<_>>();
-
-    (StatusCode::OK, Json(models)).into_response()
-}
-
-/// `GET /v1/models/{model_id}/info`。
-pub(crate) async fn model_info(
-    State(state): State<ApiState>,
-    headers: HeaderMap,
-    Path(model_id): Path<String>,
-) -> Response {
-    let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
-        Ok(client) => client,
-        Err(error) => return authentication_error_response(error),
-    };
-    let Ok(public_model) = PublicModelId::new(model_id) else {
-        return model_not_found_response().into_response();
-    };
-    if !service.contains_public_model(&client, &public_model) {
-        return model_not_found_response().into_response();
-    }
-
-    (
-        StatusCode::OK,
-        Json(catalog_model_json(public_model.as_str())),
-    )
-        .into_response()
-}
-
 fn openai_model_json(id: &str) -> Value {
    json!({
        "id": id,
@@ -150,22 +106,6 @@ fn openai_model_json(id: &str) -> Value {
    })
 }

-fn catalog_model_json(id: &str) -> Value {
-    json!({
-        "id": id,
-        "displayName": id,
-        "description": "",
-        "isDefault": false,
-        "supportedReasoningEfforts": [],
-        "defaultReasoningEffort": "",
-        "inputModalities": ["text"],
-        "outputModalities": ["text"],
-        "supportsPersonality": false,
-        "upgrade": Value::Null,
-        "source": "gateway",
-    })
-}
-
 fn codex_model_json(profile: &PublicModelProfile, index: usize) -> Value {
    let id = profile.model().as_str();
    let presentation = profile.presentation();
@@ -3,6 +3,7 @@
 use std::collections::VecDeque;
 use std::convert::Infallible;
 use std::net::{IpAddr, SocketAddr};
+use std::time::Duration;

 use axum::{
    body::{Body, Bytes},
@@ -13,9 +14,10 @@ use axum::{
    },
    response::{IntoResponse, Response},
 };
-use futures::stream;
-use gateway_core::engine::CommitRequirement;
+use futures::{StreamExt, stream};
+use gateway_core::diagnostics::TraceContext;
 use gateway_core::engine::execution::{ClientTransport, ExecutionSession, StartedExecution};
+use gateway_core::engine::{CommitRequirement, EngineError};
 use gateway_core::error::{GatewayError, GatewayErrorKind};
 use gateway_core::event::{ProviderEvent, ProviderResponseHeader};
 use gateway_core::lifecycle::ConnectionGuard;
@@ -23,7 +25,7 @@ use gateway_protocol::openai::sse::{DONE_SSE_FRAME, response_failed_sse_event_wi

 use crate::ApiState;
 use crate::openai::{
-    auth::{authenticate_client, authentication_error_response},
+    auth::{authenticate_client, client_access_error_response},
    error::{
        engine_error_response, gateway_error_contract, gateway_error_from_engine,
        gateway_error_response, protocol_error_response, runtime_unavailable_response,
@@ -32,46 +34,25 @@ use crate::openai::{

 use super::{
    OpenAiResponsesEncoder, ProtocolErrorBody, ResponseEncodeError,
-    request::{decode_request_with_headers, decode_review_request_with_headers},
+    request::decode_request_with_headers,
 };

+const SSE_KEEPALIVE_INTERVAL: Duration = Duration::from_secs(15);
+
 /// `POST /v1/responses`。
 pub(crate) async fn responses(
    State(state): State<ApiState>,
    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    ingress_id: Option<Extension<tower_http::request_id::RequestId>>,
    headers: HeaderMap,
    body: Bytes,
-) -> Response {
-    handle_responses(state, connect_info, headers, body, false).await
-}
-
-/// `POST /v1/responses/review`。
-pub(crate) async fn review_responses(
-    State(state): State<ApiState>,
-    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
-    headers: HeaderMap,
-    body: Bytes,
-) -> Response {
-    handle_responses(state, connect_info, headers, body, true).await
-}
-
-async fn handle_responses(
-    state: ApiState,
-    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
-    headers: HeaderMap,
-    body: Bytes,
-    review: bool,
 ) -> Response {
    let service = state.openai();
    let client = match authenticate_client(service, &headers) {
        Ok(client) => client,
-        Err(error) => return authentication_error_response(error),
+        Err(error) => return client_access_error_response(error),
    };
-    let decoded = match if review {
-        decode_review_request_with_headers(&body, &headers)
-    } else {
-        decode_request_with_headers(&body, &headers)
-    } {
+    let decoded = match decode_request_with_headers(&body, &headers) {
        Ok(decoded) => decoded,
        Err(error) => {
            return protocol_error_response(StatusCode::BAD_REQUEST, error.protocol_body());
@@ -100,30 +81,36 @@ async fn handle_responses(
            } else {
                ClientTransport::HttpJson
            },
-            if review {
-                "/v1/responses/review"
-            } else {
-                "/v1/responses"
-            },
+            "/v1/responses",
        )
        .await
    {
        Ok(started) => started,
        Err(error) => return gateway_error_response(&error),
    };
+    let trace = started.session.trace();
+    trace.headers("client.request", serde_json::json!({
+        "ingressRequestId": ingress_id.as_ref().and_then(|Extension(id)| id.header_value().to_str().ok()),
+    }), headers.iter().map(|(name, value)| (name.as_str(), value.as_bytes())));
+    trace.capture("client.request.body", &body);
+    let request_id_header = HeaderValue::from_str(started.request_id.as_str()).ok();
    let StartedExecution {
        stream, session, ..
    } = started;
-    if stream {
+    let mut response = if stream {
        stream_execution_response(session, connection_guard).await
    } else {
        drop(connection_guard);
        collect_execution_response(session).await
+    };
+    if let Some(id) = request_id_header {
+        response.headers_mut().insert("x-gateway-request-id", id);
    }
+    response
 }

 /// 从 socket 与标准转发头提取旧 Usage 页面使用的诊断事实。
-pub(super) fn request_client_context(
+pub(in crate::openai) fn request_client_context(
    headers: &HeaderMap,
    peer_address: Option<SocketAddr>,
 ) -> (Option<IpAddr>, Option<String>) {
@@ -180,7 +167,8 @@ pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> R
    let events = match session.collect_uncommitted().await {
        Ok(events) => events,
        Err(error) => {
-            let response = engine_error_response(&error);
+            let response_headers = session.response_headers().to_vec();
+            let response = engine_error_response_with_headers(&error, &response_headers);
            return execution.record_response_status(response).await;
        }
    };
@@ -196,6 +184,11 @@ pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> R
        }
    };
    let response_headers = session.response_headers().to_vec();
+    session.trace().record(
+        "downstream.encoded",
+        serde_json::json!({"transport": "http_json", "bytes": encoded.len()}),
+    );
+    session.trace().dump("downstream.body", &encoded);
    let response = json_body_response(encoded, &response_headers);

    let Some(session) = execution.session_mut() else {
@@ -206,7 +199,7 @@ pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> R
        .await
    {
        execution.cancel_and_finalize().await;
-        let response = engine_error_response(&error);
+        let response = engine_error_response_with_headers(&error, &response_headers);
        return execution.record_response_status(response).await;
    }
    if !session.is_finalized() {
@@ -274,6 +267,13 @@ fn apply_response_headers(
    response
 }

+fn engine_error_response_with_headers(
+    error: &EngineError,
+    response_headers: &[ProviderResponseHeader],
+) -> Response {
+    apply_response_headers(engine_error_response(error), response_headers)
+}
+
 /// 编码首个 SSE frame 后提交下游，再持续驱动同一执行会话。
 pub async fn stream_execution_response(
    session: Box<dyn ExecutionSession>,
@@ -295,7 +295,8 @@ pub async fn stream_execution_response(
            return response;
        }
        Err(error) => {
-            let response = engine_error_response(&error);
+            let response_headers = session.response_headers().to_vec();
+            let response = engine_error_response_with_headers(&error, &response_headers);
            return execution.record_response_status(response).await;
        }
    };
@@ -327,7 +328,7 @@ pub async fn stream_execution_response(
        .await
    {
        execution.cancel_and_finalize().await;
-        let response = engine_error_response(&error);
+        let response = engine_error_response_with_headers(&error, &response_headers);
        return execution.record_response_status(response).await;
    }
    let Some(session) = execution.into_session() else {
@@ -337,9 +338,11 @@ pub async fn stream_execution_response(
    if state.encoder.is_completed() {
        state.finish_completed(Vec::new()).await;
    }
-    let body = Body::from_stream(stream::unfold(state, |mut state| async move {
+    let output = Box::pin(stream::unfold(state, |mut state| async move {
        loop {
            if let Some(chunk) = state.pending.pop_front() {
+                state.trace.dump("downstream.chunk", &chunk);
+                state.handed_off_bytes += chunk.len() as u64;
                return Some((Ok::<Bytes, Infallible>(chunk), state));
            }
            if state.output_finished {
@@ -348,41 +351,59 @@ pub async fn stream_execution_response(
            state.advance().await;
        }
    }));
+    // 保活只轮询已固定的输出 stream；不能取消并重建 advance/next_event future，
+    // 否则一次心跳就可能丢失正在等待的上游事件或执行终态清理。
+    let body = Body::from_stream(stream::unfold(output, |mut output| async move {
+        let chunk = tokio::select! {
+            biased;
+            chunk = output.next() => chunk?,
+            () = tokio::time::sleep(SSE_KEEPALIVE_INTERVAL) => {
+                Ok(Bytes::from_static(b": keep-alive\n\n"))
+            }
+        };
+        Some((chunk, output))
+    }));
    event_stream_response(body, &response_headers)
 }

 fn event_stream_response(body: Body, response_headers: &[ProviderResponseHeader]) -> Response {
-    let mut response = Response::new(body);
+    let mut response = apply_response_headers(Response::new(body), response_headers);
    *response.status_mut() = StatusCode::OK;
    response
        .headers_mut()
        .insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
+    response.headers_mut().insert(
+        CACHE_CONTROL,
+        HeaderValue::from_static("no-cache, no-transform"),
+    );
    response
        .headers_mut()
-        .insert(CACHE_CONTROL, HeaderValue::from_static("no-cache"));
-    apply_response_headers(response, response_headers)
+        .insert("x-accel-buffering", HeaderValue::from_static("no"));
+    response
 }

 fn internal_gateway_response(message: &'static str) -> Response {
    gateway_error_response(&GatewayError::new(GatewayErrorKind::Internal, message))
 }

-pub(super) struct PendingExecution {
+pub(in crate::openai) struct PendingExecution {
    session: Option<Box<dyn ExecutionSession>>,
 }

 impl PendingExecution {
-    pub(super) fn new(session: Box<dyn ExecutionSession>) -> Self {
+    pub(in crate::openai) fn new(session: Box<dyn ExecutionSession>) -> Self {
        Self {
            session: Some(session),
        }
    }

-    pub(super) fn session_mut(&mut self) -> Option<&mut (dyn ExecutionSession + 'static)> {
+    pub(in crate::openai) fn session_mut(
+        &mut self,
+    ) -> Option<&mut (dyn ExecutionSession + 'static)> {
        self.session.as_deref_mut()
    }

-    async fn cancel_and_finalize(&mut self) {
+    pub(in crate::openai) async fn cancel_and_finalize(&mut self) {
        if let Some(session) = self.session.as_mut() {
            session.cancel();
            if !session.is_finalized() {
@@ -391,7 +412,10 @@ impl PendingExecution {
        }
    }

-    async fn record_response_status(&mut self, response: Response) -> Response {
+    pub(in crate::openai) async fn record_response_status(
+        &mut self,
+        response: Response,
+    ) -> Response {
        if let Some(session) = self.session.as_mut() {
            let _ = session
                .record_client_status(response.status().as_u16())
@@ -400,7 +424,7 @@ impl PendingExecution {
        response
    }

-    pub(super) fn disarm(&mut self) {
+    pub(in crate::openai) fn disarm(&mut self) {
        self.session = None;
    }

@@ -417,12 +441,18 @@ impl Drop for PendingExecution {
        if session.is_finalized() {
            return;
        }
+        session.trace().record(
+            "downstream.cancelled",
+            serde_json::json!({"reason": "response_guard_dropped"}),
+        );
        session.cancel();
        detach_finalize(session);
    }
 }

 struct ResponsesStreamState {
+    trace: TraceContext,
+    handed_off_bytes: u64,
    session: Option<Box<dyn ExecutionSession>>,
    encoder: OpenAiResponsesEncoder,
    pending: VecDeque<Bytes>,
@@ -439,6 +469,8 @@ impl ResponsesStreamState {
        connection_guard: Option<Box<dyn ConnectionGuard>>,
    ) -> Self {
        Self {
+            trace: session.trace(),
+            handed_off_bytes: 0,
            session: Some(session),
            encoder,
            pending: initial_frames.into_iter().collect(),
@@ -594,6 +626,11 @@ impl ResponsesStreamState {

 impl Drop for ResponsesStreamState {
    fn drop(&mut self) {
+        self.trace.record("downstream.body.closed", serde_json::json!({
+            "handedOffBytes": self.handed_off_bytes,
+            "pendingChunks": self.pending.len(),
+            "outputFinished": self.output_finished, "executionTerminal": self.execution_terminal,
+        }));
        if self.execution_terminal {
            return;
        }
@@ -4,11 +4,12 @@ mod error;
 mod http;
 mod request;
 mod response;
-mod websocket;
+pub mod websocket;

-pub use error::{ProtocolErrorBody, RequestDecodeError, ResponseEncodeError};
+pub use error::{ProtocolError, ProtocolErrorBody, RequestDecodeError, ResponseEncodeError};
+pub(crate) use http::responses;
+pub(super) use http::{PendingExecution, request_client_context};
 pub use http::{collect_execution_response, stream_execution_response};
-pub(crate) use http::{responses, review_responses};
 pub use request::{
    ContinuationIntent, DecodedResponsesRequest, OpenAiRequestHeaders, ResponsesRequestMetadata,
    decode_request_with_headers,
@@ -73,7 +74,6 @@ pub(super) fn response_header_is_forwardable(name: &str, connection_options: &[S
            | "x-openai-organization"
            | "x-openai-project"
            | "x-codex-installation-id"
-            | "x-codex-turn-state"
            | "x-codex-turn-metadata"
    )
 }
@@ -13,9 +13,19 @@ use serde_json::{Map, Value};
 use super::error::RequestDecodeError;

 const OPENAI_PROTOCOL: &str = "openai";
-const REVIEW_SUBAGENT: &str = "review";
 const OPENAI_SUBAGENT_KEY: &str = "x-openai-subagent";
+const CODEX_TURN_METADATA_KEY: &str = "x-codex-turn-metadata";
 const PASSTHROUGH_HEADERS_CONTEXT_KEY: &str = "opaque_request_headers";
+const DOWNSTREAM_WEBSOCKET_CONNECTION_ID_CONTEXT_KEY: &str = "downstream_websocket_connection_id";
+
+/// Responses 请求进入共享解码内核时的下游传输来源。
+#[derive(Clone, Copy)]
+pub(super) enum RequestDecodeSource {
+    /// 单次 HTTP 请求，请求头与正文属于同一请求。
+    Http,
+    /// 复用连接上的 WebSocket `response.create` 帧。
+    WebSocketFrame,
+}

 #[derive(Clone, Default)]
 pub struct OpenAiRequestHeaders {
@@ -26,6 +36,7 @@ pub struct OpenAiRequestHeaders {
    include_timing_metrics: Option<String>,
    codex_window_id: Option<String>,
    parent_thread_id: Option<String>,
+    downstream_websocket_connection_id: Option<String>,

    conversation_id: Option<String>,
    session_id: Option<String>,
@@ -51,6 +62,7 @@ impl OpenAiRequestHeaders {
            include_timing_metrics: header_string(headers, "x-responsesapi-include-timing-metrics"),
            codex_window_id: header_string(headers, "x-codex-window-id"),
            parent_thread_id: header_string(headers, "x-codex-parent-thread-id"),
+            downstream_websocket_connection_id: None,
            conversation_id: header_string(headers, "conversation-id")
                .or_else(|| header_string(headers, "conversation_id")),
            session_id: header_string(headers, "session-id")
@@ -65,16 +77,43 @@ impl OpenAiRequestHeaders {
        }
    }

-    fn apply_subagent(&self, body: &mut Map<String, Value>, forced_subagent: Option<&str>) {
-        if let Some(subagent) = forced_subagent.or(self.subagent.as_deref()) {
+    /// 绑定代理为当前下游 WebSocket 分配的连接身份。
+    #[must_use]
+    pub(super) fn with_downstream_websocket_connection_id(
+        mut self,
+        connection_id: impl Into<String>,
+    ) -> Self {
+        self.downstream_websocket_connection_id = Some(connection_id.into());
+        self
+    }
+
+    fn apply_subagent(&self, body: &mut Map<String, Value>) {
+        if let Some(subagent) = self.subagent.as_deref() {
            inject_subagent_metadata(body, subagent);
        }
    }

-    fn protocol_context(&self, use_websocket: Option<bool>) -> Map<String, Value> {
+    /// 独立端点只消费会话身份与 turn metadata，不携带 Responses 的连接状态。
+    pub(crate) fn session_context(&self) -> Map<String, Value> {
+        let mut context = Map::new();
+        insert_protocol_context(&mut context, "session_id", self.session_id.as_ref());
+        insert_protocol_context(&mut context, "thread_id", self.thread_id.as_ref());
+        insert_protocol_context(&mut context, "turn_metadata", self.turn_metadata.as_ref());
+        context
+    }
+
+    fn protocol_context(
+        &self,
+        use_websocket: Option<bool>,
+        frame_turn_metadata: Option<&String>,
+    ) -> Map<String, Value> {
        let mut context = Map::new();
        insert_protocol_context(&mut context, "turn_state", self.turn_state.as_ref());
-        insert_protocol_context(&mut context, "turn_metadata", self.turn_metadata.as_ref());
+        insert_protocol_context(
+            &mut context,
+            "turn_metadata",
+            frame_turn_metadata.or(self.turn_metadata.as_ref()),
+        );
        insert_protocol_context(&mut context, "beta_features", self.beta_features.as_ref());
        insert_protocol_context(&mut context, "version", self.version.as_ref());
        insert_protocol_context(
@@ -92,6 +131,11 @@ impl OpenAiRequestHeaders {
            "parent_thread_id",
            self.parent_thread_id.as_ref(),
        );
+        insert_protocol_context(
+            &mut context,
+            DOWNSTREAM_WEBSOCKET_CONNECTION_ID_CONTEXT_KEY,
+            self.downstream_websocket_connection_id.as_ref(),
+        );
        insert_protocol_context(
            &mut context,
            "conversation_id",
@@ -136,12 +180,6 @@ pub enum ContinuationIntent {
 }

 impl ContinuationIntent {
-    /// 返回是否请求了对话延续。
-    #[must_use]
-    pub const fn is_continuation(&self) -> bool {
-        matches!(self, Self::PreviousResponseId(_))
-    }
-
    /// 返回待 history owner 解析的 response ID。
    #[must_use]
    pub fn previous_response_id(&self) -> Option<&str> {
@@ -165,7 +203,6 @@ impl fmt::Debug for ContinuationIntent {
 #[derive(Clone, PartialEq, Eq)]
 pub struct ResponsesRequestMetadata {
    requested_model: String,
-    public_model: String,
    stream: bool,
    store: bool,
    continuation: ContinuationIntent,
@@ -180,12 +217,6 @@ impl ResponsesRequestMetadata {
        &self.requested_model
    }

-    /// 返回协议层公开模型候选。
-    #[must_use]
-    pub fn public_model(&self) -> &str {
-        &self.public_model
-    }
-
    /// 返回客户端是否请求 SSE。
    #[must_use]
    pub const fn stream(&self) -> bool {
@@ -222,7 +253,6 @@ impl fmt::Debug for ResponsesRequestMetadata {
        formatter
            .debug_struct("ResponsesRequestMetadata")
            .field("requested_model", &self.requested_model)
-            .field("public_model", &self.public_model)
            .field("stream", &self.stream)
            .field("store", &self.store)
            .field("continuation", &self.continuation)
@@ -297,20 +327,11 @@ pub fn decode_request_with_headers(
    body: &[u8],
    headers: &HeaderMap,
 ) -> Result<DecodedResponsesRequest, RequestDecodeError> {
-    decode_request_inner(body, false, &OpenAiRequestHeaders::from_headers(headers))
-}
-
-/// 解码 `POST /v1/responses/review` 请求并冻结 review subagent 语义。
-pub(super) fn decode_review_request_with_headers(
-    body: &[u8],
-    headers: &HeaderMap,
-) -> Result<DecodedResponsesRequest, RequestDecodeError> {
-    decode_request_inner(body, true, &OpenAiRequestHeaders::from_headers(headers))
+    decode_request_inner(body, &OpenAiRequestHeaders::from_headers(headers))
 }

 pub(super) fn decode_request_inner(
    body: &[u8],
-    review: bool,
    request_headers: &OpenAiRequestHeaders,
 ) -> Result<DecodedResponsesRequest, RequestDecodeError> {
    let value =
@@ -318,14 +339,14 @@ pub(super) fn decode_request_inner(
    let Value::Object(object) = value else {
        return Err(RequestDecodeError::ExpectedObject);
    };
-    decode_request_object(object, review, request_headers)
+    decode_request_object(object, request_headers, RequestDecodeSource::Http)
 }

-/// 解码已解析的顶层 object；WebSocket 帧解码复用此内核，避免序列化往返。
+/// 解码已解析的顶层 object；按下游传输来源恢复连接级协议上下文。
 pub(super) fn decode_request_object(
    mut object: Map<String, Value>,
-    review: bool,
    request_headers: &OpenAiRequestHeaders,
+    source: RequestDecodeSource,
 ) -> Result<DecodedResponsesRequest, RequestDecodeError> {
    // 仅消费已识别的本地 transport 开关；未知同名值保留给未来上游协议。
    let use_websocket = object.get("use_websocket").and_then(Value::as_bool);
@@ -354,8 +375,12 @@ pub(super) fn decode_request_object(
        .map(|response_id| ContinuationIntent::PreviousResponseId(response_id.to_owned()))
        .unwrap_or(ContinuationIntent::None);

-    request_headers.apply_subagent(&mut object, review.then_some(REVIEW_SUBAGENT));
-    let protocol_context = request_headers.protocol_context(use_websocket);
+    request_headers.apply_subagent(&mut object);
+    let frame_turn_metadata = match source {
+        RequestDecodeSource::Http => None,
+        RequestDecodeSource::WebSocketFrame => frame_turn_metadata(&object),
+    };
+    let protocol_context = request_headers.protocol_context(use_websocket, frame_turn_metadata);

    let payload = ProtocolPayload::json_object(OPENAI_PROTOCOL, object)
        .map_err(|_| RequestDecodeError::CanonicalContract {
@@ -366,8 +391,7 @@ pub(super) fn decode_request_object(
    Ok(DecodedResponsesRequest {
        operation,
        metadata: ResponsesRequestMetadata {
-            requested_model: model.clone(),
-            public_model: model,
+            requested_model: model,
            stream,
            store,
            continuation,
@@ -377,6 +401,16 @@ pub(super) fn decode_request_object(
    })
 }

+fn frame_turn_metadata(body: &Map<String, Value>) -> Option<&String> {
+    body.get("client_metadata")
+        .and_then(Value::as_object)
+        .and_then(|metadata| metadata.get(CODEX_TURN_METADATA_KEY))
+        .and_then(|value| match value {
+            Value::String(value) if !value.trim().is_empty() => Some(value),
+            _ => None,
+        })
+}
+
 fn inject_subagent_metadata(body: &mut Map<String, Value>, subagent: &str) {
    let metadata = body
        .entry("client_metadata".to_owned())
@@ -458,6 +492,8 @@ fn passthrough_header_name(name: &str, connection_headers: &[String]) -> bool {
            // 下游鉴权和账号 cookie 绝不能成为上游账号身份。
            | "authorization"
            | "x-api-key"
+            // Codex 的服务端托管认证标记只用于客户端能力判断，不代表上游身份。
+            | "x-openai-actor-authorization"
            | "cookie"
            | "cookie2"
            | "chatgpt-account-id"
@@ -470,10 +506,11 @@ fn passthrough_header_name(name: &str, connection_headers: &[String]) -> bool {
            | "x-openai-project"
            // installation ID 始终由当前 lease 重建。
            | "x-codex-installation-id"
-            // 上游指纹必须由运行时画像统一生成，客户端 originator/User-Agent
-            // 不能透传覆盖，避免不同下游客户端暴露不一致的设备指纹。
+            // 上游指纹必须由运行时画像统一生成，客户端 originator/User-Agent/version
+            // 不能作为不透明头透传覆盖，避免不同下游客户端暴露不一致的设备指纹。
            | "originator"
            | "user-agent"
+            | "version"
            // 设备 attestation/integrity 头只能由官方客户端或网关自身生成，
            // 客户端注入的 x-oai-attestation / X-OAI-IS 不得透传上游。
            | "x-oai-attestation"
@@ -1,699 +0,0 @@
-//! OpenAI Responses WebSocket adapter。
-
-use std::net::{IpAddr, SocketAddr};
-use std::sync::Arc;
-
-use axum::{
-    extract::{
-        Extension, State,
-        connect_info::ConnectInfo,
-        ws::{CloseFrame, Message, WebSocket, WebSocketUpgrade, close_code},
-    },
-    http::{HeaderMap, HeaderName, StatusCode},
-    response::{IntoResponse, Response},
-};
-use futures::StreamExt;
-use gateway_core::engine::execution::{AuthenticatedClient, ClientTransport, StartedExecution};
-use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError};
-use gateway_core::error::{GatewayError, GatewayErrorKind};
-use gateway_core::event::ProviderResponseHeader;
-use gateway_core::lifecycle::{ConnectionGuard, ConnectionLifecycle};
-use gateway_core::operation::ProviderSessionState;
-use serde_json::{Map, Value, json};
-use thiserror::Error;
-
-use crate::{
-    ApiState,
-    openai::{
-        auth::{authenticate_client, authentication_error_response},
-        error::{gateway_error_contract, gateway_error_from_engine, runtime_unavailable_response},
-        service::OpenAiService,
-    },
-};
-
-use super::{
-    DecodedResponsesRequest, OpenAiResponsesEncoder, ProtocolErrorBody, RequestDecodeError,
-    http::{PendingExecution, request_client_context},
-    request::OpenAiRequestHeaders,
-};
-
-const ACTIVE_RESPONSE_VIOLATION: &str = "Only one response.create may be active per connection";
-const TEXT_FRAMES_ONLY: &str = "Responses WebSocket accepts text frames only";
-
-/// 将已认证的 `GET /v1/responses` 升级为 Responses WebSocket。
-pub(crate) async fn responses_websocket(
-    State(state): State<ApiState>,
-    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
-    headers: HeaderMap,
-    websocket: WebSocketUpgrade,
-) -> Response {
-    let service = state.openai().clone();
-    let client = match authenticate_client(&service, &headers) {
-        Ok(client) => client,
-        Err(error) => return authentication_error_response(error),
-    };
-    let (client_ip, user_agent) = request_client_context(
-        &headers,
-        connect_info.map(|Extension(ConnectInfo(address))| address),
-    );
-    ResponsesWebSocketAdapter::new(service).upgrade_with_client_context(
-        websocket,
-        client,
-        client_ip,
-        user_agent,
-        OpenAiRequestHeaders::from_headers(&headers),
-    )
-}
-
-/// 已鉴权 Responses WebSocket 升级边界。
-#[derive(Clone)]
-pub(crate) struct ResponsesWebSocketAdapter {
-    service: OpenAiService,
-}
-
-impl ResponsesWebSocketAdapter {
-    /// 绑定应用提供的唯一 OpenAI 客户端服务端口。
-    #[must_use]
-    pub const fn new(service: OpenAiService) -> Self {
-        Self { service }
-    }
-
-    fn upgrade_with_client_context(
-        &self,
-        websocket: WebSocketUpgrade,
-        client: AuthenticatedClient,
-        client_ip: Option<IpAddr>,
-        user_agent: Option<String>,
-        request_headers: OpenAiRequestHeaders,
-    ) -> Response {
-        let connection_guard = match self.service.try_register_connection() {
-            Ok(guard) => guard,
-            Err(_) => return runtime_unavailable_response().into_response(),
-        };
-        let session = ResponsesWebSocketSession {
-            service: self.service.clone(),
-            client,
-            connection_id: self.service.next_request_id().replacen("req_", "ws_", 1),
-            client_ip,
-            user_agent,
-            request_headers,
-            lifecycle: self.service.lifecycle(),
-            _connection_guard: connection_guard,
-        };
-        websocket
-            // 覆盖 axum/tungstenite 的私有 64 MiB message 与 16 MiB frame 默认值。
-            // Responses JSON 的协议可接受性由上游决定，代理不另设 wire 长度上限。
-            .max_message_size(usize::MAX)
-            .max_frame_size(usize::MAX)
-            .on_upgrade(move |socket| async move {
-                serve_responses_websocket(socket, session).await;
-            })
-    }
-}
-
-struct ResponsesWebSocketSession {
-    service: OpenAiService,
-    client: AuthenticatedClient,
-    connection_id: String,
-    client_ip: Option<IpAddr>,
-    user_agent: Option<String>,
-    request_headers: OpenAiRequestHeaders,
-    lifecycle: Arc<dyn ConnectionLifecycle>,
-    _connection_guard: Box<dyn ConnectionGuard>,
-}
-
-async fn serve_responses_websocket(mut socket: WebSocket, session: ResponsesWebSocketSession) {
-    tracing::info!(
-        websocket_connection_id = %session.connection_id,
-        "Responses WebSocket connected"
-    );
-    let mut request_count = 0_u64;
-    let mut replay = ConnectionReplaySnapshot::default();
-
-    let cancellation = session.lifecycle.cancellation();
-    loop {
-        let message = tokio::select! {
-            () = cancellation.cancelled() => break,
-            message = socket.next() => message,
-        };
-        let Some(message) = message else {
-            break;
-        };
-        let payload = match message {
-            Ok(Message::Text(payload)) => payload,
-            Ok(Message::Ping(_) | Message::Pong(_)) => continue,
-            Ok(Message::Close(_)) => break,
-            Ok(Message::Binary(_)) => {
-                close_for_protocol_violation(&mut socket, TEXT_FRAMES_ONLY).await;
-                break;
-            }
-            Err(error) => {
-                tracing::info!(
-                    websocket_connection_id = %session.connection_id,
-                    error = %error,
-                    "Responses WebSocket receive failed"
-                );
-                break;
-            }
-        };
-        request_count = request_count.saturating_add(1);
-        let correlation_id = session.service.next_request_id();
-        let decoded =
-            match decode_response_create_with_context(payload.as_str(), &session.request_headers) {
-                Ok(decoded) => {
-                    decoded.with_client_context(session.client_ip, session.user_agent.clone())
-                }
-                Err(error) => {
-                    tracing::info!(
-                        websocket_connection_id = %session.connection_id,
-                        request_id = %correlation_id,
-                        error = %error,
-                        "Responses WebSocket request rejected"
-                    );
-                    if send_protocol_error(
-                        &mut socket,
-                        StatusCode::BAD_REQUEST,
-                        error.protocol_body(),
-                        &correlation_id,
-                    )
-                    .await
-                        == ForwardOutcome::Disconnect
-                    {
-                        break;
-                    }
-                    continue;
-                }
-            };
-        let decoded = replay.prepare(decoded);
-        let started = match session
-            .service
-            .start_response(
-                session.client.clone(),
-                decoded,
-                ClientTransport::WebSocket,
-                "/v1/responses",
-            )
-            .await
-        {
-            Ok(started) => started,
-            Err(error) => {
-                if send_gateway_error(&mut socket, &error, &correlation_id).await
-                    == ForwardOutcome::Disconnect
-                {
-                    break;
-                }
-                continue;
-            }
-        };
-
-        if forward_execution(&mut socket, started, &mut replay).await == ForwardOutcome::Disconnect
-        {
-            break;
-        }
-    }
-
-    tracing::info!(
-        websocket_connection_id = %session.connection_id,
-        request_count,
-        "Responses WebSocket disconnected"
-    );
-}
-
-#[derive(Clone, Copy, PartialEq, Eq)]
-enum ForwardOutcome {
-    Continue,
-    Disconnect,
-}
-
-#[derive(Default)]
-struct ConnectionReplaySnapshot {
-    last_response_id: Option<String>,
-    provider_state: Option<ProviderSessionState>,
-}
-
-impl ConnectionReplaySnapshot {
-    fn prepare(&self, request: DecodedResponsesRequest) -> DecodedResponsesRequest {
-        match (
-            request.metadata().continuation().previous_response_id(),
-            self.last_response_id.as_deref(),
-            self.provider_state.as_ref(),
-        ) {
-            (Some(previous), Some(last), Some(state)) if previous == last => {
-                request.with_provider_session_state(state.clone())
-            }
-            _ => request,
-        }
-    }
-
-    fn commit(&mut self, response_id: String, provider_state: Option<ProviderSessionState>) {
-        self.last_response_id = Some(response_id);
-        self.provider_state = provider_state;
-    }
-}
-
-async fn forward_execution(
-    socket: &mut WebSocket,
-    started: StartedExecution,
-    replay: &mut ConnectionReplaySnapshot,
-) -> ForwardOutcome {
-    let request_id = started.request_id.to_string();
-    let streaming = started.stream;
-    let mut execution = PendingExecution::new(started.session);
-    if !streaming {
-        let error = GatewayError::new(
-            GatewayErrorKind::Internal,
-            "WebSocket execution was not initialized as a stream",
-        );
-        return send_gateway_error(socket, &error, &request_id).await;
-    }
-    let first = loop {
-        match next_active_input(socket, &mut execution).await {
-            ActiveInput::Event(Ok(Some(event))) => break event,
-            ActiveInput::Event(Ok(None)) => {
-                let error = GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response ended before its first event",
-                );
-                return send_gateway_error(socket, &error, &request_id).await;
-            }
-            ActiveInput::Event(Err(error)) => {
-                let error = gateway_error_from_engine(&error);
-                return send_gateway_error(socket, &error, &request_id).await;
-            }
-            ActiveInput::Control => continue,
-            ActiveInput::Disconnect => return ForwardOutcome::Disconnect,
-            ActiveInput::ProtocolViolation => {
-                close_for_protocol_violation(socket, ACTIVE_RESPONSE_VIOLATION).await;
-                return ForwardOutcome::Disconnect;
-            }
-        }
-    };
-    let requirement = first.commit_requirement();
-    let mut first = first.into_provider_events();
-    if requirement != CommitRequirement::CommitBeforeDelivery {
-        let error = GatewayError::new(
-            GatewayErrorKind::Internal,
-            "gateway first event did not require commit",
-        );
-        return send_gateway_error(socket, &error, &request_id).await;
-    }
-    let mut encoder = OpenAiResponsesEncoder::new();
-    let mut provider_state = None;
-    let mut first_messages = Vec::new();
-    for event in &mut first {
-        if let Some(update) = event.take_session_update() {
-            provider_state = Some(update);
-        }
-        first_messages.extend(encoder.push_websocket(event));
-    }
-    if first_messages.is_empty() {
-        let error = GatewayError::new(
-            GatewayErrorKind::Internal,
-            "gateway commit batch encoded no output",
-        );
-        return send_gateway_error(socket, &error, &request_id).await;
-    }
-    let Some(response_session) = execution.session_mut() else {
-        return ForwardOutcome::Disconnect;
-    };
-    let response_headers = response_session.response_headers().to_vec();
-    if let Err(error) = response_session.commit_downstream(None).await {
-        let error = gateway_error_from_engine(&error);
-        return send_gateway_error(socket, &error, &request_id).await;
-    }
-    if encoder.is_completed() {
-        if let Err(outcome) = confirm_completed_execution(socket, &mut execution, &request_id).await
-        {
-            return outcome;
-        }
-        commit_connection_replay(replay, &encoder, provider_state.take());
-        if !send_text(
-            socket,
-            response_metadata_event(&request_id, &response_headers),
-        )
-        .await
-            || !send_messages(socket, first_messages).await
-        {
-            return ForwardOutcome::Disconnect;
-        }
-        execution.disarm();
-        return ForwardOutcome::Continue;
-    }
-    if !send_text(
-        socket,
-        response_metadata_event(&request_id, &response_headers),
-    )
-    .await
-        || !send_messages(socket, first_messages).await
-    {
-        return ForwardOutcome::Disconnect;
-    }
-
-    loop {
-        match next_active_input(socket, &mut execution).await {
-            ActiveInput::Event(Ok(Some(delivery))) => {
-                let requirement = delivery.commit_requirement();
-                let mut events = delivery.into_provider_events();
-                if requirement != CommitRequirement::AlreadyCommitted {
-                    let error = GatewayError::new(
-                        GatewayErrorKind::Internal,
-                        "gateway requested another downstream commit",
-                    );
-                    return send_gateway_error(socket, &error, &request_id).await;
-                }
-                let mut messages = Vec::new();
-                for event in &mut events {
-                    if let Some(update) = event.take_session_update() {
-                        provider_state = Some(update);
-                    }
-                    messages.extend(encoder.push_websocket(event));
-                }
-                if encoder.is_completed() {
-                    if let Err(outcome) =
-                        confirm_completed_execution(socket, &mut execution, &request_id).await
-                    {
-                        return outcome;
-                    }
-                    commit_connection_replay(replay, &encoder, provider_state.take());
-                    if !send_messages(socket, messages).await {
-                        return ForwardOutcome::Disconnect;
-                    }
-                    execution.disarm();
-                    return ForwardOutcome::Continue;
-                }
-                if !send_messages(socket, messages).await {
-                    return ForwardOutcome::Disconnect;
-                }
-            }
-            ActiveInput::Event(Ok(None)) => {
-                if execution
-                    .session_mut()
-                    .is_some_and(|session| session.is_finalized())
-                {
-                    commit_connection_replay(replay, &encoder, provider_state.take());
-                    execution.disarm();
-                    return ForwardOutcome::Continue;
-                }
-                let error = GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response ended without finalizing the execution",
-                );
-                return send_gateway_error(socket, &error, &request_id).await;
-            }
-            ActiveInput::Event(Err(error)) => {
-                if encoder.has_wire_failure() {
-                    execution.disarm();
-                    return ForwardOutcome::Continue;
-                }
-                let error = gateway_error_from_engine(&error);
-                return send_gateway_error(socket, &error, &request_id).await;
-            }
-            ActiveInput::Control => {}
-            ActiveInput::Disconnect => return ForwardOutcome::Disconnect,
-            ActiveInput::ProtocolViolation => {
-                close_for_protocol_violation(socket, ACTIVE_RESPONSE_VIOLATION).await;
-                return ForwardOutcome::Disconnect;
-            }
-        }
-    }
-}
-
-fn commit_connection_replay(
-    replay: &mut ConnectionReplaySnapshot,
-    encoder: &OpenAiResponsesEncoder,
-    provider_state: Option<ProviderSessionState>,
-) {
-    if let Some(response_id) = encoder.response_id() {
-        replay.commit(response_id.to_owned(), provider_state);
-    }
-}
-
-async fn confirm_completed_execution(
-    socket: &mut WebSocket,
-    execution: &mut PendingExecution,
-    request_id: &str,
-) -> Result<(), ForwardOutcome> {
-    loop {
-        match next_active_input(socket, execution).await {
-            ActiveInput::Event(Ok(None))
-                if execution
-                    .session_mut()
-                    .is_some_and(|session| session.is_finalized()) =>
-            {
-                return Ok(());
-            }
-            ActiveInput::Event(Ok(None)) => {
-                let error = GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response was not finalized after its terminal event",
-                );
-                return Err(send_gateway_error(socket, &error, request_id).await);
-            }
-            ActiveInput::Event(Ok(Some(_))) => {
-                let error = GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response continued after its terminal event",
-                );
-                return Err(send_gateway_error(socket, &error, request_id).await);
-            }
-            ActiveInput::Event(Err(error)) => {
-                let error = gateway_error_from_engine(&error);
-                return Err(send_gateway_error(socket, &error, request_id).await);
-            }
-            ActiveInput::Control => {}
-            ActiveInput::Disconnect => return Err(ForwardOutcome::Disconnect),
-            ActiveInput::ProtocolViolation => {
-                close_for_protocol_violation(socket, ACTIVE_RESPONSE_VIOLATION).await;
-                return Err(ForwardOutcome::Disconnect);
-            }
-        }
-    }
-}
-
-enum ActiveInput {
-    Event(Result<Option<CoordinatedEvent>, EngineError>),
-    Control,
-    Disconnect,
-    ProtocolViolation,
-}
-
-async fn next_active_input(
-    socket: &mut WebSocket,
-    execution: &mut PendingExecution,
-) -> ActiveInput {
-    let Some(session) = execution.session_mut() else {
-        return ActiveInput::Disconnect;
-    };
-    tokio::select! {
-        event = session.next_event() => ActiveInput::Event(event),
-        message = socket.next() => match message {
-            Some(Ok(Message::Ping(_) | Message::Pong(_))) => ActiveInput::Control,
-            Some(Ok(Message::Close(_))) | None | Some(Err(_)) => ActiveInput::Disconnect,
-            Some(Ok(Message::Text(_) | Message::Binary(_))) => ActiveInput::ProtocolViolation,
-        },
-    }
-}
-
-/// 使用连接级请求头和 Provider 上下文解码官方 `response.create` 文本帧。
-///
-/// 缺省 `stream` 等价于 WebSocket 固有的流式语义；显式 `false` 会被拒绝。
-///
-/// # Errors
-///
-/// 帧不是合法 JSON object、消息类型错误、显式关闭 stream，或 Responses 请求
-/// 无法映射到 canonical operation 时返回不包含正文内容的稳定错误。
-pub fn decode_response_create_with_context(
-    payload: &str,
-    request_headers: &OpenAiRequestHeaders,
-) -> Result<DecodedResponsesRequest, ResponseCreateFrameError> {
-    decode_response_create_inner(payload, request_headers)
-}
-
-fn decode_response_create_inner(
-    payload: &str,
-    request_headers: &OpenAiRequestHeaders,
-) -> Result<DecodedResponsesRequest, ResponseCreateFrameError> {
-    let Value::Object(mut body) = serde_json::from_str::<Value>(payload)
-        .map_err(|_| ResponseCreateFrameError::InvalidJson)?
-    else {
-        return Err(ResponseCreateFrameError::ExpectedObject);
-    };
-    match body.remove("type") {
-        Some(Value::String(message_type)) if message_type == "response.create" => {}
-        _ => return Err(ResponseCreateFrameError::UnsupportedType),
-    }
-    if matches!(body.get("stream"), Some(value) if value.as_bool() != Some(true)) {
-        return Err(ResponseCreateFrameError::StreamingRequired);
-    }
-    super::request::decode_request_object(body, false, request_headers)
-        .map_err(ResponseCreateFrameError::Request)
-}
-
-/// `response.create` 帧的稳定安全错误。
-#[derive(Debug, Clone, PartialEq, Eq, Error)]
-pub enum ResponseCreateFrameError {
-    /// 文本不是合法 JSON。
-    #[error("response.create frame must be valid JSON")]
-    InvalidJson,
-    /// 顶层不是 object。
-    #[error("response.create frame must be a JSON object")]
-    ExpectedObject,
-    /// `type` 缺失或不是 `response.create`。
-    #[error("unsupported Responses WebSocket message type")]
-    UnsupportedType,
-    /// WebSocket 请求显式声明 `stream=false`。
-    #[error("Responses WebSocket requests require stream=true")]
-    StreamingRequired,
-    /// 内层 Responses 请求无法映射到 canonical operation。
-    #[error(transparent)]
-    Request(RequestDecodeError),
-}
-
-impl ResponseCreateFrameError {
-    fn protocol_body(&self) -> ProtocolErrorBody {
-        match self {
-            Self::Request(error) => error.protocol_body(),
-            Self::InvalidJson => RequestDecodeError::MalformedJson.protocol_body(),
-            Self::ExpectedObject => RequestDecodeError::ExpectedObject.protocol_body(),
-            Self::UnsupportedType => RequestDecodeError::InvalidValue {
-                field: "type".to_owned(),
-            }
-            .protocol_body(),
-            Self::StreamingRequired => RequestDecodeError::InvalidValue {
-                field: "stream".to_owned(),
-            }
-            .protocol_body(),
-        }
-    }
-}
-
-fn response_metadata_event(
-    request_id: &str,
-    response_headers: &[ProviderResponseHeader],
-) -> String {
-    let connection_options = super::response_connection_options(response_headers);
-    let mut headers = Map::new();
-    for header in response_headers {
-        if !super::response_header_is_forwardable(header.name(), &connection_options) {
-            continue;
-        }
-        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
-            continue;
-        };
-        let Ok(value) = std::str::from_utf8(header.value()) else {
-            continue;
-        };
-        // 官方 response.metadata 使用 string map，无法表达同名多值；后值保持既有覆盖语义。
-        headers.insert(name.as_str().to_owned(), Value::String(value.to_owned()));
-    }
-    headers
-        .entry("x-request-id".to_owned())
-        .or_insert_with(|| Value::String(request_id.to_owned()));
-    json!({
-        "type": "response.metadata",
-        "headers": headers,
-    })
-    .to_string()
-}
-
-async fn send_gateway_error(
-    socket: &mut WebSocket,
-    error: &GatewayError,
-    request_id: &str,
-) -> ForwardOutcome {
-    let (status, default_type, default_code) = gateway_error_contract(error.kind());
-    if send_error_event(
-        socket,
-        status,
-        error.client_error_type().unwrap_or(default_type),
-        error.client_error_code().unwrap_or(default_code),
-        error.client_message(),
-        None,
-        request_id,
-    )
-    .await
-    {
-        ForwardOutcome::Continue
-    } else {
-        ForwardOutcome::Disconnect
-    }
-}
-
-async fn send_protocol_error(
-    socket: &mut WebSocket,
-    status: StatusCode,
-    body: ProtocolErrorBody,
-    request_id: &str,
-) -> ForwardOutcome {
-    let error = body.error;
-    if send_error_event(
-        socket,
-        status,
-        error.kind,
-        error.code,
-        &error.message,
-        error.param.as_deref(),
-        request_id,
-    )
-    .await
-    {
-        ForwardOutcome::Continue
-    } else {
-        ForwardOutcome::Disconnect
-    }
-}
-
-async fn send_error_event(
-    socket: &mut WebSocket,
-    status: StatusCode,
-    error_type: &str,
-    code: &str,
-    message: &str,
-    param: Option<&str>,
-    request_id: &str,
-) -> bool {
-    let mut error = Map::new();
-    error.insert("type".to_owned(), Value::String(error_type.to_owned()));
-    error.insert("code".to_owned(), Value::String(code.to_owned()));
-    error.insert("message".to_owned(), Value::String(message.to_owned()));
-    if let Some(param) = param {
-        error.insert("param".to_owned(), Value::String(param.to_owned()));
-    }
-    send_text(
-        socket,
-        json!({
-            "type": "error",
-            "status": status.as_u16(),
-            "error": error,
-            "request_id": request_id,
-        })
-        .to_string(),
-    )
-    .await
-}
-
-async fn send_messages(socket: &mut WebSocket, messages: Vec<String>) -> bool {
-    for message in messages {
-        if !send_text(socket, message).await {
-            return false;
-        }
-    }
-    true
-}
-
-async fn send_text(socket: &mut WebSocket, payload: String) -> bool {
-    if let Err(error) = socket.send(Message::Text(payload.into())).await {
-        tracing::info!(error = %error, "Responses WebSocket send failed");
-        return false;
-    }
-    true
-}
-
-async fn close_for_protocol_violation(socket: &mut WebSocket, reason: &'static str) {
-    let _ = socket
-        .send(Message::Close(Some(CloseFrame {
-            code: close_code::POLICY,
-            reason: reason.into(),
-        })))
-        .await;
-}
@@ -0,0 +1,672 @@
+//! 下游客户端 WebSocket 的单 owner pump 与有界收发边界。
+
+use std::{
+    fmt,
+    sync::{
+        Arc,
+        atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use axum::extract::ws::{CloseFrame, Message, WebSocket, close_code};
+use futures::{Sink, SinkExt, Stream, StreamExt};
+use gateway_core::lifecycle::CancellationToken;
+use thiserror::Error;
+use tokio::{
+    sync::{mpsc, oneshot},
+    task::JoinHandle,
+    time::{Instant, timeout},
+};
+
+const OUTBOUND_COMMAND_BUFFER: usize = 32;
+const INBOUND_EVENT_BUFFER: usize = 32;
+const DOWNSTREAM_WRITE_TIMEOUT: Duration = Duration::from_secs(5 * 60);
+const CONNECTION_MAX_AGE: Duration = Duration::from_secs(60 * 60);
+const DOWNSTREAM_PING_INTERVAL: Duration = Duration::from_secs(25);
+
+/// WebSocket pump 的写入与生命周期预算。
+#[derive(Clone, Copy)]
+pub struct ConnectionConfig {
+    write_timeout: Duration,
+    max_age: Duration,
+}
+
+impl ConnectionConfig {
+    /// 生产环境固定预算。
+    pub const PRODUCTION: Self = Self {
+        write_timeout: DOWNSTREAM_WRITE_TIMEOUT,
+        max_age: CONNECTION_MAX_AGE,
+    };
+}
+
+/// 业务层可观察的客户端输入；Ping/Pong 始终由 pump 消费。
+pub enum ConnectionEvent {
+    Text(String),
+    Binary,
+    Expired,
+    Exited(PumpExitReason),
+}
+
+/// 下游写入阶段；名称刻意使用 write，而不是暗示客户端已消费的 delivery。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FramePhase {
+    Metadata,
+    First,
+    Data,
+    Terminal,
+    FirstAndTerminal,
+    Error,
+    ConnectionLimit,
+    Close,
+}
+
+impl FramePhase {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::Metadata => "metadata",
+            Self::First => "first",
+            Self::Data => "data",
+            Self::Terminal => "terminal",
+            Self::FirstAndTerminal => "first_and_terminal",
+            Self::Error => "error",
+            Self::ConnectionLimit => "connection_limit",
+            Self::Close => "close",
+        }
+    }
+
+    const fn is_milestone(self) -> bool {
+        matches!(
+            self,
+            Self::First
+                | Self::Terminal
+                | Self::FirstAndTerminal
+                | Self::Error
+                | Self::ConnectionLimit
+                | Self::Close
+        )
+    }
+}
+
+/// 一次下游写入的请求归属与协议阶段。
+#[derive(Clone)]
+pub struct WriteContext {
+    request_id: Option<Arc<str>>,
+    phase: FramePhase,
+}
+
+impl WriteContext {
+    /// 创建归属于某个请求的写入上下文。
+    #[must_use]
+    pub fn request(request_id: &Arc<str>, phase: FramePhase) -> Self {
+        Self {
+            request_id: Some(Arc::clone(request_id)),
+            phase,
+        }
+    }
+
+    /// 创建连接级写入上下文。
+    #[must_use]
+    pub const fn connection(phase: FramePhase) -> Self {
+        Self {
+            request_id: None,
+            phase,
+        }
+    }
+}
+
+/// WebSocket pump 停止的稳定原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PumpExitReason {
+    ClientClose,
+    PeerEof,
+    ReadError,
+    WriteError,
+    WriteTimeout,
+    LifecycleShutdown,
+    ConnectionMaxAge,
+    CoordinatorDropped,
+    InboundOverload,
+    ServerClose,
+    PumpStopped,
+}
+
+impl PumpExitReason {
+    pub(super) const fn as_str(self) -> &'static str {
+        match self {
+            Self::ClientClose => "client_close",
+            Self::PeerEof => "peer_eof",
+            Self::ReadError => "read_error",
+            Self::WriteError => "write_error",
+            Self::WriteTimeout => "write_timeout",
+            Self::LifecycleShutdown => "lifecycle_shutdown",
+            Self::ConnectionMaxAge => "connection_max_age",
+            Self::CoordinatorDropped => "coordinator_dropped",
+            Self::InboundOverload => "inbound_overload",
+            Self::ServerClose => "server_close",
+            Self::PumpStopped => "pump_stopped",
+        }
+    }
+}
+
+/// 下游 WebSocket 写入失败。
+#[derive(Debug, Error)]
+pub enum ConnectionWriteError {
+    #[error("downstream WebSocket pump is closed")]
+    Closed,
+    #[error("downstream WebSocket write timed out after {timeout:?}")]
+    Timeout { timeout: Duration },
+    #[error("downstream WebSocket transport write failed: {message}")]
+    Transport { message: String },
+}
+
+struct ConnectionCommand {
+    message: Message,
+    context: WriteContext,
+    acknowledged: oneshot::Sender<Result<(), ConnectionWriteError>>,
+}
+
+#[derive(Default)]
+struct ConnectionStats {
+    command_queue_high_water: AtomicUsize,
+    command_backpressure_count: AtomicU64,
+    ping_received_count: AtomicU64,
+    pong_written_count: AtomicU64,
+    ping_written_count: AtomicU64,
+    pong_received_count: AtomicU64,
+    last_read_ms: AtomicU64,
+    last_write_ms: AtomicU64,
+}
+
+impl ConnectionStats {
+    fn record_read(&self, opened_at: Instant) {
+        self.last_read_ms.store(
+            u64::try_from(opened_at.elapsed().as_millis()).unwrap_or(u64::MAX),
+            Ordering::Relaxed,
+        );
+    }
+
+    fn record_write(&self, opened_at: Instant) {
+        self.last_write_ms.store(
+            u64::try_from(opened_at.elapsed().as_millis()).unwrap_or(u64::MAX),
+            Ordering::Relaxed,
+        );
+    }
+
+    fn observe_command_queue(&self, sender: &mpsc::Sender<ConnectionCommand>) {
+        let queued = OUTBOUND_COMMAND_BUFFER
+            .saturating_sub(sender.capacity())
+            .saturating_add(1)
+            .min(OUTBOUND_COMMAND_BUFFER);
+        self.command_queue_high_water
+            .fetch_max(queued, Ordering::Relaxed);
+        if sender.capacity() == 0 {
+            self.command_backpressure_count
+                .fetch_add(1, Ordering::Relaxed);
+        }
+    }
+}
+
+/// 协调层持有的单 owner WebSocket 连接句柄。
+pub struct ResponsesWebSocketConnection {
+    connection_id: Arc<str>,
+    opened_at: Instant,
+    expired: Arc<AtomicBool>,
+    commands: Option<mpsc::Sender<ConnectionCommand>>,
+    incoming: mpsc::Receiver<ConnectionEvent>,
+    exited: oneshot::Receiver<PumpExitReason>,
+    pump_task: Option<JoinHandle<()>>,
+    stats: Arc<ConnectionStats>,
+    config: ConnectionConfig,
+    exit_reason: Option<PumpExitReason>,
+}
+
+impl ResponsesWebSocketConnection {
+    pub(super) fn new(
+        socket: WebSocket,
+        connection_id: String,
+        cancellation: CancellationToken,
+    ) -> Self {
+        spawn_connection(
+            socket,
+            Arc::<str>::from(connection_id),
+            cancellation,
+            ConnectionConfig::PRODUCTION,
+        )
+    }
+
+    pub(super) fn id(&self) -> &str {
+        &self.connection_id
+    }
+
+    /// 返回连接是否已经达到生命周期上限。
+    #[must_use]
+    pub fn is_expired(&self) -> bool {
+        self.expired.load(Ordering::Acquire)
+    }
+
+    pub(super) fn age(&self) -> Duration {
+        self.opened_at.elapsed()
+    }
+
+    /// 等待下一个需要业务层处理的客户端事件。
+    pub async fn next_event(&mut self) -> Option<ConnectionEvent> {
+        if let Some(reason) = self.exit_reason {
+            return Some(ConnectionEvent::Exited(reason));
+        }
+        let event = tokio::select! {
+            biased;
+            reason = &mut self.exited => {
+                Some(ConnectionEvent::Exited(reason.unwrap_or(PumpExitReason::PumpStopped)))
+            }
+            event = self.incoming.recv() => event,
+        };
+        if let Some(ConnectionEvent::Exited(reason)) = event.as_ref() {
+            self.exit_reason.get_or_insert(*reason);
+        } else if event.is_none() {
+            self.exit_reason.get_or_insert(PumpExitReason::PumpStopped);
+        }
+        event
+    }
+
+    /// 等待连接退出，不消费留给后续串行请求的业务帧。
+    pub async fn wait_for_exit(&mut self) -> PumpExitReason {
+        if let Some(reason) = self.exit_reason {
+            return reason;
+        }
+        let reason = (&mut self.exited)
+            .await
+            .unwrap_or(PumpExitReason::PumpStopped);
+        self.exit_reason = Some(reason);
+        reason
+    }
+
+    /// 串行写入文本帧，并等待 pump 确认 transport 写入结果。
+    ///
+    /// # Errors
+    ///
+    /// pump 已关闭、写入超时或 transport 失败时返回稳定错误。
+    pub async fn send_text(
+        &mut self,
+        payload: String,
+        context: WriteContext,
+    ) -> Result<(), ConnectionWriteError> {
+        self.send(Message::Text(payload.into()), context).await
+    }
+
+    pub(super) async fn close_policy(
+        &mut self,
+        reason: &'static str,
+        request_id: Option<&Arc<str>>,
+    ) {
+        let context = request_id.map_or_else(
+            || WriteContext::connection(FramePhase::Close),
+            |request_id| WriteContext::request(request_id, FramePhase::Close),
+        );
+        self.close(
+            CloseFrame {
+                code: close_code::POLICY,
+                reason: reason.into(),
+            },
+            context,
+            PumpExitReason::ServerClose,
+        )
+        .await;
+    }
+
+    pub(super) async fn close_for_connection_limit(&mut self, reason: &'static str) {
+        self.close(
+            CloseFrame {
+                code: close_code::NORMAL,
+                reason: reason.into(),
+            },
+            WriteContext::connection(FramePhase::Close),
+            PumpExitReason::ConnectionMaxAge,
+        )
+        .await;
+    }
+
+    async fn close(
+        &mut self,
+        frame: CloseFrame,
+        context: WriteContext,
+        exit_reason: PumpExitReason,
+    ) {
+        if self
+            .send(Message::Close(Some(frame)), context)
+            .await
+            .is_ok()
+        {
+            self.exit_reason.get_or_insert(exit_reason);
+        }
+    }
+
+    async fn send(
+        &mut self,
+        message: Message,
+        context: WriteContext,
+    ) -> Result<(), ConnectionWriteError> {
+        let Some(commands) = self.commands.as_ref().cloned() else {
+            return Err(ConnectionWriteError::Closed);
+        };
+        self.stats.observe_command_queue(&commands);
+        let (acknowledged, acknowledgement) = oneshot::channel();
+        let started_at = Instant::now();
+        let request_id = context.request_id.clone();
+        let phase = context.phase;
+        let command = ConnectionCommand {
+            message,
+            context,
+            acknowledged,
+        };
+        let write = async move {
+            commands
+                .send(command)
+                .await
+                .map_err(|_| ConnectionWriteError::Closed)?;
+            acknowledgement
+                .await
+                .map_err(|_| ConnectionWriteError::Closed)?
+        };
+        let result = match timeout(self.config.write_timeout, write).await {
+            Ok(result) => result,
+            Err(_) => Err(ConnectionWriteError::Timeout {
+                timeout: self.config.write_timeout,
+            }),
+        };
+        let duration = started_at.elapsed();
+        match &result {
+            Ok(()) if phase.is_milestone() => tracing::info!(
+                websocket_connection_id = %self.connection_id,
+                request_id = request_id.as_deref().unwrap_or(""),
+                frame_phase = phase.as_str(),
+                write_duration_ms = duration.as_millis(),
+                "Responses WebSocket frame write succeeded"
+            ),
+            Ok(()) => tracing::debug!(
+                websocket_connection_id = %self.connection_id,
+                request_id = request_id.as_deref().unwrap_or(""),
+                frame_phase = phase.as_str(),
+                write_duration_ms = duration.as_millis(),
+                "Responses WebSocket frame write succeeded"
+            ),
+            Err(error) => tracing::info!(
+                websocket_connection_id = %self.connection_id,
+                request_id = request_id.as_deref().unwrap_or(""),
+                frame_phase = phase.as_str(),
+                write_duration_ms = duration.as_millis(),
+                error = %error,
+                "Responses WebSocket frame write failed"
+            ),
+        }
+        if let Err(error) = &result {
+            let reason = match error {
+                ConnectionWriteError::Timeout { .. } => PumpExitReason::WriteTimeout,
+                ConnectionWriteError::Transport { .. } => PumpExitReason::WriteError,
+                ConnectionWriteError::Closed => PumpExitReason::PumpStopped,
+            };
+            self.terminate(reason);
+        }
+        result
+    }
+
+    fn terminate(&mut self, reason: PumpExitReason) {
+        self.exit_reason.get_or_insert(reason);
+        self.commands.take();
+        if let Some(task) = self.pump_task.take() {
+            task.abort();
+        }
+    }
+
+    pub(super) fn log_summary(&self, request_count: u64) {
+        let connection_age_ms = self.age().as_millis();
+        let read_idle_ms = connection_age_ms
+            .saturating_sub(u128::from(self.stats.last_read_ms.load(Ordering::Relaxed)));
+        let write_idle_ms = connection_age_ms
+            .saturating_sub(u128::from(self.stats.last_write_ms.load(Ordering::Relaxed)));
+        tracing::info!(
+            websocket_connection_id = %self.connection_id,
+            request_count,
+            connection_age_ms,
+            pump_exit_reason = self
+                .exit_reason
+                .map_or("unknown", PumpExitReason::as_str),
+            command_queue_high_water = self
+                .stats
+                .command_queue_high_water
+                .load(Ordering::Relaxed),
+            command_backpressure_count = self
+                .stats
+                .command_backpressure_count
+                .load(Ordering::Relaxed),
+            ping_received_count = self.stats.ping_received_count.load(Ordering::Relaxed),
+            pong_written_count = self.stats.pong_written_count.load(Ordering::Relaxed),
+            ping_written_count = self.stats.ping_written_count.load(Ordering::Relaxed),
+            pong_received_count = self.stats.pong_received_count.load(Ordering::Relaxed),
+            read_idle_ms,
+            write_idle_ms,
+            "Responses WebSocket disconnected"
+        );
+    }
+}
+
+impl Drop for ResponsesWebSocketConnection {
+    fn drop(&mut self) {
+        self.commands.take();
+        if let Some(task) = self.pump_task.take() {
+            task.abort();
+        }
+    }
+}
+
+/// 为一个 socket 启动单 owner pump，并返回协调层句柄。
+pub fn spawn_connection<S, E>(
+    socket: S,
+    connection_id: Arc<str>,
+    cancellation: CancellationToken,
+    config: ConnectionConfig,
+) -> ResponsesWebSocketConnection
+where
+    S: Stream<Item = Result<Message, E>> + Sink<Message, Error = E> + Unpin + Send + 'static,
+    E: fmt::Display + Send + 'static,
+{
+    let opened_at = Instant::now();
+    let expired = Arc::new(AtomicBool::new(false));
+    let stats = Arc::new(ConnectionStats::default());
+    let (command_tx, command_rx) = mpsc::channel(OUTBOUND_COMMAND_BUFFER);
+    let (incoming_tx, incoming_rx) = mpsc::channel(INBOUND_EVENT_BUFFER);
+    let (exit_tx, exit_rx) = oneshot::channel();
+    let pump_task = tokio::spawn(run_pump(
+        socket,
+        command_rx,
+        incoming_tx,
+        exit_tx,
+        Arc::clone(&connection_id),
+        cancellation,
+        opened_at,
+        Arc::clone(&expired),
+        Arc::clone(&stats),
+        config,
+    ));
+    ResponsesWebSocketConnection {
+        connection_id,
+        opened_at,
+        expired,
+        commands: Some(command_tx),
+        incoming: incoming_rx,
+        exited: exit_rx,
+        pump_task: Some(pump_task),
+        stats,
+        config,
+        exit_reason: None,
+    }
+}
+
+#[expect(clippy::too_many_arguments)]
+async fn run_pump<S, E>(
+    mut socket: S,
+    mut commands: mpsc::Receiver<ConnectionCommand>,
+    incoming: mpsc::Sender<ConnectionEvent>,
+    exited: oneshot::Sender<PumpExitReason>,
+    connection_id: Arc<str>,
+    cancellation: CancellationToken,
+    opened_at: Instant,
+    expired: Arc<AtomicBool>,
+    stats: Arc<ConnectionStats>,
+    config: ConnectionConfig,
+) where
+    S: Stream<Item = Result<Message, E>> + Sink<Message, Error = E> + Unpin,
+    E: fmt::Display,
+{
+    let deadline = tokio::time::sleep_until(opened_at + config.max_age);
+    tokio::pin!(deadline);
+    let mut deadline_elapsed = false;
+    let mut heartbeat = tokio::time::interval_at(
+        opened_at + DOWNSTREAM_PING_INTERVAL,
+        DOWNSTREAM_PING_INTERVAL,
+    );
+    heartbeat.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    let mut ping_sequence = 0_u64;
+    let reason = loop {
+        tokio::select! {
+            biased;
+            () = cancellation.cancelled() => break PumpExitReason::LifecycleShutdown,
+            () = &mut deadline, if !deadline_elapsed => {
+                deadline_elapsed = true;
+                expired.store(true, Ordering::Release);
+                // 满队列本身已能唤醒空闲协调层；到期标志仍阻止启动下一轮。
+                // 不能因无法追加 Expired 通知而中断正在收尾的响应。
+                match incoming.try_send(ConnectionEvent::Expired) {
+                    Ok(()) | Err(mpsc::error::TrySendError::Full(_)) => {}
+                    Err(mpsc::error::TrySendError::Closed(_)) => {
+                        break PumpExitReason::CoordinatorDropped;
+                    }
+                }
+            }
+            command = commands.recv() => {
+                let Some(command) = command else {
+                    break PumpExitReason::CoordinatorDropped;
+                };
+                let ConnectionCommand {
+                    message,
+                    context,
+                    acknowledged,
+                } = command;
+                let closing = matches!(message, Message::Close(_));
+                let result = socket.send(message).await.map_err(|error| {
+                    let message = error.to_string();
+                    tracing::debug!(
+                        websocket_connection_id = %connection_id,
+                        request_id = context.request_id.as_deref().unwrap_or(""),
+                        frame_phase = context.phase.as_str(),
+                        error = %message,
+                        "Responses WebSocket pump transport write failed"
+                    );
+                    ConnectionWriteError::Transport { message }
+                });
+                let failed = result.is_err();
+                if !failed {
+                    stats.record_write(opened_at);
+                }
+                let _ = acknowledged.send(result);
+                if failed {
+                    break PumpExitReason::WriteError;
+                }
+                if closing {
+                    break PumpExitReason::ServerClose;
+                }
+            }
+            // 官方 Codex WsStream 在独立 pump 中回复 Pong，且不将控制帧交给业务流。
+            // 这里只为下游链路保活，不设置 Pong deadline，也不延长业务请求预算。
+            _ = heartbeat.tick() => {
+                ping_sequence = ping_sequence.wrapping_add(1);
+                let ping = Message::Ping(ping_sequence.to_be_bytes().to_vec().into());
+                let result = tokio::select! {
+                    biased;
+                    () = cancellation.cancelled() => break PumpExitReason::LifecycleShutdown,
+                    result = timeout(config.write_timeout, socket.send(ping)) => result,
+                };
+                match result {
+                    Ok(Ok(())) => {
+                        stats.ping_written_count.fetch_add(1, Ordering::Relaxed);
+                        stats.record_write(opened_at);
+                    }
+                    Ok(Err(error)) => {
+                        tracing::info!(
+                            websocket_connection_id = %connection_id,
+                            error = %error,
+                            "Responses WebSocket Ping write failed"
+                        );
+                        break PumpExitReason::WriteError;
+                    }
+                    Err(_) => break PumpExitReason::WriteTimeout,
+                }
+            }
+            message = socket.next() => {
+                if matches!(&message, Some(Ok(_))) {
+                    stats.record_read(opened_at);
+                }
+                match message {
+                    Some(Ok(Message::Text(payload))) => {
+                        if let Err(reason) = emit_incoming(&incoming, ConnectionEvent::Text(payload.to_string())) {
+                            break reason;
+                        }
+                    }
+                    Some(Ok(Message::Binary(_))) => {
+                        if let Err(reason) = emit_incoming(&incoming, ConnectionEvent::Binary) {
+                            break reason;
+                        }
+                    }
+                    Some(Ok(Message::Ping(payload))) => {
+                        stats.ping_received_count.fetch_add(1, Ordering::Relaxed);
+                        match timeout(config.write_timeout, socket.send(Message::Pong(payload))).await {
+                            Ok(Ok(())) => {
+                                stats.pong_written_count.fetch_add(1, Ordering::Relaxed);
+                                stats.record_write(opened_at);
+                            }
+                            Ok(Err(error)) => {
+                                tracing::info!(
+                                    websocket_connection_id = %connection_id,
+                                    error = %error,
+                                    "Responses WebSocket Pong write failed"
+                                );
+                                break PumpExitReason::WriteError;
+                            }
+                            Err(_) => break PumpExitReason::WriteTimeout,
+                        }
+                    }
+                    Some(Ok(Message::Pong(_))) => {
+                        stats.pong_received_count.fetch_add(1, Ordering::Relaxed);
+                    }
+                    Some(Ok(Message::Close(_))) => break PumpExitReason::ClientClose,
+                    Some(Err(error)) => {
+                        tracing::info!(
+                            websocket_connection_id = %connection_id,
+                            error = %error,
+                            "Responses WebSocket receive failed"
+                        );
+                        break PumpExitReason::ReadError;
+                    }
+                    None => break PumpExitReason::PeerEof,
+                }
+            },
+        }
+    };
+    // 退出不能排在待执行请求之后，也不能因业务队列已满而丢失。
+    let _ = exited.send(reason);
+    tracing::debug!(
+        websocket_connection_id = %connection_id,
+        pump_exit_reason = reason.as_str(),
+        "Responses WebSocket pump exited"
+    );
+}
+
+fn emit_incoming(
+    incoming: &mpsc::Sender<ConnectionEvent>,
+    event: ConnectionEvent,
+) -> Result<(), PumpExitReason> {
+    incoming.try_send(event).map_err(|error| match error {
+        mpsc::error::TrySendError::Full(_) => PumpExitReason::InboundOverload,
+        mpsc::error::TrySendError::Closed(_) => PumpExitReason::CoordinatorDropped,
+    })
+}
@@ -0,0 +1,481 @@
+//! 已启动 Responses execution 到客户端 WebSocket wire event 的串行转发。
+
+use std::sync::Arc;
+
+use axum::http::StatusCode;
+use gateway_core::engine::execution::StartedExecution;
+use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError};
+use gateway_core::error::{GatewayError, GatewayErrorKind};
+use gateway_core::operation::ProviderSessionState;
+use tokio::time::Instant;
+
+use crate::openai::error::{gateway_error_contract, gateway_error_from_engine};
+
+use super::{
+    super::{DecodedResponsesRequest, OpenAiResponsesEncoder, PendingExecution, ProtocolErrorBody},
+    connection::{FramePhase, ResponsesWebSocketConnection, WriteContext},
+    protocol::{error_event, response_metadata_event},
+};
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub(super) enum ForwardOutcome {
+    Continue,
+    Disconnect,
+}
+
+#[derive(Default)]
+pub(super) struct ConnectionReplaySnapshot {
+    last_response_id: Option<String>,
+    provider_state: Option<ProviderSessionState>,
+}
+
+impl ConnectionReplaySnapshot {
+    pub(super) fn prepare(&self, request: DecodedResponsesRequest) -> DecodedResponsesRequest {
+        match (
+            request.metadata().continuation().previous_response_id(),
+            self.last_response_id.as_deref(),
+            self.provider_state.as_ref(),
+        ) {
+            (Some(previous), Some(last), Some(state)) if previous == last => {
+                request.with_provider_session_state(state.clone())
+            }
+            _ => request,
+        }
+    }
+
+    fn commit(&mut self, response_id: String, provider_state: Option<ProviderSessionState>) {
+        self.last_response_id = Some(response_id);
+        self.provider_state = provider_state;
+    }
+}
+
+pub(super) async fn forward_execution(
+    connection: &mut ResponsesWebSocketConnection,
+    started: StartedExecution,
+    replay: &mut ConnectionReplaySnapshot,
+) -> ForwardOutcome {
+    let request_id = Arc::<str>::from(started.request_id.to_string());
+    let streaming = started.stream;
+    let mut execution = PendingExecution::new(started.session);
+    if !streaming {
+        let error = GatewayError::new(
+            GatewayErrorKind::Internal,
+            "WebSocket execution was not initialized as a stream",
+        );
+        return send_gateway_error(connection, &error, &request_id).await;
+    }
+    let first = match next_active_input(connection, &mut execution).await {
+        ActiveInput::Event(Ok(Some(event))) => event,
+        ActiveInput::Event(Ok(None)) => {
+            let error = GatewayError::new(
+                GatewayErrorKind::Internal,
+                "gateway response ended before its first event",
+            );
+            return send_gateway_error(connection, &error, &request_id).await;
+        }
+        ActiveInput::Event(Err(error)) => {
+            return send_initial_engine_error(connection, &mut execution, &error, &request_id)
+                .await;
+        }
+        ActiveInput::Disconnect => return ForwardOutcome::Disconnect,
+    };
+    let requirement = first.commit_requirement();
+    let mut first = first.into_provider_events();
+    if requirement != CommitRequirement::CommitBeforeDelivery {
+        let error = GatewayError::new(
+            GatewayErrorKind::Internal,
+            "gateway first event did not require commit",
+        );
+        return send_gateway_error(connection, &error, &request_id).await;
+    }
+    let mut encoder = OpenAiResponsesEncoder::new();
+    let mut provider_state = None;
+    let mut first_messages = Vec::new();
+    for event in &mut first {
+        if let Some(update) = event.take_session_update() {
+            provider_state = Some(update);
+        }
+        first_messages.extend(encoder.push_websocket(event));
+    }
+    if first_messages.is_empty() {
+        let error = GatewayError::new(
+            GatewayErrorKind::Internal,
+            "gateway commit batch encoded no output",
+        );
+        return send_gateway_error(connection, &error, &request_id).await;
+    }
+    let Some(response_session) = execution.session_mut() else {
+        return ForwardOutcome::Disconnect;
+    };
+    let response_headers = response_session.response_headers().to_vec();
+    if let Err(error) = response_session.commit_downstream(None).await {
+        let error = gateway_error_from_engine(&error);
+        return send_gateway_error(connection, &error, &request_id).await;
+    }
+    let mut first_frame_written = false;
+    if encoder.is_completed() {
+        if let Err(outcome) =
+            confirm_completed_execution(connection, &mut execution, &request_id).await
+        {
+            return outcome;
+        }
+        let provider_terminal_at = Instant::now();
+        commit_connection_replay(replay, &encoder, provider_state.take());
+        let writes_succeeded = send_metadata(
+            connection,
+            &request_id,
+            response_metadata_event(&request_id, &response_headers),
+        )
+        .await
+            && send_messages(
+                connection,
+                first_messages,
+                &request_id,
+                &mut first_frame_written,
+                true,
+            )
+            .await;
+        if !writes_succeeded {
+            log_terminal_write_failure(connection, &request_id, provider_terminal_at.elapsed());
+            return ForwardOutcome::Disconnect;
+        }
+        log_terminal_write_success(connection, &request_id, provider_terminal_at.elapsed());
+        execution.disarm();
+        return ForwardOutcome::Continue;
+    }
+    if !send_metadata(
+        connection,
+        &request_id,
+        response_metadata_event(&request_id, &response_headers),
+    )
+    .await
+        || !send_messages(
+            connection,
+            first_messages,
+            &request_id,
+            &mut first_frame_written,
+            encoder.has_wire_failure(),
+        )
+        .await
+    {
+        return ForwardOutcome::Disconnect;
+    }
+
+    loop {
+        match next_active_input(connection, &mut execution).await {
+            ActiveInput::Event(Ok(Some(delivery))) => {
+                let requirement = delivery.commit_requirement();
+                let mut events = delivery.into_provider_events();
+                if requirement != CommitRequirement::AlreadyCommitted {
+                    let error = GatewayError::new(
+                        GatewayErrorKind::Internal,
+                        "gateway requested another downstream commit",
+                    );
+                    return send_gateway_error(connection, &error, &request_id).await;
+                }
+                let mut messages = Vec::new();
+                for event in &mut events {
+                    if let Some(update) = event.take_session_update() {
+                        provider_state = Some(update);
+                    }
+                    messages.extend(encoder.push_websocket(event));
+                }
+                if encoder.is_completed() {
+                    if let Err(outcome) =
+                        confirm_completed_execution(connection, &mut execution, &request_id).await
+                    {
+                        return outcome;
+                    }
+                    let provider_terminal_at = Instant::now();
+                    commit_connection_replay(replay, &encoder, provider_state.take());
+                    if !send_messages(
+                        connection,
+                        messages,
+                        &request_id,
+                        &mut first_frame_written,
+                        true,
+                    )
+                    .await
+                    {
+                        log_terminal_write_failure(
+                            connection,
+                            &request_id,
+                            provider_terminal_at.elapsed(),
+                        );
+                        return ForwardOutcome::Disconnect;
+                    }
+                    log_terminal_write_success(
+                        connection,
+                        &request_id,
+                        provider_terminal_at.elapsed(),
+                    );
+                    execution.disarm();
+                    return ForwardOutcome::Continue;
+                }
+                let terminal_batch = encoder.has_wire_failure();
+                if !send_messages(
+                    connection,
+                    messages,
+                    &request_id,
+                    &mut first_frame_written,
+                    terminal_batch,
+                )
+                .await
+                {
+                    return ForwardOutcome::Disconnect;
+                }
+            }
+            ActiveInput::Event(Ok(None)) => {
+                if execution
+                    .session_mut()
+                    .is_some_and(|session| session.is_finalized())
+                {
+                    commit_connection_replay(replay, &encoder, provider_state.take());
+                    execution.disarm();
+                    return ForwardOutcome::Continue;
+                }
+                let error = GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "gateway response ended without finalizing the execution",
+                );
+                return send_gateway_error(connection, &error, &request_id).await;
+            }
+            ActiveInput::Event(Err(error)) => {
+                if encoder.has_wire_failure() {
+                    execution.disarm();
+                    return ForwardOutcome::Continue;
+                }
+                let error = gateway_error_from_engine(&error);
+                return send_gateway_error(connection, &error, &request_id).await;
+            }
+            ActiveInput::Disconnect => return ForwardOutcome::Disconnect,
+        }
+    }
+}
+
+async fn send_initial_engine_error(
+    connection: &mut ResponsesWebSocketConnection,
+    execution: &mut PendingExecution,
+    error: &EngineError,
+    request_id: &Arc<str>,
+) -> ForwardOutcome {
+    let response_headers = execution
+        .session_mut()
+        .map(|session| session.response_headers().to_vec())
+        .unwrap_or_default();
+    if !response_headers.is_empty()
+        && !send_metadata(
+            connection,
+            request_id,
+            response_metadata_event(request_id, &response_headers),
+        )
+        .await
+    {
+        return ForwardOutcome::Disconnect;
+    }
+    let error = gateway_error_from_engine(error);
+    send_gateway_error(connection, &error, request_id).await
+}
+
+fn commit_connection_replay(
+    replay: &mut ConnectionReplaySnapshot,
+    encoder: &OpenAiResponsesEncoder,
+    provider_state: Option<ProviderSessionState>,
+) {
+    if let Some(response_id) = encoder.response_id() {
+        replay.commit(response_id.to_owned(), provider_state);
+    }
+}
+
+async fn confirm_completed_execution(
+    connection: &mut ResponsesWebSocketConnection,
+    execution: &mut PendingExecution,
+    request_id: &Arc<str>,
+) -> Result<(), ForwardOutcome> {
+    match next_active_input(connection, execution).await {
+        ActiveInput::Event(Ok(None))
+            if execution
+                .session_mut()
+                .is_some_and(|session| session.is_finalized()) =>
+        {
+            Ok(())
+        }
+        ActiveInput::Event(Ok(None)) => {
+            let error = GatewayError::new(
+                GatewayErrorKind::Internal,
+                "gateway response was not finalized after its terminal event",
+            );
+            Err(send_gateway_error(connection, &error, request_id).await)
+        }
+        ActiveInput::Event(Ok(Some(_))) => {
+            let error = GatewayError::new(
+                GatewayErrorKind::Internal,
+                "gateway response continued after its terminal event",
+            );
+            Err(send_gateway_error(connection, &error, request_id).await)
+        }
+        ActiveInput::Event(Err(error)) => {
+            let error = gateway_error_from_engine(&error);
+            Err(send_gateway_error(connection, &error, request_id).await)
+        }
+        ActiveInput::Disconnect => Err(ForwardOutcome::Disconnect),
+    }
+}
+
+enum ActiveInput {
+    Event(Result<Option<CoordinatedEvent>, EngineError>),
+    Disconnect,
+}
+
+async fn next_active_input(
+    connection: &mut ResponsesWebSocketConnection,
+    execution: &mut PendingExecution,
+) -> ActiveInput {
+    let Some(session) = execution.session_mut() else {
+        return ActiveInput::Disconnect;
+    };
+    // 与 Codex stream_request 的连接锁一致：本轮结束前不消费下一条请求。
+    // pump 继续接收有界业务帧和处理 Ping/Pong；退出通过独立通知取消本轮。
+    tokio::select! {
+        biased;
+        _ = connection.wait_for_exit() => {
+            session.trace().record("downstream.cancelled", serde_json::json!({
+                "reason": "websocket_connection_exit", "connectionId": connection.id(),
+            }));
+            ActiveInput::Disconnect
+        },
+        event = session.next_event() => ActiveInput::Event(event),
+    }
+}
+
+pub(super) async fn send_gateway_error(
+    connection: &mut ResponsesWebSocketConnection,
+    error: &GatewayError,
+    request_id: &Arc<str>,
+) -> ForwardOutcome {
+    let (status, default_type, default_code) = gateway_error_contract(error.kind());
+    send_error(
+        connection,
+        status,
+        error.client_error_type().unwrap_or(default_type),
+        error.client_error_code().unwrap_or(default_code),
+        error.client_message(),
+        None,
+        request_id,
+    )
+    .await
+}
+
+pub(super) async fn send_protocol_error(
+    connection: &mut ResponsesWebSocketConnection,
+    status: StatusCode,
+    body: ProtocolErrorBody,
+    request_id: &Arc<str>,
+) -> ForwardOutcome {
+    let error = body.error;
+    send_error(
+        connection,
+        status,
+        error.kind,
+        error.code,
+        &error.message,
+        error.param.as_deref(),
+        request_id,
+    )
+    .await
+}
+
+async fn send_error(
+    connection: &mut ResponsesWebSocketConnection,
+    status: StatusCode,
+    error_type: &str,
+    code: &str,
+    message: &str,
+    param: Option<&str>,
+    request_id: &Arc<str>,
+) -> ForwardOutcome {
+    if connection
+        .send_text(
+            error_event(status, error_type, code, message, param, Some(request_id)),
+            WriteContext::request(request_id, FramePhase::Error),
+        )
+        .await
+        .is_ok()
+    {
+        ForwardOutcome::Continue
+    } else {
+        ForwardOutcome::Disconnect
+    }
+}
+
+async fn send_metadata(
+    connection: &mut ResponsesWebSocketConnection,
+    request_id: &Arc<str>,
+    message: String,
+) -> bool {
+    connection
+        .send_text(
+            message,
+            WriteContext::request(request_id, FramePhase::Metadata),
+        )
+        .await
+        .is_ok()
+}
+
+async fn send_messages(
+    connection: &mut ResponsesWebSocketConnection,
+    messages: Vec<String>,
+    request_id: &Arc<str>,
+    first_frame_written: &mut bool,
+    terminal_batch: bool,
+) -> bool {
+    let message_count = messages.len();
+    for (index, message) in messages.into_iter().enumerate() {
+        let is_terminal = terminal_batch && index + 1 == message_count;
+        let phase = match (*first_frame_written, is_terminal) {
+            (false, true) => FramePhase::FirstAndTerminal,
+            (false, false) => FramePhase::First,
+            (true, true) => FramePhase::Terminal,
+            (true, false) => FramePhase::Data,
+        };
+        if connection
+            .send_text(message, WriteContext::request(request_id, phase))
+            .await
+            .is_err()
+        {
+            return false;
+        }
+        *first_frame_written = true;
+    }
+    true
+}
+
+fn log_terminal_write_success(
+    connection: &ResponsesWebSocketConnection,
+    request_id: &Arc<str>,
+    provider_terminal_to_write: std::time::Duration,
+) {
+    tracing::info!(
+        target: "request_trace", stage = "downstream.terminal.written",
+        websocket_connection_id = connection.id(),
+        request_id = %request_id,
+        provider_terminal_to_terminal_write_ms = provider_terminal_to_write.as_millis(),
+        terminal_frame_written = true,
+        "Provider execution terminal was written to the WebSocket transport"
+    );
+}
+
+fn log_terminal_write_failure(
+    connection: &ResponsesWebSocketConnection,
+    request_id: &Arc<str>,
+    provider_terminal_to_write: std::time::Duration,
+) {
+    tracing::info!(
+        target: "request_trace", stage = "downstream.terminal.write_failed",
+        websocket_connection_id = connection.id(),
+        request_id = %request_id,
+        provider_terminal_to_terminal_write_ms = provider_terminal_to_write.as_millis(),
+        provider_succeeded_but_terminal_write_failed = true,
+        "Provider execution succeeded before the terminal WebSocket frame write failed"
+    );
+}
@@ -0,0 +1,307 @@
+//! OpenAI Responses WebSocket 的升级、连接与串行 session 编排。
+
+pub mod connection;
+mod forward;
+mod protocol;
+
+use std::{
+    net::{IpAddr, SocketAddr},
+    sync::Arc,
+};
+
+use axum::{
+    extract::{
+        Extension, State,
+        connect_info::ConnectInfo,
+        ws::{WebSocket, WebSocketUpgrade},
+    },
+    http::{HeaderMap, StatusCode},
+    response::{IntoResponse, Response},
+};
+use gateway_core::{
+    diagnostics::{TraceContext, diagnostic_json},
+    engine::execution::{AuthenticatedClient, ClientTransport},
+    lifecycle::{ConnectionGuard, ConnectionLifecycle},
+};
+
+use crate::{
+    ApiState,
+    openai::{
+        auth::{authenticate_client, client_access_error_response},
+        error::runtime_unavailable_response,
+        service::OpenAiService,
+    },
+};
+
+use super::{http::request_client_context, request::OpenAiRequestHeaders};
+use connection::{ConnectionEvent, FramePhase, ResponsesWebSocketConnection, WriteContext};
+use forward::{
+    ConnectionReplaySnapshot, ForwardOutcome, forward_execution, send_gateway_error,
+    send_protocol_error,
+};
+use protocol::connection_limit_event;
+pub use protocol::{ResponseCreateFrameError, decode_response_create_with_context};
+
+const TEXT_FRAMES_ONLY: &str = "Responses WebSocket accepts text frames only";
+const CONNECTION_LIMIT_CLOSE_REASON: &str = "Responses websocket connection limit reached";
+
+/// 将已认证的 `GET /v1/responses` 升级为 Responses WebSocket。
+pub(crate) async fn responses_websocket(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    websocket: WebSocketUpgrade,
+) -> Response {
+    let service = state.openai().clone();
+    let client = match authenticate_client(&service, &headers) {
+        Ok(client) => client,
+        Err(error) => return client_access_error_response(error),
+    };
+    let (client_ip, user_agent) = request_client_context(
+        &headers,
+        connect_info.map(|Extension(ConnectInfo(address))| address),
+    );
+    let request_headers = OpenAiRequestHeaders::from_headers(&headers);
+    ResponsesWebSocketAdapter::new(service).upgrade_with_client_context(
+        websocket,
+        client,
+        client_ip,
+        user_agent,
+        request_headers,
+        headers,
+    )
+}
+
+/// 已鉴权 Responses WebSocket 升级边界。
+#[derive(Clone)]
+pub(crate) struct ResponsesWebSocketAdapter {
+    service: OpenAiService,
+}
+
+impl ResponsesWebSocketAdapter {
+    /// 绑定应用提供的唯一 OpenAI 客户端服务端口。
+    #[must_use]
+    pub const fn new(service: OpenAiService) -> Self {
+        Self { service }
+    }
+
+    fn upgrade_with_client_context(
+        &self,
+        websocket: WebSocketUpgrade,
+        client: AuthenticatedClient,
+        client_ip: Option<IpAddr>,
+        user_agent: Option<String>,
+        request_headers: OpenAiRequestHeaders,
+        raw_headers: HeaderMap,
+    ) -> Response {
+        let connection_guard = match self.service.try_register_connection() {
+            Ok(guard) => guard,
+            Err(_) => return runtime_unavailable_response().into_response(),
+        };
+        let connection_id = self.service.next_request_id().replacen("req_", "ws_", 1);
+        TraceContext::new(&connection_id).headers(
+            "client.connection.headers",
+            serde_json::json!({"transport": "websocket", "method": "GET", "path": "/v1/responses"}),
+            raw_headers
+                .iter()
+                .map(|(name, value)| (name.as_str(), value.as_bytes())),
+        );
+        let session = ResponsesWebSocketSession {
+            service: self.service.clone(),
+            client,
+            connection_id,
+            client_ip,
+            user_agent,
+            request_headers,
+            lifecycle: self.service.lifecycle(),
+            connection_guard,
+        };
+        websocket
+            // 覆盖 axum/tungstenite 的私有 64 MiB message 与 16 MiB frame 默认值。
+            // Responses JSON 的协议可接受性由上游决定，代理不另设 wire 长度上限。
+            .max_message_size(usize::MAX)
+            .max_frame_size(usize::MAX)
+            .on_upgrade(move |socket| async move {
+                serve_responses_websocket(socket, session).await;
+            })
+    }
+}
+
+struct ResponsesWebSocketSession {
+    service: OpenAiService,
+    client: AuthenticatedClient,
+    connection_id: String,
+    client_ip: Option<IpAddr>,
+    user_agent: Option<String>,
+    request_headers: OpenAiRequestHeaders,
+    lifecycle: Arc<dyn ConnectionLifecycle>,
+    connection_guard: Box<dyn ConnectionGuard>,
+}
+
+async fn serve_responses_websocket(socket: WebSocket, session: ResponsesWebSocketSession) {
+    let ResponsesWebSocketSession {
+        service,
+        client,
+        connection_id,
+        client_ip,
+        user_agent,
+        request_headers,
+        lifecycle,
+        connection_guard,
+    } = session;
+    tracing::info!(
+        websocket_connection_id = %connection_id,
+        "Responses WebSocket connected"
+    );
+    let _connection_guard = connection_guard;
+    let cancellation = lifecycle.cancellation();
+    let request_headers =
+        request_headers.with_downstream_websocket_connection_id(connection_id.clone());
+    let mut connection = ResponsesWebSocketConnection::new(socket, connection_id, cancellation);
+    let mut request_count = 0_u64;
+    let mut replay = ConnectionReplaySnapshot::default();
+
+    loop {
+        let Some(event) = connection.next_event().await else {
+            break;
+        };
+        let payload = match event {
+            ConnectionEvent::Text(payload) => payload,
+            ConnectionEvent::Binary => {
+                connection.close_policy(TEXT_FRAMES_ONLY, None).await;
+                break;
+            }
+            ConnectionEvent::Expired => {
+                expire_connection(&mut connection).await;
+                break;
+            }
+            ConnectionEvent::Exited(_) => break,
+        };
+        if connection.is_expired() {
+            expire_connection(&mut connection).await;
+            break;
+        }
+        request_count = request_count.saturating_add(1);
+        let correlation_id = Arc::<str>::from(service.next_request_id());
+        let decoded = match decode_response_create_with_context(&payload, &request_headers) {
+            Ok(decoded) => decoded.with_client_context(client_ip, user_agent.clone()),
+            Err(error) => {
+                trace_rejected_request(
+                    &correlation_id,
+                    connection.id(),
+                    &payload,
+                    "decode",
+                    &error.to_string(),
+                );
+                if send_protocol_error(
+                    &mut connection,
+                    StatusCode::BAD_REQUEST,
+                    error.protocol_body(),
+                    &correlation_id,
+                )
+                .await
+                    == ForwardOutcome::Disconnect
+                {
+                    break;
+                }
+                continue;
+            }
+        };
+        let decoded = replay.prepare(decoded);
+        // deadline 与 Text 可能同时就绪；在任何上游执行开始前再次封住该竞争窗口。
+        if connection.is_expired() {
+            trace_rejected_request(
+                &correlation_id,
+                connection.id(),
+                &payload,
+                "connection_expired",
+                "",
+            );
+            expire_connection(&mut connection).await;
+            break;
+        }
+        let started = match service
+            .start_response(
+                client.clone(),
+                decoded,
+                ClientTransport::WebSocket,
+                "/v1/responses",
+            )
+            .await
+        {
+            Ok(started) => started,
+            Err(error) => {
+                trace_rejected_request(
+                    &correlation_id,
+                    connection.id(),
+                    &payload,
+                    "start",
+                    &error.to_string(),
+                );
+                if send_gateway_error(&mut connection, &error, &correlation_id).await
+                    == ForwardOutcome::Disconnect
+                {
+                    break;
+                }
+                continue;
+            }
+        };
+        started.session.trace().record("client.connection", serde_json::json!({
+            "transport": "websocket", "connectionId": connection.id(), "correlationId": correlation_id.as_ref(),
+            "requestIndex": request_count,
+        }));
+        started
+            .session
+            .trace()
+            .capture("client.request.body", payload.as_bytes());
+
+        if forward_execution(&mut connection, started, &mut replay).await
+            == ForwardOutcome::Disconnect
+        {
+            break;
+        }
+        if connection.is_expired() {
+            expire_connection(&mut connection).await;
+            break;
+        }
+    }
+
+    connection.log_summary(request_count);
+}
+
+// 尚未建立模型请求的拒绝也保留原文入口，用返回给客户端的 correlation ID 检索。
+fn trace_rejected_request(
+    correlation_id: &str,
+    connection_id: &str,
+    payload: &str,
+    phase: &'static str,
+    error: &str,
+) {
+    let trace = TraceContext::new(correlation_id);
+    trace.record(
+        "client.connection",
+        serde_json::json!({"connectionId": connection_id}),
+    );
+    trace.capture("client.request.body", payload.as_bytes());
+    trace.record(
+        "client.request.rejected",
+        serde_json::json!({
+            "phase": phase, "detail": diagnostic_json(&serde_json::json!({"message": error})),
+        }),
+    );
+}
+
+async fn expire_connection(connection: &mut ResponsesWebSocketConnection) {
+    if connection
+        .send_text(
+            connection_limit_event(),
+            WriteContext::connection(FramePhase::ConnectionLimit),
+        )
+        .await
+        .is_ok()
+    {
+        connection
+            .close_for_connection_limit(CONNECTION_LIMIT_CLOSE_REASON)
+            .await;
+    }
+}
@@ -0,0 +1,156 @@
+//! Responses WebSocket 入站请求与下行事件的纯协议映射。
+
+use axum::http::{HeaderName, StatusCode};
+use gateway_core::event::ProviderResponseHeader;
+use serde_json::{Map, Value, json};
+use thiserror::Error;
+
+use super::super::{
+    DecodedResponsesRequest, ProtocolErrorBody, RequestDecodeError,
+    request::{OpenAiRequestHeaders, RequestDecodeSource},
+};
+
+/// 使用连接级请求头和 Provider 上下文解码官方 `response.create` 文本帧。
+///
+/// 缺省 `stream` 等价于 WebSocket 固有的流式语义；显式 `false` 会被拒绝。
+///
+/// # Errors
+///
+/// 帧不是合法 JSON object、消息类型错误、显式关闭 stream，或 Responses 请求
+/// 无法映射到 canonical operation 时返回不包含正文内容的稳定错误。
+pub fn decode_response_create_with_context(
+    payload: &str,
+    request_headers: &OpenAiRequestHeaders,
+) -> Result<DecodedResponsesRequest, ResponseCreateFrameError> {
+    decode_response_create_inner(payload, request_headers)
+}
+
+fn decode_response_create_inner(
+    payload: &str,
+    request_headers: &OpenAiRequestHeaders,
+) -> Result<DecodedResponsesRequest, ResponseCreateFrameError> {
+    let Value::Object(mut body) = serde_json::from_str::<Value>(payload)
+        .map_err(|_| ResponseCreateFrameError::InvalidJson)?
+    else {
+        return Err(ResponseCreateFrameError::ExpectedObject);
+    };
+    match body.remove("type") {
+        Some(Value::String(message_type)) if message_type == "response.create" => {}
+        _ => return Err(ResponseCreateFrameError::UnsupportedType),
+    }
+    if matches!(body.get("stream"), Some(value) if value.as_bool() != Some(true)) {
+        return Err(ResponseCreateFrameError::StreamingRequired);
+    }
+    super::super::request::decode_request_object(
+        body,
+        request_headers,
+        RequestDecodeSource::WebSocketFrame,
+    )
+    .map_err(ResponseCreateFrameError::Request)
+}
+
+/// `response.create` 帧的稳定安全错误。
+#[derive(Debug, Clone, PartialEq, Eq, Error)]
+pub enum ResponseCreateFrameError {
+    /// 文本不是合法 JSON。
+    #[error("response.create frame must be valid JSON")]
+    InvalidJson,
+    /// 顶层不是 object。
+    #[error("response.create frame must be a JSON object")]
+    ExpectedObject,
+    /// `type` 缺失或不是 `response.create`。
+    #[error("unsupported Responses WebSocket message type")]
+    UnsupportedType,
+    /// WebSocket 请求显式声明 `stream=false`。
+    #[error("Responses WebSocket requests require stream=true")]
+    StreamingRequired,
+    /// 内层 Responses 请求无法映射到 canonical operation。
+    #[error(transparent)]
+    Request(RequestDecodeError),
+}
+
+impl ResponseCreateFrameError {
+    pub(super) fn protocol_body(&self) -> ProtocolErrorBody {
+        match self {
+            Self::Request(error) => error.protocol_body(),
+            Self::InvalidJson => RequestDecodeError::MalformedJson.protocol_body(),
+            Self::ExpectedObject => RequestDecodeError::ExpectedObject.protocol_body(),
+            Self::UnsupportedType => RequestDecodeError::InvalidValue {
+                field: "type".to_owned(),
+            }
+            .protocol_body(),
+            Self::StreamingRequired => RequestDecodeError::InvalidValue {
+                field: "stream".to_owned(),
+            }
+            .protocol_body(),
+        }
+    }
+}
+
+pub(super) fn response_metadata_event(
+    request_id: &str,
+    response_headers: &[ProviderResponseHeader],
+) -> String {
+    let connection_options = super::super::response_connection_options(response_headers);
+    let mut headers = Map::new();
+    for header in response_headers {
+        if !super::super::response_header_is_forwardable(header.name(), &connection_options) {
+            continue;
+        }
+        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+            continue;
+        };
+        let Ok(value) = std::str::from_utf8(header.value()) else {
+            continue;
+        };
+        // 官方 response.metadata 使用 string map，无法表达同名多值；后值保持既有覆盖语义。
+        headers.insert(name.as_str().to_owned(), Value::String(value.to_owned()));
+    }
+    headers
+        .entry("x-request-id".to_owned())
+        .or_insert_with(|| Value::String(request_id.to_owned()));
+    json!({
+        "type": "response.metadata",
+        "headers": headers,
+    })
+    .to_string()
+}
+
+pub(super) fn error_event(
+    status: StatusCode,
+    error_type: &str,
+    code: &str,
+    message: &str,
+    param: Option<&str>,
+    request_id: Option<&str>,
+) -> String {
+    let mut error = Map::new();
+    error.insert("type".to_owned(), Value::String(error_type.to_owned()));
+    error.insert("code".to_owned(), Value::String(code.to_owned()));
+    error.insert("message".to_owned(), Value::String(message.to_owned()));
+    if let Some(param) = param {
+        error.insert("param".to_owned(), Value::String(param.to_owned()));
+    }
+    let mut event = Map::new();
+    event.insert("type".to_owned(), Value::String("error".to_owned()));
+    event.insert("status".to_owned(), Value::Number(status.as_u16().into()));
+    event.insert("error".to_owned(), Value::Object(error));
+    if let Some(request_id) = request_id {
+        event.insert(
+            "request_id".to_owned(),
+            Value::String(request_id.to_owned()),
+        );
+    }
+    Value::Object(event).to_string()
+}
+
+pub(super) fn connection_limit_event() -> String {
+    error_event(
+        StatusCode::BAD_REQUEST,
+        "invalid_request_error",
+        "websocket_connection_limit_reached",
+        "Responses websocket connection limit reached (60 minutes). Create a new websocket connection to continue.",
+        None,
+        None,
+    )
+}
@@ -7,8 +7,10 @@ use axum::{
 };

 use super::{
-    models::{model_catalog, model_detail, model_info, models},
-    responses::{responses, responses_websocket, review_responses},
+    images::{image_edits, image_generations},
+    models::{model_detail, models},
+    responses::{responses, responses_websocket},
+    search::standalone_search,
 };

 use crate::ApiState;
@@ -16,14 +18,14 @@ use crate::ApiState;
 /// 构造 OpenAI 客户端协议路由。
 pub(crate) fn router() -> Router<ApiState> {
    Router::new()
+        .route("/v1/images/generations", post(image_generations))
+        .route("/v1/images/edits", post(image_edits))
+        .route("/v1/alpha/search", post(standalone_search))
        .route("/v1/responses", get(responses_websocket).post(responses))
-        .route("/v1/responses/review", post(review_responses))
        .route("/v1/models", get(models))
-        .route("/v1/models/catalog", get(model_catalog))
-        .route("/v1/models/{model_id}/info", get(model_info))
        // 官方 OpenAI 模型详情合同使用 path ID；它不属于 Admin API 约束。
        .route("/v1/models/{model_id}", get(model_detail))
-        // Responses 正文属于 OpenAI/Codex 协议；代理不能用私有大小上限提前拒绝
+        // OpenAI 数据面正文属于客户端/上游协议；代理不能用私有大小上限提前拒绝
        // 上游本可接受的未来 payload。
        .layer(DefaultBodyLimit::disable())
 }
@@ -0,0 +1,67 @@
+//! Codex standalone search 非流式 HTTP adapter。
+
+use std::net::SocketAddr;
+
+use axum::{
+    body::Bytes,
+    extract::{Extension, State, connect_info::ConnectInfo},
+    http::HeaderMap,
+    response::Response,
+};
+use gateway_core::error::{GatewayError, GatewayErrorKind};
+use gateway_core::operation::{Operation, RawJsonPayload, StandaloneSearchRequest};
+
+use crate::ApiState;
+use crate::openai::{
+    auth::{authenticate_client, client_access_error_response},
+    endpoint::collect_raw_json_response,
+    error::gateway_error_response,
+    responses::{OpenAiRequestHeaders, request_client_context},
+};
+
+const OPENAI_PROTOCOL: &str = "openai";
+
+/// `POST /v1/alpha/search`。
+pub(crate) async fn standalone_search(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    let service = state.openai();
+    let client = match authenticate_client(service, &headers) {
+        Ok(client) => client,
+        Err(error) => return client_access_error_response(error),
+    };
+    let (client_ip, user_agent) = request_client_context(
+        &headers,
+        connect_info.map(|Extension(ConnectInfo(address))| address),
+    );
+    let operation = match search_operation(body, &headers) {
+        Ok(operation) => operation,
+        Err(error) => return gateway_error_response(&error),
+    };
+    let started = match service
+        .start_provider_endpoint(client, operation, client_ip, user_agent, "/v1/alpha/search")
+        .await
+    {
+        Ok(started) => started,
+        Err(error) => return gateway_error_response(&error),
+    };
+    collect_raw_json_response(started).await
+}
+
+fn search_operation(body: Bytes, headers: &HeaderMap) -> Result<Operation, GatewayError> {
+    let context = OpenAiRequestHeaders::from_headers(headers).session_context();
+    let payload = RawJsonPayload::new(OPENAI_PROTOCOL, body)
+        .map_err(|_| {
+            GatewayError::new(
+                GatewayErrorKind::Internal,
+                "OpenAI protocol identifier is invalid",
+            )
+        })?
+        .with_context(context);
+    Ok(Operation::Search(StandaloneSearchRequest::from_raw_json(
+        payload,
+    )))
+}
@@ -0,0 +1,5 @@
+//! Codex standalone search HTTP adapter。
+
+mod http;
+
+pub(crate) use http::standalone_search;
@@ -1,11 +1,12 @@
 //! OpenAI wire adapter 到 Core 执行用例的唯一映射。

+use std::net::IpAddr;
 use std::sync::Arc;

 use gateway_core::engine::continuation::PreviousResponseId;
 use gateway_core::engine::execution::{
    AuthenticatedClient, ClientAuthenticationError, ClientTransport, ExecutionRequestMetadata,
-    ExecutionService, StartExecution, StartedExecution,
+    ExecutionService, StartExecution, StartProviderExecution, StartedExecution,
 };
 use gateway_core::error::{GatewayError, GatewayErrorKind};
 use gateway_core::lifecycle::{ConnectionDraining, ConnectionGuard, ConnectionLifecycle};
@@ -74,13 +75,13 @@ impl OpenAiService {
        endpoint: &'static str,
    ) -> Result<StartedExecution, GatewayError> {
        let (operation, metadata) = request.into_parts();
-        let public_model = PublicModelId::from_client_wire(metadata.public_model().to_owned())
+        let public_model = PublicModelId::from_client_wire(metadata.requested_model().to_owned())
            .map_err(|_| {
-                GatewayError::new(
-                    GatewayErrorKind::ModelNotFound,
-                    "requested model was not found",
-                )
-            })?;
+            GatewayError::new(
+                GatewayErrorKind::ModelNotFound,
+                "requested model was not found",
+            )
+        })?;
        let previous_response_id = match metadata.continuation() {
            ContinuationIntent::None => None,
            ContinuationIntent::PreviousResponseId(value) => {
@@ -105,6 +106,38 @@ impl OpenAiService {
            .await
    }

+    pub(crate) async fn start_provider_endpoint(
+        &self,
+        client: AuthenticatedClient,
+        operation: gateway_core::operation::Operation,
+        client_ip: Option<IpAddr>,
+        user_agent: Option<String>,
+        endpoint: &'static str,
+    ) -> Result<StartedExecution, GatewayError> {
+        let provider = gateway_core::routing::ProviderKind::new("openai").map_err(|_| {
+            GatewayError::new(
+                GatewayErrorKind::Internal,
+                "OpenAI provider identifier is invalid",
+            )
+        })?;
+        self.execution
+            .start_provider_endpoint(StartProviderExecution {
+                client,
+                provider,
+                operation,
+                metadata: ExecutionRequestMetadata {
+                    protocol: "openai".to_owned(),
+                    endpoint: endpoint.to_owned(),
+                    transport: ClientTransport::HttpJson,
+                    stream: false,
+                    client_ip,
+                    user_agent,
+                    previous_response_id: None,
+                },
+            })
+            .await
+    }
+
    pub(crate) fn try_register_connection(
        &self,
    ) -> Result<Box<dyn ConnectionGuard>, ConnectionDraining> {
@@ -40,7 +40,10 @@ async fn list_route_should_keep_camel_case_group_and_page_wire() {
    assert_eq!(value["data"]["items"][0]["capacity"]["usedSlots"], 0);
    assert_eq!(value["data"]["items"][0]["capacity"]["totalSlots"], 1);
    assert_eq!(value["data"]["items"][0]["usage"]["todayUsd"], "1.25");
-    assert_eq!(value["data"]["items"][0]["usage"]["totalUsd"], "5.5");
+    assert_eq!(
+        value["data"]["items"][0]["usage"]["retainedTotalUsd"],
+        "5.5"
+    );
    assert!(value["data"]["items"][0].get("member_count").is_none());
 }

@@ -70,6 +70,140 @@ mod query {
    }
 }

+mod profile_statistics {
+    use chrono::NaiveDate;
+    use gateway_admin::model::provider_credentials::{
+        ProviderProfileActivityInsights, ProviderProfileDailyUsage, ProviderProfileInvocation,
+        ProviderProfileStatistics, ProviderProfileStatisticsSummary,
+    };
+    use gateway_api::admin::accounts::{AccountProfileAvatarQuery, AccountProfileStatisticsData};
+    use serde_json::json;
+
+    #[test]
+    fn profile_statistics_response_preserves_nullable_official_fields() {
+        let response = AccountProfileStatisticsData::from(ProviderProfileStatistics {
+            display_name: Some("Ada".to_owned()),
+            username: Some("ada".to_owned()),
+            image_url: Some("https://example.test/avatar.png".to_owned()),
+            has_stats_error: false,
+            summary: ProviderProfileStatisticsSummary {
+                total_text_tokens: Some(409_500_000),
+                peak_tokens: Some(267_000_000),
+                longest_task_duration_ms: Some(51_900_000),
+                current_streak_days: Some(16),
+                longest_streak_days: Some(32),
+            },
+            daily_usage: Some(vec![ProviderProfileDailyUsage {
+                date: NaiveDate::from_ymd_opt(2026, 8, 25).expect("usage date"),
+                tokens: 42,
+            }]),
+            activity_insights: ProviderProfileActivityInsights {
+                fast_mode_percent: Some(0.0),
+                reasoning_effort: Some("high".to_owned()),
+                reasoning_effort_percent: Some(48.0),
+                skills_explored: Some(8),
+                total_skills_used: Some(61),
+                total_threads: Some(2_391),
+                invocations: Some(vec![ProviderProfileInvocation {
+                    invocation_type: "plugin".to_owned(),
+                    plugin_id: Some("plugin_1".to_owned()),
+                    plugin_name: Some("example".to_owned()),
+                    skill_id: None,
+                    skill_name: None,
+                    usage_count: Some(29),
+                }]),
+            },
+        });
+        let value = serde_json::to_value(response).expect("serialize profile statistics");
+
+        assert_eq!(value["displayName"], "Ada");
+        assert_eq!(value["summary"]["totalTextTokens"], 409_500_000);
+        assert_eq!(
+            value["dailyUsage"][0],
+            json!({"date": "2026-08-25", "tokens": 42})
+        );
+        assert_eq!(
+            value["activityInsights"]["invocations"][0]["type"],
+            "plugin"
+        );
+        assert_eq!(
+            value["activityInsights"]["invocations"][0]["usageCount"],
+            29
+        );
+        assert!(value.get("cycle").is_none());
+        assert!(value.get("models").is_none());
+        assert!(value.get("estimatedCost").is_none());
+    }
+
+    #[test]
+    fn profile_avatar_query_accepts_only_bounded_cache_versions() {
+        let valid: AccountProfileAvatarQuery = serde_json::from_value(json!({
+            "accountId": "acct_openai",
+            "version": "k9m2z1"
+        }))
+        .expect("decode avatar query");
+        valid.validate().expect("validate avatar query");
+
+        for version in ["", "contains-dash", "x23456789012345678901234567890123"] {
+            let query: AccountProfileAvatarQuery = serde_json::from_value(json!({
+                "accountId": "acct_openai",
+                "version": version
+            }))
+            .expect("decode invalid avatar query");
+            assert_eq!(
+                query.validate().expect_err("reject version").field(),
+                "version"
+            );
+        }
+        assert!(
+            serde_json::from_value::<AccountProfileAvatarQuery>(json!({
+                "accountId": "acct_openai",
+                "sourceUrl": "https://example.test/avatar"
+            }))
+            .is_err()
+        );
+    }
+}
+
+mod profile_avatar {
+    use axum::body::to_bytes;
+    use bytes::Bytes;
+    use futures::stream;
+    use gateway_admin::model::provider_credentials::ProviderProfileAvatar;
+    use gateway_api::admin::accounts::profile_avatar_response;
+
+    #[tokio::test]
+    async fn profile_avatar_response_preserves_stream_metadata_and_private_cache() {
+        let response = profile_avatar_response(ProviderProfileAvatar {
+            content_type: Some("image/svg+xml".to_owned()),
+            content_length: Some(6),
+            etag: Some("\"v1\"".to_owned()),
+            body: Box::pin(stream::iter([Ok(Bytes::from_static(b"avatar"))])),
+        });
+
+        assert_eq!(response.status(), 200);
+        assert_eq!(response.headers()["content-type"], "image/svg+xml");
+        assert_eq!(response.headers()["content-length"], "6");
+        assert_eq!(response.headers()["etag"], "\"v1\"");
+        assert_eq!(response.headers()["cache-control"], "private, max-age=3600");
+        assert_eq!(response.headers()["x-content-type-options"], "nosniff");
+        assert_eq!(
+            response.headers()["cross-origin-resource-policy"],
+            "same-origin"
+        );
+        assert_eq!(
+            response.headers()["content-security-policy"],
+            "sandbox; default-src 'none'"
+        );
+        assert_eq!(
+            to_bytes(response.into_body(), 16)
+                .await
+                .expect("avatar response body"),
+            Bytes::from_static(b"avatar")
+        );
+    }
+}
+
 mod batch_update {
    use gateway_api::admin::accounts::{BatchUpdateAccountsRequest, UpdateAccountRequest};
    use serde_json::json;
@@ -214,6 +348,8 @@ mod response {
            output_tokens_display: "-".to_owned(),
            cached_tokens: None,
            cached_tokens_display: "-".to_owned(),
+            reasoning_tokens: None,
+            reasoning_tokens_display: "-".to_owned(),
            image_input_tokens: None,
            image_input_tokens_display: "-".to_owned(),
            image_output_tokens: None,
@@ -240,6 +376,8 @@ mod response {
        let value = serde_json::to_value(view).expect("serialize account usage");
        assert!(value["inputTokens"].is_null());
        assert!(value["totalTokens"].is_null());
+        assert!(value["reasoningTokens"].is_null());
+        assert_eq!(value["reasoningTokensDisplay"], "-");
        assert_eq!(value["createdTokensDisplay"], "-");
    }

@@ -266,10 +404,13 @@ mod actions {
        AccountActionRequest, AccountConnectionTestEvent, AccountDeletionData,
        AccountDeletionRequest, AccountExportData, AccountExportQuery, AccountIdQuery,
        AccountImportData, AccountImportRequest, AccountMutationData, AccountRefreshRequest,
-        AccountTestQuery, CompleteAccountAuthorizationRequest, RotateAccountRequest,
-        StartAccountAuthorizationRequest,
+        AccountResetCreditConsumeRequest, AccountTestQuery, CompleteAccountAuthorizationRequest,
+        RotateAccountRequest, StartAccountAuthorizationRequest,
+    };
+    use gateway_core::{
+        account::ProviderAccountId, engine::probe::AccountProbeErrorSource,
+        error::GatewayErrorKind, upstream::UpstreamSendState,
    };
-    use gateway_core::engine::credential::ProviderAccountId;
    use serde_json::json;

    #[test]
@@ -325,6 +466,44 @@ mod actions {
        );
    }

+    #[test]
+    fn reset_credit_consume_should_require_canonical_v4_idempotency_key() {
+        let valid: AccountResetCreditConsumeRequest = serde_json::from_value(json!({
+            "accountId": "acct_1",
+            "creditId": "credit_1",
+            "redeemRequestId": "8fbf302d-11df-4bd5-82e4-08e4b3df7874"
+        }))
+        .expect("decode reset-credit consume");
+        valid.validate().expect("validate reset-credit consume");
+
+        for (redeem_request_id, field) in [
+            ("019c0000-0000-7000-8000-000000000000", "redeemRequestId"),
+            ("8FBF302D-11DF-4BD5-82E4-08E4B3DF7874", "redeemRequestId"),
+            ("invalid", "redeemRequestId"),
+        ] {
+            let request: AccountResetCreditConsumeRequest = serde_json::from_value(json!({
+                "accountId": "acct_1",
+                "redeemRequestId": redeem_request_id
+            }))
+            .expect("decode invalid reset-credit consume");
+            assert_eq!(request.validate().expect_err("reject UUID").field(), field);
+        }
+
+        let invalid_credit: AccountResetCreditConsumeRequest = serde_json::from_value(json!({
+            "accountId": "acct_1",
+            "creditId": " ",
+            "redeemRequestId": "8fbf302d-11df-4bd5-82e4-08e4b3df7874"
+        }))
+        .expect("decode invalid credit");
+        assert_eq!(
+            invalid_credit
+                .validate()
+                .expect_err("reject credit")
+                .field(),
+            "creditId"
+        );
+    }
+
    #[test]
    fn credential_recovery_requests_should_not_accept_client_revision_fences() {
        let authorization: StartAccountAuthorizationRequest = serde_json::from_value(json!({
@@ -516,6 +695,9 @@ mod actions {
            },
            DomainConnectionTestEvent::Completed {},
            DomainConnectionTestEvent::Failed {
+                source: AccountProbeErrorSource::Upstream,
+                gateway_error_code: GatewayErrorKind::RateLimited,
+                send_state: Some(UpstreamSendState::Sent),
                message: "upstream unavailable".to_owned(),
                provider_error_code: Some("usage_exhausted".to_owned()),
                provider_error_type: Some("invalid_request_error".to_owned()),
@@ -549,6 +731,9 @@ mod actions {
                json!({ "type": "test_complete", "success": true }),
                json!({
                    "type": "error",
+                    "source": "upstream",
+                    "gatewayErrorCode": "rate_limited",
+                    "sendState": "sent",
                    "error": "upstream unavailable",
                    "providerErrorCode": "usage_exhausted",
                    "providerErrorType": "invalid_request_error",
--- a/Show More
+++ b/Show More