dsh-codex-community 0.0.1 → 0.0.2

package/dist/internal/codex-pi-provider.mjs

@@ -6,8 +6,14 @@ import { buildBaseOptions } from "@earendil-works/pi-ai/api/simple-options"
 import { stream as streamCodexResponses } from "@earendil-works/pi-ai/api/openai-codex-responses"
 import { openaiCodexProvider } from "@earendil-works/pi-ai/providers/openai-codex"
 
+import {
+  piThinkingLevelMap,
+  supportsCodexFast,
+} from "./codex-model-capabilities.mjs"
 import { codexTransportSessionId } from "./codex-session-resources.mjs"
 
+export { supportsCodexFast } from "./codex-model-capabilities.mjs"
+
 const FACTORY_OPTION_KEYS = new Set([
   "resolveSessionPreferences",
   "resolveTransportSessionId",
@@ -72,7 +78,24 @@ function resolveSessionPreferenceOptions(resolver, sessionId) {
 function reasoningOptions(model, reasoning) {
   if (reasoning === undefined) return {}
   const effort = clampThinkingLevel(model, reasoning)
-  return effort === "off" ? {} : { reasoningEffort: effort }
+  return { reasoningEffort: effort === "off" ? "none" : effort }
+}
+
+function truthfulCodexModel(model) {
+  const thinkingLevelMap = piThinkingLevelMap(model.id)
+  if (thinkingLevelMap === undefined) {
+    return Object.freeze({
+      ...model,
+      // A newly published model stays usable with the provider default, but
+      // gains no selector controls until its catalog capabilities are verified.
+      reasoning: false,
+      thinkingLevelMap: undefined,
+    })
+  }
+  return Object.freeze({
+    ...model,
+    thinkingLevelMap,
+  })
 }
 
 /**
@@ -84,6 +107,7 @@ function reasoningOptions(model, reasoning) {
 export function createCodexPiProvider(options = {}) {
   validateFactoryOptions(options)
   const source = openaiCodexProvider()
+  const models = source.getModels().map(truthfulCodexModel)
   const resolveSessionPreferences = options.resolveSessionPreferences
   const resolveTransportSessionId = options.resolveTransportSessionId
     ?? codexTransportSessionId
@@ -94,7 +118,7 @@ export function createCodexPiProvider(options = {}) {
     baseUrl: source.baseUrl,
     headers: source.headers,
     auth: source.auth,
-    models: source.getModels(),
+    models,
     ...(source.filterModels === undefined
       ? {}
       : {
@@ -109,11 +133,14 @@ export function createCodexPiProvider(options = {}) {
               resolveSessionPreferences,
               streamOptions.sessionId,
             )
-        const serviceTier = sessionPreferences === undefined
+        const requestedServiceTier = sessionPreferences === undefined
           ? options.serviceTier
           : sessionPreferences.fast
             ? "priority"
             : undefined
+        const serviceTier = requestedServiceTier !== undefined && supportsCodexFast(model.id)
+          ? requestedServiceTier
+          : undefined
         const transportSessionId = resolveTransportSessionId(streamOptions.sessionId)
         if (
           transportSessionId !== undefined

package/dist/internal/codex-provider-runtime.mjs

@@ -1,5 +1,6 @@
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai"
 import { resolveRetryPolicy } from "@deepseek-ai/dsh-llm"
+import { createModels } from "@earendil-works/pi-ai"
 import {
   installSettingsSection,
   settingsNamespace,
@@ -7,6 +8,7 @@ import {
 import Schema from "@deepseek-ai/schemastery"
 
 import { registerCodexAuthorizationFlow } from "./codex-authorization.mjs"
+import { createCodexAccountUsageReader } from "./codex-account-usage.mjs"
 import {
   CODEX_PROVIDER_ID,
   createCodexCredentialStore,
@@ -141,6 +143,27 @@ export function installCodexProviderRuntime(ctx, entryConfig = {}, options = {})
     env: async () => undefined,
     fileExists: async () => false,
   })
+  const authModels = createModels({ credentials: credentialStore, authContext })
+  authModels.setProvider(provider)
+  const accountUsageReader = createCodexAccountUsageReader({
+    baseUrl: provider.baseUrl,
+    ...(options.accountUsageFetch === undefined ? {} : { fetch: options.accountUsageFetch }),
+    ...(options.accountUsageClock === undefined ? {} : { clock: options.accountUsageClock }),
+    resolveAuth: async ({ signal }) => {
+      if (signal.aborted) throw signal.reason
+      const resolved = await authModels.getAuth(provider.id)
+      if (signal.aborted) throw signal.reason
+      const credential = await credentialStore.read(provider.id)
+      if (
+        resolved?.auth?.apiKey === undefined
+        || credential?.type !== "oauth"
+        || resolved.auth.apiKey !== credential.access
+      ) {
+        throw new Error("Codex OAuth credential is unavailable")
+      }
+      return { access: credential.access, accountId: credential.accountId }
+    },
+  })
 
   let source = () => entry
   let previousConfig
@@ -211,7 +234,10 @@ export function installCodexProviderRuntime(ctx, entryConfig = {}, options = {})
     },
   })
 
-  return Object.freeze({ getConfig: () => source() })
+  return Object.freeze({
+    accountUsageReader,
+    getConfig: () => source(),
+  })
 }
 
 function configuredModels(configured, catalog) {

package/dist/internal/codex-route-adapter.mjs

@@ -8,6 +8,10 @@ import {
   CODEX_PROVIDER_ID,
   CODEX_ROUTE_ID,
 } from "./codex-identifiers.mjs"
+import {
+  codexModelCapability,
+  supportsCodexReasoningEffort,
+} from "./codex-model-capabilities.mjs"
 
 export { CODEX_ROUTE_ID } from "./codex-identifiers.mjs"
 
@@ -73,10 +77,10 @@ export class CodexRouteAdapter extends LlmAdapter {
 
   async resolveModel(provider, model, signal) {
     this.#assertRoute(provider)
-    return {
+    return externalModelInfo({
       ...await this.delegate.resolveModel(CODEX_PROVIDER_ID, model, signal),
       provider: CODEX_ROUTE_ID,
-    }
+    })
   }
 
   async prepareCall(provider, model, signal) {
@@ -87,7 +91,10 @@ export class CodexRouteAdapter extends LlmAdapter {
       signal,
     )
     return Object.freeze({
-      model: Object.freeze({ ...prepared.model, provider: CODEX_ROUTE_ID }),
+      model: Object.freeze(externalModelInfo({
+        ...prepared.model,
+        provider: CODEX_ROUTE_ID,
+      })),
       stream: (options) => prepared.stream(this.#canonicalOptions(options)),
     })
   }
@@ -98,9 +105,20 @@ export class CodexRouteAdapter extends LlmAdapter {
 
   #canonicalOptions(options) {
     this.#assertRoute(options?.provider)
+    const reasoningEffort = options.reasoningEffort
+    if (
+      reasoningEffort !== undefined
+      && !supportsCodexReasoningEffort(options.model, reasoningEffort)
+    ) {
+      throw new LlmError(
+        `provider "${CODEX_ROUTE_ID}" model "${String(options.model)}" does not support reasoning effort "${String(reasoningEffort)}"`,
+        "UNSUPPORTED_REASONING_EFFORT",
+      )
+    }
     return {
       ...options,
       provider: CODEX_PROVIDER_ID,
+      ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
       messages: options.messages.map(toCanonicalHistoryMessage),
     }
   }
@@ -115,6 +133,21 @@ export class CodexRouteAdapter extends LlmAdapter {
   }
 }
 
+function externalModelInfo(model) {
+  const capability = codexModelCapability(model.id)
+  if (capability === undefined) {
+    const { reasoning: _unverifiedReasoning, ...withoutReasoning } = model
+    return withoutReasoning
+  }
+  return {
+    ...model,
+    reasoning: {
+      efforts: capability.reasoningEfforts,
+      defaultEffort: capability.defaultReasoningEffort,
+    },
+  }
+}
+
 function toCanonicalHistoryMessage(message) {
   if (
     message.role !== "assistant"

package/dist/internal/session-preference-bridge.mjs

@@ -0,0 +1,150 @@
+// Connection channels are one path segment; endpoints are appended by RPC.
+export const SESSION_PREFERENCE_RPC_CHANNEL = "/dsh-codex-session"
+
+const MAX_SESSION_ID_CHARS = 256
+
+class RpcInputError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "RpcInputError"
+  }
+}
+
+/**
+ * Narrow browser bridge for the existing process-local session preferences.
+ * Transport choices and all store internals remain host-only; the client can
+ * read or change only Fast for one explicitly named session.
+ */
+export class CodexSessionPreferenceBridge {
+  #preferences
+
+  constructor(sessionPreferences) {
+    if (
+      sessionPreferences === null
+      || typeof sessionPreferences !== "object"
+      || typeof sessionPreferences.resolve !== "function"
+      || typeof sessionPreferences.configure !== "function"
+    ) {
+      throw new TypeError("sessionPreferences must provide resolve and configure")
+    }
+    this.#preferences = sessionPreferences
+  }
+
+  get(payload, signal) {
+    throwIfCancelled(signal)
+    const input = objectInput(payload)
+    assertOnlyKeys(input, ["sessionId"])
+    const sessionId = requiredSessionId(input)
+    const result = publicFastSnapshot(this.#preferences.resolve(sessionId))
+    throwIfCancelled(signal)
+    return result
+  }
+
+  setFast(payload, signal) {
+    throwIfCancelled(signal)
+    const input = objectInput(payload)
+    assertOnlyKeys(input, ["sessionId", "fast"])
+    const sessionId = requiredSessionId(input)
+    if (!Object.hasOwn(input, "fast") || typeof input.fast !== "boolean") {
+      throw new RpcInputError("fast must be a boolean")
+    }
+    const result = publicFastSnapshot(this.#preferences.configure(sessionId, { fast: input.fast }))
+    throwIfCancelled(signal)
+    return result
+  }
+
+  dispatch(endpoint, payload, signal) {
+    switch (endpoint) {
+      case "get": return this.get(payload, signal)
+      case "set-fast": return this.setFast(payload, signal)
+      default: throw new RpcInputError("Unknown session preference RPC endpoint")
+    }
+  }
+}
+
+/** Register the session-only Fast surface on a dedicated loopback channel. */
+export function registerSessionPreferenceRpc(ctx, sessionPreferences) {
+  const bridge = new CodexSessionPreferenceBridge(sessionPreferences)
+  ctx.connection.rpc.handle(
+    SESSION_PREFERENCE_RPC_CHANNEL,
+    createSessionPreferenceRpcHandler(bridge),
+    { authority: "loopback" },
+  )
+  return bridge
+}
+
+/** Convert bridge failures into the bounded browser RPC result envelope. */
+export function createSessionPreferenceRpcHandler(bridge) {
+  if (bridge === null || typeof bridge !== "object" || typeof bridge.dispatch !== "function") {
+    throw new TypeError("bridge must provide dispatch")
+  }
+  return async (endpoint, payload, signal) => {
+    if (signal?.aborted === true) return cancelledResult()
+    try {
+      const value = await bridge.dispatch(endpoint, payload, signal)
+      if (signal?.aborted === true) return cancelledResult()
+      return { ok: true, value }
+    } catch (error) {
+      if (signal?.aborted === true) return cancelledResult()
+      if (error instanceof RpcInputError) {
+        return {
+          ok: false,
+          error: { code: "bad-request", message: error.message, details: { issues: [] } },
+        }
+      }
+      return {
+        ok: false,
+        error: { code: "internal", message: "Session preference request failed", details: {} },
+      }
+    }
+  }
+}
+
+function publicFastSnapshot(value) {
+  if (value === null || typeof value !== "object" || typeof value.fast !== "boolean") {
+    throw new TypeError("session preference store returned an invalid snapshot")
+  }
+  return { fast: value.fast }
+}
+
+function objectInput(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new RpcInputError("RPC payload must be an object")
+  }
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new RpcInputError("RPC payload must be a plain object")
+  }
+  return value
+}
+
+function assertOnlyKeys(value, allowed) {
+  const accepted = new Set(allowed)
+  if (Object.keys(value).some((key) => !accepted.has(key))) {
+    throw new RpcInputError("RPC payload contains an unknown field")
+  }
+}
+
+function requiredSessionId(value) {
+  const sessionId = value.sessionId
+  if (
+    !Object.hasOwn(value, "sessionId")
+    || typeof sessionId !== "string"
+    || sessionId.length < 1
+    || sessionId.length > MAX_SESSION_ID_CHARS
+  ) {
+    throw new RpcInputError(`sessionId must contain 1 to ${MAX_SESSION_ID_CHARS} characters`)
+  }
+  return sessionId
+}
+
+function throwIfCancelled(signal) {
+  if (signal?.aborted === true) throw new Error("request cancelled")
+}
+
+function cancelledResult() {
+  return {
+    ok: false,
+    error: { code: "cancelled", message: "Request cancelled", details: {} },
+  }
+}

package/docs/architecture.en.md

@@ -8,16 +8,17 @@ This plugin registers the Codex route, settings namespace, OAuth flow, session p
 
 ```text
 DSH Web settings ── loopback RPC ── AuthorizationBridge
-                                           │
-                              dsh-codex/openai-codex
-                                           │
-                              CodexCredentialStore
-                                           │
-                                  ChatGPT OAuth grant
+        │                                  │
+        │ page entry / manual refresh      │
+        ▼                                  ▼
+AccountUsageReader ─────────────── CodexCredentialStore
+        │                                  │
+        ▼                                  ▼
+Codex Web usage endpoint           ChatGPT OAuth grant
 
 Harness Agent Loop
         │
-        ├── SessionPreferences ── Fast / transport
+        ├── SessionPreferences ── lightning button, Fast / transport
         │
         ▼
 StreamResilience ── CodexRouteAdapter (`dsh-codex`)
@@ -48,15 +49,21 @@ The Host starts, cancels, and observes sign-in through the DSH authorization ser
 
 `/codex-login status|cancel|logout` uses the same boundary and prevents command input from entering conversation history.
 
+## AccountUsageReader
+
+Whenever the settings page mounts or the user clicks Refresh, the Host-side `AccountUsageReader` uses the current OAuth grant to request the Web-backend usage compatibility endpoint used by the official Codex client. It strictly parses used percentages, window durations, and reset times, then converts the five-hour and weekly windows into a minimal credential-free snapshot. Access tokens, refresh tokens, account IDs, raw responses, and arbitrary response headers never cross the loopback RPC.
+
+This endpoint is treated as a Web-backend compatibility boundary, not as a stable plugin public API. Requests have timeout, response-size, and numeric-range limits. A network failure, authentication failure, or schema change is never rendered as zero remaining usage and does not erase the latest verified reading. When no live reading can be retained, the page safely falls back to recent-request `QuotaObserver` state or “unknown” instead of inferring usage.
+
 ## SessionPreferences
 
-`/codex` changes only the session that receives the command:
+The lightning button to the left of the model selector and `/codex` update the same current-session state:
 
-- `fast on|off` controls whether the priority service tier is requested and defaults to off;
+- the lightning button or `fast on|off` controls whether the Fast priority service tier is requested and defaults to off;
 - `transport` accepts `auto`, `sse`, `websocket`, or `websocket-cached` and defaults to `auto`;
 - `reset` restores that session's defaults.
 
-Preferences live in a capacity-bounded in-memory table that returns immutable snapshots; they do not change global provider settings. A failed Fast request is not replayed automatically on another service tier, avoiding duplicate tool side effects. Real account entitlement for this tier must be confirmed by release acceptance.
+Preferences live in a capacity-bounded in-memory table that returns immutable snapshots; they do not change global provider settings and return to their defaults after a process restart. Fast applies only to GPT-5.4, GPT-5.5, GPT-5.6 Luna, Sol, and Terra, using the official priority service tier to target 1.5× speed while consuming more usage. Other models never carry that tier. A toggle affects the next request, not one already in flight. A failed Fast request is not replayed automatically on another service tier, avoiding duplicate tool side effects.
 
 The raw DSH session ID is used only for preference lookup and message/replay provenance. The transport/cache session ID passed to pi-ai is namespaced with `dsh-codex:`. `/codex reset`, `agent/disposed`, and runtime disposal use pi-ai's public exact-session APIs to clear only this plugin's WebSocket connection, fallback, and debug state. They never invoke no-argument global cleanup and do not affect sessions owned by another in-process pi-ai consumer. The namespace enters only pi-ai stream options; it does not rewrite history messages or replay envelopes.
 
@@ -66,6 +73,8 @@ This plugin's settings page uses `llm.discoverModels` to display requestable mod
 
 The settings page requires at least one selected model. Selecting all removes the `models` override only when entries have no custom fields, allowing the directory to follow pi-ai version updates. Partial selections, extra fields, and custom parameters retain explicit configuration. Catalog filtering affects discovery only; exact hidden models remain resolvable, so older sessions are not invalidated merely because a model is hidden.
 
+Model names, context windows, and input capabilities come from the installed provider catalog and are not presented as a dynamic account directory. `CodexRouteAdapter` projects reasoning controls from the verified subscription-Codex model catalog: it removes generic `Default`, `Off`, and `Minimal` entries, supplies each model's default, and exposes only Low through Max, which the Provider request layer can represent truthfully. Codex `Ultra` combines the highest plain reasoning level with proactive task delegation and is therefore an Agent orchestration mode. This plugin neither sends a fabricated `ultra` wire value nor silently degrades it to `Max`. Unknown models receive no inferred controls, and the route boundary rejects direct injection of an unverified effort.
+
 ## ImagePolicy
 
 Optional settings resolve to one immutable policy with no optional numeric fields. The attachment contract receives only `{ maxPixels, maxBytes }`. Zero, negative, fractional, `NaN`, and unsafe integers fail at the configuration boundary.
@@ -80,7 +89,7 @@ Each plugin instance runs at most two remote-image jobs and queues at most 32; a
 
 `QUOTA`, `QUOTA_OR_RATE_LIMIT`, and confirmed transport failures are rebuilt as minimal failures containing a fixed sanitized message, code, and optional valid HTTP status/safe-character request ID. Arbitrary provider fields and WebSocket close reasons are never reflected. `QUOTA_OR_RATE_LIMIT` is not written to `QuotaObserver`: it fails without retry when no partial output exists and only preserves already safe plain text when partial output exists.
 
-`QuotaObserver` records only successful completion, `QUOTA`, and a reset timestamp accepted by strict format and bounded-horizon checks. Snapshots have three states: `unknown`, `recent-success`, and `exhausted`. It does not poll an account, display a balance or percentage, or call undocumented plan-quota endpoints.
+`QuotaObserver` records only successful completion, `QUOTA`, and a reset timestamp accepted by strict format and bounded-horizon checks. Snapshots have three states: `unknown`, `recent-success`, and `exhausted`. It neither polls an account nor displays a balance or percentage. Instead, it is the request-observation fallback when `AccountUsageReader` has no usable live snapshot; the two evidence types never masquerade as each other.
 
 ## StreamResilience
 

package/docs/architecture.md

@@ -8,16 +8,17 @@
 
 ```text
 DSH Web 设置 ── loopback RPC ── AuthorizationBridge
-                                      │
-                         dsh-codex/openai-codex
-                                      │
-                         CodexCredentialStore
-                                      │
-                             ChatGPT OAuth grant
+        │                             │
+        │ 进入页面 / 手动刷新          │
+        ▼                             ▼
+AccountUsageReader ────────── CodexCredentialStore
+        │                             │
+        ▼                             ▼
+Codex Web usage endpoint      ChatGPT OAuth grant
 
 Harness Agent Loop
         │
-        ├── SessionPreferences ── Fast / transport
+        ├── SessionPreferences ── 闪电按钮、Fast / transport
         │
         ▼
 StreamResilience ── CodexRouteAdapter (`dsh-codex`)
@@ -48,15 +49,21 @@ Host 端通过 DSH authorization service 启动、取消和观察登录流程，
 
 `/codex-login status|cancel|logout` 使用同一边界，并禁止把命令输入写入会话记录。
 
+## AccountUsageReader
+
+设置页每次挂载以及用户点击“刷新”时，Host 端 `AccountUsageReader` 使用当前 OAuth grant 请求官方 Codex 客户端使用的 Web 后端 usage 兼容接口。它严格解析使用百分比、窗口时长和 reset 时间，并把五小时与每周窗口转换为不含凭据的最小快照；access token、refresh token、account ID、原始响应和任意响应头都不会跨过 loopback RPC。
+
+该接口是 Web 后端兼容边界，不被当作稳定的插件公共 API。请求具有超时、响应大小和数值范围限制；网络失败、鉴权失败或结构变化不会被显示成零余额，也不会清除最近一次已验证读数。若没有可保留的实时读数，页面会安全降级为最近请求产生的 `QuotaObserver` 状态或“未知”，而不是推断额度。
+
 ## SessionPreferences
 
-`/codex` 只修改接收命令的当前会话：
+模型选择器左侧的闪电按钮和 `/codex` 修改同一份当前会话状态：
 
-- `fast on|off` 控制是否发送 priority service tier，默认关闭；
+- 闪电按钮或 `fast on|off` 控制是否发送 Fast priority service tier，默认关闭；
 - `transport` 可选 `auto`、`sse`、`websocket` 或 `websocket-cached`，默认 `auto`；
 - `reset` 恢复当前会话默认值。
 
-偏好保存在有容量上限的内存表中，返回不可变快照，不写入全局 provider 设置。Fast 请求失败后不会自动以另一 service tier 重放，避免重复工具副作用。真实账号是否允许该 tier 必须通过发布验收确认。
+偏好保存在有容量上限的内存表中，返回不可变快照，不写入全局 provider 设置，进程重启后恢复默认。Fast 只对 GPT-5.4、GPT-5.5、GPT-5.6 Luna、Sol 和 Terra 请求生效，使用官方 priority service tier，目标速度为 1.5 倍并消耗更多额度；其他模型不会携带该 tier。切换只影响下一次请求，已经开始的请求不变。Fast 请求失败后不会自动以另一 service tier 重放，避免重复工具副作用。
 
 DSH 原始 session ID 只用于偏好查询和消息/replay provenance；传给 pi-ai 的 transport/cache session ID 带有 `dsh-codex:` 命名空间。`/codex reset`、`agent/disposed` 和 runtime dispose 只通过 pi-ai 的公开、精确 session API 清理本插件拥有的 WebSocket 连接、fallback 与 debug 状态，不调用无参全局清理，也不影响同进程其他 pi-ai consumer 的 session。该命名空间只进入 pi-ai stream options，不改写历史消息或 replay envelope。
 
@@ -66,6 +73,8 @@ DSH 原始 session ID 只用于偏好查询和消息/replay provenance；传给
 
 设置页至少要求选中一个模型。全选且条目没有自定义字段时移除 `models` 覆盖，使目录随 pi-ai 版本更新；部分选择、额外字段和自定义参数保留显式配置。目录筛选只影响模型发现，精确指定的隐藏模型仍可解析，因此旧会话不会仅因模型被隐藏而失效。
 
+模型名称、上下文窗口与输入能力来自当前安装的 provider catalog，不声称是账号动态目录。推理选择器由 `CodexRouteAdapter` 按已核验的订阅 Codex 模型目录重新投影：删除通用 `Default`、`Off` 与 `Minimal`，写入逐模型默认值，并只暴露可以由 Provider 请求层诚实表达的 Low 至 Max。Codex 的 `Ultra` 同时代表最高普通推理与主动任务委派，属于 Agent 编排模式；本插件不会只发送一个伪造的 `ultra` 值，也不会静默退化成 `Max`。未知模型不获得推断能力，route 边界也拒绝直接注入未核验档位。
+
 ## ImagePolicy
 
 可选配置会解析为不可变、没有 optional 数字的完整策略。attachment contract 只收到 `{ maxPixels, maxBytes }`。零、负数、浮点、`NaN` 和超安全整数会在配置边界被拒绝。
@@ -80,7 +89,7 @@ DSH 原始 session ID 只用于偏好查询和消息/replay provenance；传给
 
 `QUOTA`、`QUOTA_OR_RATE_LIMIT` 和已确认 transport 的输出均重新构造为最小 failure，只保留固定脱敏消息、code，以及可选的有效 HTTP status/受限字符集 request ID；不回显任意 provider 字段或 WebSocket close reason。`QUOTA_OR_RATE_LIMIT` 不写入 `QuotaObserver`：无 partial 输出时直接失败且不重试，已有安全纯文本时只保存 partial。
 
-`QuotaObserver` 只记录成功终止、`QUOTA` 和通过严格格式及有限时距校验的 reset timestamp。快照只有 `unknown`、`recent-success` 和 `exhausted` 三态。它不轮询账户、不展示余额或百分比，也不调用未公开的套餐额度接口。
+`QuotaObserver` 只记录成功终止、`QUOTA` 和通过严格格式及有限时距校验的 reset timestamp。快照只有 `unknown`、`recent-success` 和 `exhausted` 三态。它不轮询账户，也不展示余额或百分比；它作为 `AccountUsageReader` 无可用实时快照时的请求观测降级，两类证据不会互相伪装。
 
 ## StreamResilience
 

package/docs/compatibility.en.md

@@ -4,29 +4,30 @@
 
 Last updated: 2026-08-29.
 
-| Component or environment | `0.0.1` evidence | Status |
+| Component or environment | `0.0.2` evidence | Status |
 | --- | --- | --- |
 | DeepSeek Harness | `test/fixtures/dsh-runtime/pnpm-lock.yaml` locks the complete `@deepseek-ai/dsh@0.1.1-rc.2` runtime/peer graph and validates the `dsh-llm` schema and stream contract | Exact version verified |
-| pi-ai | OAuth, catalog, Codex payload, and replay contract tests against `@earendil-works/pi-ai@0.82.1` | Public contract verified; real sign-in pending |
-| Node.js | Complete local suite on `22.22.2`; [CI run 33224023141](https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33224023141) covers 22 and 24 on all three operating systems | `>=22.19.0 <25` |
-| macOS arm64 | Local tests, build, attachment seam, and isolated profile startup; `macos-latest` CI passes on Node 22 and 24 | Local and CI automation verified |
-| Windows x64 | `windows-latest` CI on Node 22 and 24 completes the frozen DSH install, the full check suite, release-draft verification, exact-candidate install, and disposable Web/profile startup | CI automation verified; real user environment pending |
-| Linux x64 | `ubuntu-latest` CI on Node 22 and 24 completes the same checks and Web/profile smoke | CI automation verified |
+| pi-ai | OAuth, catalog, Codex payload, and replay contract tests against `@earendil-works/pi-ai@0.82.1` | Public contract verified; 0.0.2 live-network acceptance is `0/13 pending` |
+| Node.js | Complete local suite on `22.22.2`; the [0.0.2 three-platform candidate run](https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33243698807) covers Node 22/24 | `>=22.19.0 <25`; candidate run passed |
+| macOS | `macos-latest` Node 22/24 complete checks, frozen DSH installation, and Web/profile smoke | Platform gate passed |
+| Windows x64 | `windows-latest` Node 22/24 complete checks, frozen DSH installation, and Web/profile smoke | Platform gate passed; real user environment pending |
+| Linux x64 | `ubuntu-latest` Node 22/24 complete checks, frozen DSH installation, and Web/profile smoke | Platform gate passed |
 | Real ChatGPT OAuth login | Automation does not read or modify a user's real grant | Controlled acceptance pending |
+| Codex usage windows | Opening the settings page and refreshing manually both make the Host actively read and strictly parse the real five-hour and weekly limits; both windows were verified in the local DSH settings page | Verified; a failure retains the latest safe reading or falls back to request observation/an unknown state |
 | Real Codex conversation | Automation does not consume user account quota | Controlled acceptance pending |
 | Text / reasoning / usage / tools / replay | Public PiAiAdapter success, tool-call, and two-turn replay automation passes | Live reasoning, tool round trip, and conversation continuity are pending |
 | Codex image input | Attachment-seam and budget-projection automation passes | A live request with `maxPixels=4194304` is pending |
 | auto / SSE / WebSocket / cached | Transport mapping and session isolation pass in automation | One live request through each transport is pending |
 | Fast / priority tier | Verified that only an explicit per-session choice changes `service_tier` | Account entitlement and live network pending |
-| npm / GitHub Release | The strict workflow verifies the candidate, Registry readback, and Release assets | `0.0.1` uses npm `latest` and a full GitHub Release |
+| npm / GitHub Release | The strict workflow verifies the candidate, Registry readback, provenance, signatures, and Release assets; artifacts are attached to [`v0.0.2`](https://github.com/yoshino-xiao7/dsh-codex/releases/tag/v0.0.2) | Formal publication is performed by the protected workflow |
 
-The `0.0.x` line is a technical preview and declares compatibility only with the exact DSH release candidate above. Before `0.0.1` is formally published, Linux, macOS, and Windows CI/profile smoke must reach `3/3`, supply-chain verification must be complete, and a maintainer must approve the release. The real OAuth, conversation, image, transport, and Fast rows may remain at `0/13` when the formal release is published; post-release validation completes them one by one afterward. Incomplete checks must remain visible and must never be presented as verified capabilities; findings are fixed and iterated in `0.0.2`.
+The `0.0.x` line is a technical preview and declares compatibility only with the exact DSH release candidate above. Linux, macOS, and Windows CI/profile smoke for `0.0.2` reached `3/3`; the accepted commit, exact Node versions, and job links are recorded in the [acceptance record](releases/v0.0.2.acceptance.json), with maintainer approval. Live OAuth, conversation, image, transport, and Fast network acceptance remains `0/13 pending` for post-release validation and will be completed individually after publication. These incomplete checks must remain visible and must never be presented as verified capabilities. Reading the usage windows was verified independently in the local settings page and is not one of these 13 checks that consume a model request or require a complete interaction round trip.
 
 The root `pnpm-lock.yaml` locks plugin dependencies, while `test/fixtures/dsh-runtime/pnpm-lock.yaml` independently locks the complete DSH runtime and peer graph used by compatibility smoke. CI runs `pnpm --dir test/fixtures/dsh-runtime install --frozen-lockfile --ignore-scripts` instead of handing that peer graph to direct npm resolution, avoiding nondeterministic dependency results and uncontrolled memory use. This frozen layer verifies Web/profile integration; it does not claim coverage of native terminal or native-build capabilities in DSH dependencies that require lifecycle scripts. Dependency upgrades must use a pinned-version PR, update and review both lockfiles, repeat complete CI, profile smoke, and supply-chain verification before publication, and renew controlled live validation afterward. The scheduled compatibility workflow only verifies the current locked graph and reports Registry drift; neither a broad semver range nor one scheduled run proves cross-RC compatibility.
 
 ## Profile composition
 
-The `0.0.1` bundle does not modify the general `llm-pi-ai` Cordis row. It adds:
+The `0.0.2` bundle does not modify the general `llm-pi-ai` Cordis row. It provides:
 
 - the `dsh-codex` route;
 - the `dsh-codex` settings namespace;
@@ -45,9 +46,9 @@ Fast and transport preferences set by `/codex` exist only for the current proces
 ## Credentials and capability boundaries
 
 - The Codex route accepts ChatGPT OAuth only and does not read an OpenAI Platform API key.
-- Cancel sign-in through the plugin settings page or `/codex-login cancel`: cancellation succeeds before write linearization, while an in-progress commit is reported as too late and remains observed through its final state; `logout` always deletes the credential. The current DSH public seam has no post-commit cancellation barrier, so third-party code that calls `ctx.authorization.cancel()` directly bypasses this coordination and is not a supported `0.0.1` interaction path.
+- Cancel sign-in through the plugin settings page or `/codex-login cancel`: cancellation succeeds before write linearization, while an in-progress commit is reported as too late and remains observed through its final state; `logout` always deletes the credential. The current DSH public seam has no post-commit cancellation barrier, so third-party code that calls `ctx.authorization.cancel()` directly bypasses this coordination and is not a supported `0.0.2` interaction path.
 - When a plugin or hot-reload flow owner is disposed, sign-in is cancelled before commit selection, while a selected credential commit is allowed to reach its final write before disposal completes. An unsupported or malformed stored record is shown as `invalid`, requires signing in again or signing out to clear it, and is never presented as signed in.
-- The quota card shows recent request-derived observations, not a live balance, percentage, or proactive account query.
+- The usage card actively reads the real five-hour and weekly limits when the settings page opens and when the user refreshes it manually. The Host returns only strictly parsed windows, percentages, and reset times to the Web page, never OAuth credentials or raw responses. If the endpoint is unavailable or malformed, the latest safe reading is retained and the card falls back to request observation or an unknown state rather than presenting the failure as zero remaining usage.
 - DSH Web search uses its own provider and credentials; it does not reuse ChatGPT OAuth.
-- `0.0.1` does not provide image generation or editing.
+- `0.0.2` does not provide image generation or editing.
 - Session compaction continues to use DSH's built-in automatic compaction and `/compact`.

package/docs/compatibility.md

@@ -4,29 +4,30 @@
 
 最近更新：2026-08-29。
 
-| 组件或环境 | `0.0.1` 证据 | 状态 |
+| 组件或环境 | `0.0.2` 证据 | 状态 |
 | --- | --- | --- |
 | DeepSeek Harness | `test/fixtures/dsh-runtime/pnpm-lock.yaml` 锁定完整 `@deepseek-ai/dsh@0.1.1-rc.2` runtime/peer 图，并验证 `dsh-llm` schema 与 stream contract | 精确版本已验证 |
-| pi-ai | `@earendil-works/pi-ai@0.82.1` 的 OAuth、模型目录、Codex payload 与 replay 合同测试 | 公开合同已验证；真实登录待验收 |
-| Node.js | 本地 `22.22.2` 完整测试；[CI 运行 33224023141](https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33224023141) 在三种系统上覆盖 22 与 24 | `>=22.19.0 <25` |
-| macOS arm64 | 本地测试、构建、attachment seam 与隔离 profile 启动；`macos-latest` 的 Node 22/24 CI 通过 | 本地与 CI 自动化已验证 |
-| Windows x64 | `windows-latest` 的 Node 22/24 CI 完成冻结 DSH 安装、完整检查套件、发布草案校验、精确候选包安装与一次性 Web/profile 启动 | CI 自动化已验证；真实用户环境待验收 |
-| Linux x64 | `ubuntu-latest` 的 Node 22/24 CI 完成同一组检查与 Web/profile smoke | CI 自动化已验证 |
+| pi-ai | `@earendil-works/pi-ai@0.82.1` 的 OAuth、模型目录、Codex payload 与 replay 合同测试 | 公开合同已验证；0.0.2 真实网络验收 `0/13 pending` |
+| Node.js | 本地 `22.22.2` 完整测试；[0.0.2 三平台候选运行](https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33243698807)覆盖 Node 22/24 | `>=22.19.0 <25`；候选运行通过 |
+| macOS | `macos-latest` Node 22/24 完整检查、冻结 DSH 安装与 Web/profile smoke | 平台门禁通过 |
+| Windows x64 | `windows-latest` Node 22/24 完整检查、冻结 DSH 安装与 Web/profile smoke | 平台门禁通过；真实用户环境待验收 |
+| Linux x64 | `ubuntu-latest` Node 22/24 完整检查、冻结 DSH 安装与 Web/profile smoke | 平台门禁通过 |
 | ChatGPT OAuth 真实登录 | 自动化不读取或修改用户真实 grant | 受控验收待完成 |
+| Codex 额度窗口 | 进入设置页和手动刷新都会通过 Host 主动读取并严格解析真实五小时与每周额度；本机 DSH 设置页已验证两种额度窗口 | 已验证；读取失败时保留最近安全读数或降级为请求观测/未知状态 |
 | Codex 真实网络对话 | 自动化不消耗用户账户配额 | 受控验收待完成 |
 | 文本 / reasoning / usage / 工具 / replay | 公开 PiAiAdapter 成功流、工具调用和两轮 replay 自动化已通过 | 真实 reasoning、工具闭环与连续对话待验收 |
 | Codex 图片输入 | attachment seam 与预算投影自动化已通过 | `maxPixels=4194304` 真实请求待验收 |
 | auto / SSE / WebSocket / cached | transport 映射与会话隔离自动化已通过 | 四种真实请求待验收 |
 | Fast / priority tier | 已验证仅在当前会话开启时改变 `service_tier` | 账号权限与真实网络待验收 |
-| npm / GitHub Release | 严格工作流校验候选、Registry 回读与 Release 资产 | `0.0.1` 使用 npm `latest` 与正式 GitHub Release |
+| npm / GitHub Release | 严格工作流校验候选、Registry 回读、provenance、签名与 Release 资产；发布制品见 [`v0.0.2`](https://github.com/yoshino-xiao7/dsh-codex/releases/tag/v0.0.2) | 正式发布由受保护工作流完成 |
 
-`0.0.x` 是技术预览，只对表中的精确 DSH 预发布版本声明兼容。`0.0.1` 在正式发布前必须完成 Linux、macOS 和 Windows 三平台 CI/profile smoke `3/3`、完整供应链校验和维护者批准。表中真实 OAuth、对话、图片、transport 和 Fast 状态可在正式发布时保持 `0/13`，并在发布后逐项补齐。这些未完成项必须如实展示，不能冒充已验证能力；发现的问题在 `0.0.2` 中修复和迭代。
+`0.0.x` 是技术预览，只对表中的精确 DSH 预发布版本声明兼容。`0.0.2` 的 Linux、macOS 和 Windows CI/profile smoke 已达到 `3/3`，候选提交、精确 Node 版本与作业链接记录在[验收记录](releases/v0.0.2.acceptance.json)中，并已获得维护者批准。真实 OAuth、对话、图片、transport 和 Fast 网络验收为 `0/13 pending`，正式发布后再逐项补齐；这些未完成项必须如实展示，不能冒充已验证能力。额度窗口读取已独立完成本机设置页验证，不计入这 13 个会消耗模型请求或需要完整交互闭环的验收项。
 
 根目录 `pnpm-lock.yaml` 锁定插件依赖，`test/fixtures/dsh-runtime/pnpm-lock.yaml` 独立锁定兼容性 smoke 的完整 DSH runtime 与 peer 图；CI 使用 `pnpm --dir test/fixtures/dsh-runtime install --frozen-lockfile --ignore-scripts`，不把该 peer 图交给直接 npm 解算，以避免不确定依赖结果和内存失控。该冻结层验证 Web/profile 集成，不声称覆盖 DSH 依赖中需要生命周期脚本的原生终端或本机构建能力。依赖升级必须通过固定版本变更 PR，同时更新并审查两套 lockfile，在发布前重跑完整 CI、profile smoke 和供应链校验，发布后重新记录受控真实验证。定时兼容工作流只验证当前锁定图并报告 Registry 漂移，不能从宽泛 semver 或一次定时运行推断跨 RC 兼容。
 
 ## Profile 组合
 
-`0.0.1` 的 bundle 不修改通用 `llm-pi-ai` Cordis row。它新增：
+`0.0.2` 的 bundle 不修改通用 `llm-pi-ai` Cordis row。它提供：
 
 - `dsh-codex` route；
 - `dsh-codex` 设置命名空间；
@@ -45,9 +46,9 @@
 ## 凭据与功能边界
 
 - Codex route 只接受 ChatGPT OAuth，不读取 OpenAI Platform API key；
-- 请通过插件设置页或 `/codex-login cancel` 取消登录：写入线性化前会正常取消，提交已经开始时会明确提示无法取消并继续等待最终状态；`logout` 始终删除凭据。DSH 当前公共 seam 没有“提交后禁止取消”能力，第三方代码直接调用 `ctx.authorization.cancel()` 会绕过这一协调，不属于 `0.0.1` 支持的交互路径；
+- 请通过插件设置页或 `/codex-login cancel` 取消登录：写入线性化前会正常取消，提交已经开始时会明确提示无法取消并继续等待最终状态；`logout` 始终删除凭据。DSH 当前公共 seam 没有“提交后禁止取消”能力，第三方代码直接调用 `ctx.authorization.cancel()` 会绕过这一协调，不属于 `0.0.2` 支持的交互路径；
 - 插件或热重载 flow owner 卸载时，提交选择前的登录会取消，已经进入凭据提交的登录会等待最终写入再完成卸载；不支持类型或结构损坏的已存记录显示为 `invalid`，需要重新登录或退出清除，不会显示为已登录；
-- 额度卡只显示请求产生的最近观测，不提供实时余额、百分比或主动账户查询；
+- 额度卡会在进入设置页和手动刷新时主动读取真实五小时与每周额度；Host 只向 Web 页面返回严格解析后的窗口、百分比和重置时间，不返回 OAuth 凭据或原始响应。接口不可用或结构异常时保留最近一次安全读数，并降级为请求观测或未知状态，不把失败显示成零余额；
 - DSH 的 Web search 使用它自己的 provider 和凭据，不复用 ChatGPT OAuth；
-- `0.0.1` 不提供图片生成或编辑；
+- `0.0.2` 不提供图片生成或编辑；
 - 会话压缩继续使用 DSH 自带的自动压缩和 `/compact`。