dsh-vertex-argon 1.5.1 → 1.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,31 @@
2
2
 
3
3
  All notable changes to `dsh-vertex-argon` are documented in this file.
4
4
 
5
+ ## [1.5.3] - 2026-10-24
6
+
7
+ ### Fixed
8
+ - **Pre-Checkpoint Real-Time Streaming & Fast-Fail Outer Retry Handoff (`generate-content.js`)**:
9
+ - Streamed incoming `GenerateContent` SSE chunks in real time before the first 32,768-token `continuationToken` checkpoint is acquired (`!token`), eliminating buffering delay on thought summaries, text, and tool calls for `< 32K` turns when `longDecode` is enabled.
10
+ - Surfaced pre-checkpoint stream drops and errors immediately to the DSH outer retry handler on the first hop instead of silently looping 4 internal hops without a checkpoint token, while preserving `pending` checkpoint buffering and internal `continuationToken` resume once a 32K+ checkpoint is active.
11
+ - **Inspector Usage Ledger, Cache Coverage & Hop Accounting (`usage-details.js`, `pricing.js`, `inspector-overview.js`, `client.js`, `generate-content.js`)**:
12
+ - Added `selectGcUsageRows` to strip contiguous unanswered pre-progress `retry-original` hops when a subsequent hop completes, keeping cost and token completeness accurate across historical and multi-hop records.
13
+ - Computed weighted cache-hit percentage across requests with complete valid cache/input counts and recorded `hopTracker.onChunk({ status: 200 })` before throwing on malformed or non-JSON SSE chunks.
14
+
15
+ ## [1.5.2] - 2026-10-22
16
+
17
+ ### Fixed
18
+ - **Usage Counter Normalization & Cost Estimation (`usage-details.js`, `pricing.js`, `inspector-overview.js`, `diagnostic-store.js`)**:
19
+ - Resolved omitted optional zero usage counters (`cachedTokens`, `toolTokens`, `thoughtTokens`, and conserved zero `outputTokens` on tool-only `GenerateContent` turns) via `resolveUsageCounts` so completed turns with omitted zero counters no longer drop USD cost estimates to `null` or under-report `allComplete` scope totals, while preserving durable `invalidCounts` markers for malformed wire values.
20
+ - **Native Patch & Request Association Lifecycle (`adapter.js`, `index.js`, `generate-content.js`)**:
21
+ - Updated `installGemini4PiAiPatch` and `ensureGemini4ApiClientPatch` to follow live `longDecode`, service-tier, and `retainRawResponses` settings on patched native providers and cleanly deactivate upon disposal without overwriting downstream wrappers.
22
+ - Cleared `request-association` tracking state on plugin unload and guarded `continueArgonRequestStream` when `signal` is already aborted before the first stream attempt.
23
+ - **Offline Test Guard & Host Module Loader (`package.json`, `test/offline-guard.mjs`, `test/host-loader.mjs`, `test/host-internals.mjs`)**:
24
+ - Enforced `--import ./test/offline-guard.mjs` in `npm test`, added IPv6 loopback bracket handling, and decoupled offline UI/SSR tests from checkout-only internals via verified read-only host bundle loading.
25
+
26
+ ### Changed
27
+ - **Inspector & Client Rendering Performance (`inspector-overview.js`, `client.js`)**:
28
+ - Computed `oldestAt` / `newestAt` overview bounds in a single pass and cached module-level `Intl.DateTimeFormat` / `Intl.NumberFormat` instances.
29
+
5
30
  ## [1.5.1] - 2026-10-19
6
31
 
7
32
  ### Changed
package/README.md CHANGED
@@ -26,17 +26,17 @@
26
26
 
27
27
  `dsh-vertex-argon` 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) 提供生产级的 **Gemini 4 Argon** 双通道接入支持。插件同时打通 **Google Vertex AI**(ADC 服务账号 / Express API Key)与 **Google Gemini Developer API**(AI Studio API Key),完整支持 **`GenerateContent` (`v1beta1` / `v1`) 多跳长解码续传**与 **`Interactions` (`v1beta`) 持久化后台恢复**双协议,配备显式服务层级路由(`Standard` / `Flex` / `Priority`)、仅签名空 `Part` 无损回放、模态级 Token 账本、公开价格成本估算、**Argon Inspector 全景检视台**以及只读 Agent 诊断工具 `argon_inspect`。
28
28
 
29
- Current release: **[1.5.1](https://github.com/higekibaka/dsh-vertex-argon)** · [npm](https://www.npmjs.com/package/dsh-vertex-argon) · [CHANGELOG](./CHANGELOG.md)
29
+ Current release: **[1.5.2](https://github.com/higekibaka/dsh-vertex-argon)** · [npm](https://www.npmjs.com/package/dsh-vertex-argon) · [CHANGELOG](./CHANGELOG.md)
30
30
 
31
31
  ---
32
32
 
33
33
  ## ✨ 为什么需要这个插件?
34
34
 
35
- | 能力维度 | DSH 内置 `google` / `google-vertex` 默认适配器 | `dsh-vertex-argon` (v1.5.1) |
35
+ | 能力维度 | DSH 内置 `google` / `google-vertex` 默认适配器 | `dsh-vertex-argon` (v1.5.2) |
36
36
  |---|---|---|
37
37
  | **思考控制参数** | 误传 `thinkingBudget: -1` 触发云端 `HTTP 400`,或传入超限档位 `max` 报错 | 原生映射 `thinkingLevel: "LOW" \| "MEDIUM" \| "HIGH"`,自动将 `max` 收敛为 `high`,剔除无效采样参数 |
38
38
  | **思维链与空块签名回放** | 容易丢失不带文本的独立 `thoughtSignature` `Part`,影响长链路多轮推理与工具续答 | 固定开启 `includeThoughts: true`,通过 `google-signatures.js` 无损编码并原样回放仅含签名的空 `Part` |
39
- | **GenerateContent 超长解码** | 单次锁死 64K,遇 `CONTINUATION` 直接截断结束;无流内错误帧识别 | 自动切换 `v1beta1` 执行 `continuationToken` 多跳续写(最高 `1,048,576`预算 / 最多 32 跳)、检查点指数退避重连与 HTTP 200 SSE 内联 `{ error }` 拦截 |
39
+ | **GenerateContent 超长解码** | 单次锁死 64K,遇 `CONTINUATION` 直接截断结束;无流内错误帧识别 | 自动切换 `v1beta1` 执行 `continuationToken` 多跳续写(最高 `1,048,576` 输出 token 预算 / 最多 32 跳)、同一检查点无进展最多 3 次指数退避重连与 HTTP 200 SSE 内联 `{ error }` 拦截 |
40
40
  | **Interactions 协议与后台恢复** | 不支持 `Interactions` 协议及后台持久化执行 | 原生支持 `Interactions` (`v1beta`)、`creating` 预写防重发锁、以及基于 `last_event_id` 游标的流式断点续读 |
41
41
  | **服务层级与 PayGo 控制** | 仅默认标准队列,无层级路由与响应账单核验 | 支持按通道显式指定 `standard` / `flex` / `priority` 及 Vertex `PayGo-Only` 共享池请求头,未验证组合发包前 Fail-Closed 拦截 |
42
42
  | **可观测性、用量与成本估算** | 仅展示粗粒度总 Token,多跳长解码易虚报上下文水位触发误压缩 | **水位线 Token 与累计计费 Token 双轨分离** + 模态级(文本/图像/音频/视频/文档)拆解 + 公开价格非账单 USD 估算 + **Argon Inspector** 检视台与 `argon_inspect` 工具 |
@@ -90,7 +90,7 @@ flowchart TD
90
90
  P -->|"generate-content (默认)"| GC["GenerateContent 引擎 (v1beta1 / v1)<br/>• continuationToken 多跳续传 (最高 32 跳)<br/>• 检查点指数退避重连 & 内联 { error } 拦截<br/>• google-signatures.js 空块签名无损回放"]
91
91
  P -->|"interactions"| IA["Interactions 引擎 (v1beta)<br/>• 前台 SSE 流式 或 后台持久化执行<br/>• creating 预写锁防止断网重复创建计费<br/>• last_event_id 游标流式断点续读"]
92
92
 
93
- GC --> D["诊断、关联与公开价格估算中心<br/>• request-association.js 绑定精确 messageId<br/>• usage-details.js 模态拆解 & 水位/计费双轨计量<br/>• pricing.js 公开价格表非账单 USD 估算<br/>• response-store.js 可选脱敏原始响应帧"]
93
+ GC --> D["诊断、关联与公开价格估算中心<br/>• request-association.js 绑定精确 messageId<br/>• usage-details.js 模态拆解 & 水位/计费双轨计量<br/>• pricing.js 公开价格表非账单 USD 估算<br/>• response-store.js 可选上游 JSON 响应帧"]
94
94
  IA --> D
95
95
 
96
96
  D --> UI["Argon Inspector 检视台 & argon_inspect 工具<br/>右侧栏 · 对话主视图 · 单条回复图标 · 只读云端 ID 查询"]
@@ -114,7 +114,7 @@ v1.5.0 内置完整的 **Argon Inspector** 可观测套件,前后端共享同
114
114
  - **Overview**:通道、模型、协议、API 版本、区域分类(`global` / `non-global`)、请求与实测服务层级、关联 `messageId`。
115
115
  - **Hops & Usage**:逐跳耗时、HTTP 状态、触发原因(`initial` / `continuation` / `checkpoint-reconnect`)、水位线 Token 与分模态(`TEXT` / `IMAGE` / `AUDIO` / `VIDEO` / `DOCUMENT`)账本。
116
116
  - **Cost Estimate**:基于公开价格快照 `argon-public-2026-10-18` 的逐跳与汇总 USD 估算(明确标注非账单发票,区分促销期与 Vertex 非 `global` `1.1x` 系数)。
117
- - **Raw Response**:当开启 `retainRawResponses` 时,支持按帧、按字符偏移分页查阅已脱敏的原始响应内容。
117
+ - **Raw Response**:当开启 `retainRawResponses` 时,支持按帧、按字符偏移分页查阅解析后的上游 JSON 响应;可能包含正文、签名以及尚未提交或重放的帧,并非已脱敏正文或可恢复检查点。
118
118
  - **Operations 运维标签页**:
119
119
  - **Cloud Interaction ID 只读查询**:输入任意已知的云端 Interaction ID 与通道,执行单次只读 `interactions.get(id)` 查询并分页检视返回内容(绝不恢复生成、不取消云端任务、不执行返回的工具调用)。
120
120
  - **Background Recovery 锁管理**:查看当前持久化后台任务状态,并在出现未知创建中断(`creating`)时由用户确认后手动释放锁。
@@ -127,7 +127,7 @@ v1.5.0 内置完整的 **Argon Inspector** 可观测套件,前后端共享同
127
127
  | `overview` | 聚合当前会话(或指定 `messageId`)在保留窗口内的用量、成本与覆盖率概览 | `messageId?`, `limit?` (1–100) |
128
128
  | `list` | 列出当前会话(或指定 `messageId`)的本地诊断请求摘要与 `requestId` | `messageId?`, `limit?` (1–50) |
129
129
  | `detail` | 分页读取指定 `requestId` 的完整诊断记录、逐跳账本、模态用量与成本明细 | `requestId`, `offset?`, `limit?` (1–10) |
130
- | `response` | 按字符偏移分页读取指定 `requestId` 已捕获的脱敏原始响应帧 | `requestId`, `index?`, `offset?`, `length?` |
130
+ | `response` | 按字符偏移分页读取指定 `requestId` 已捕获的上游 JSON 响应帧 | `requestId`, `index?`, `offset?`, `length?` |
131
131
  | `query` | 使用当前配置凭据对已知 Cloud Interaction ID 执行单次只读 `GET` 查询 | `route`, `id` |
132
132
  | `query-response` | 分页读取 `query` 返回的临时云端 Interaction 响应内容 | `queryId`, `offset?`, `length?` |
133
133
 
@@ -211,7 +211,7 @@ dsh plugin --profile web add dsh-vertex-argon
211
211
  | | `vertexPaygoOnly` | `false` | `boolean` | Vertex `generate-content` 请求固定附带 `X-Vertex-AI-LLM-Request-Type: shared` |
212
212
  | **Interactions 后台模式** | `interactionsBackground` | `false` | `boolean` | 在 `interactions` 协议下启用云端持久化后台执行(须同时开启 `allowInteractionStorage`) |
213
213
  | | `allowInteractionStorage` | `false` | `boolean` | 允许向 `interactions` 请求发送 `store: true` 以支持断线恢复与 ID 查询 |
214
- | **诊断与高级** | `retainRawResponses` | `false` | `boolean` | 显式开启后,在本地 `vertex_argon_responses` 存储域保留最近 50 条脱敏原始响应帧(关闭时立即清空) |
214
+ | **诊断与高级** | `retainRawResponses` | `false` | `boolean` | 显式开启后,在本地 `vertex_argon_responses` 存储域保留最多 20 条响应记录,总量 64 MiB、单条 16 MiB;关闭仅停止新请求捕获,不清空已有记录 |
215
215
 
216
216
  ---
217
217
 
@@ -230,23 +230,25 @@ dsh plugin --profile web add dsh-vertex-argon
230
230
 
231
231
  ### 本地持久化存储域(Storage Domains)
232
232
  - `vertex_argon_diagnostics`:保存最近 **200 条**结构化请求诊断记录(自动脱敏,不含正文或密钥)。
233
- - `vertex_argon_responses`:仅当 `retainRawResponses: true` 时保存最近 **50 条**脱敏原始响应帧(单帧上限 256 KB,关闭开关即刻清空)。
233
+ - `vertex_argon_responses`:仅当 `retainRawResponses: true` 时捕获上游 JSON 响应,最多保留 **20 条响应记录**、**64 MiB 总量**、**16 MiB 单条**;按最旧记录淘汰,超出单条限制的后续帧记为省略。关闭开关仅停止新请求捕获,**不会清空已有记录**。响应可能包含正文、签名及未提交或重放的帧;不保存 HTTP 头、请求体或凭据。
234
234
  - `vertex_argon_interactions`:保存后台 `Interactions` 任务的创建锁与 `last_event_id` 恢复游标。
235
235
 
236
236
  ---
237
237
 
238
238
  ## 🧪 离线零网络测试套件
239
239
 
240
- 仓库内置 **36 个自动化测试文件**(`test/*.test.mjs`),全部在 `test/offline-guard.mjs` 零外网守卫下运行(拦截一切非回环 `fetch` / `http` / `https` / `http2` / `net` / `tls` / `dns` 调用,确保测试零网络、零产生云端费用):
240
+ 仓库内置 **37 个自动化测试文件**(`test/*.test.mjs`)。`npm test` 会先加载 [offline-guard.mjs](<test/offline-guard.mjs>) 零外网守卫,再加载 [host-loader.mjs](<test/host-loader.mjs>) 复用本机已有依赖;仅允许测试进程自行创建的临时 IPv4 回环服务,不访问外网或产生云端费用:
241
241
 
242
242
  ```bash
243
- DSH_TEST_HOST_ROOT=/path/to/deepseek-harness \
244
- node --experimental-transform-types \
245
- --import ./test/offline-guard.mjs \
246
- --import ./test/host-loader.mjs \
247
- --test test/*.test.mjs
243
+ npm test
244
+ # 需要指定已有宿主依赖时:
245
+ DSH_TEST_HOST_ROOT=/path/to/deepseek-harness npm test
248
246
  ```
249
247
 
248
+ 默认模块解析失败后,测试加载器依次尝试显式 `DSH_TEST_HOST_ROOT`、相对仓库根的 `../../deepseek-harness`(也兼容 `../deepseek-harness` 相邻布局)、本机 `~/.dsh/profiles/desktop/node_modules`,以及 Windows 上的 `O:/DeepSeekHarness/resources/app.asar.unpacked/dsh/node_modules`;只使用存在的路径。可显式指定源码根、已解包宿主根或其 `node_modules`,并沿真实包路径解析 pnpm 嵌套依赖。加载器不下载依赖、不修改宿主或桌面 profile。若仍缺少依赖,最后尝试本机 `O:/DeepSeekHarness/resources/app.asar`:Electron 可直接读取时复用归档;普通 Node 则只读解出实际请求的包及其包内文件,缓存到仓库 `.tmp/test-host/<归档指纹>/node_modules`。缓存校验路径、链接、文件偏移及归档提供的完整性摘要,写完后原子发布以供并行测试复用;宿主归档变化会使用新缓存。
249
+
250
+ 客户端回归通过 [host-internals.mjs](<test/host-internals.mjs>) 加载真实宿主控制器:有源码时直接导入,否则读取发行工厂并仅附加内部符号导出,不替换实现或行为断言。服务端渲染需要版本完全匹配的真实 `react` / `react-dom`,优先复用显式源码树及本地依赖;本机也可只读复用 `O:/AI/kt/outdoor-gear-landing/node_modules` 中的 19.2.8。缺少真实依赖时明确失败,不联网下载或改用模拟控制器。
251
+
250
252
  ---
251
253
 
252
254
  ## ⚠️ 与 `billion-context` 配合使用的兼容性说明
package/adapter.js CHANGED
@@ -76,7 +76,7 @@ export function detectPiAiArgonRoutes(ctx, explicitRoutes) {
76
76
  const TRANSIENT_GEMINI_STOP_RE = /(?:Unhandled stop reason:\s*(?:MALFORMED_RESPONSE|MALFORMED_FUNCTION_CALL|UNEXPECTED_TOOL_CALL|TOO_MANY_TOOL_CALLS)|Provider stopped with:\s*(?:MALFORMED_RESPONSE|MALFORMED_FUNCTION_CALL|UNEXPECTED_TOOL_CALL|OTHER|FINISH_REASON_UNSPECIFIED))/i
77
77
 
78
78
  let apiClientProtoRef = null
79
- let origApiClientRequestStream = null
79
+ let apiClientPatch = null
80
80
 
81
81
  function getApiClientPrototype() {
82
82
  if (apiClientProtoRef) return apiClientProtoRef
@@ -92,28 +92,26 @@ function getApiClientPrototype() {
92
92
  export function ensureGemini4ApiClientPatch() {
93
93
  const proto = getApiClientPrototype()
94
94
  if (!proto || typeof proto.requestStream !== 'function') return () => {}
95
- if (origApiClientRequestStream) {
96
- return () => {
97
- if (proto.requestStream !== origApiClientRequestStream && origApiClientRequestStream) {
98
- proto.requestStream = origApiClientRequestStream
99
- origApiClientRequestStream = null
100
- }
101
- }
102
- }
95
+ if (apiClientPatch) return apiClientPatch.dispose
103
96
  const orig = proto.requestStream
104
- origApiClientRequestStream = orig
97
+ let active = true
105
98
  function patchedRequestStream(request) {
106
99
  const meta = request?.httpOptions?.[ARGON_LONG_DECODE_SYMBOL]
107
- if (!meta) return orig.call(this, request)
100
+ if (!active || !meta) return orig.call(this, request)
108
101
  return continueArgonRequestStream(this, orig, request, meta)
109
102
  }
110
- proto.requestStream = patchedRequestStream
111
- return () => {
112
- if (proto.requestStream === patchedRequestStream) {
113
- proto.requestStream = orig
114
- }
115
- origApiClientRequestStream = null
103
+ const patch = {
104
+ dispose() {
105
+ if (!active) return
106
+ active = false
107
+ // A later wrapper belongs to its installer, even when it delegates to us.
108
+ if (proto.requestStream === patchedRequestStream) proto.requestStream = orig
109
+ if (apiClientPatch === patch) apiClientPatch = null
110
+ },
116
111
  }
112
+ proto.requestStream = patchedRequestStream
113
+ apiClientPatch = patch
114
+ return patch.dispose
117
115
  }
118
116
 
119
117
  function wrapGemini4Stream(rawStream, tracker, signal) {
@@ -255,12 +253,13 @@ export function gemini4StreamSimple(
255
253
  )
256
254
  }
257
255
 
258
- export function installGemini4PiAiPatch(recordDiagnostic) {
256
+ export function installGemini4PiAiPatch(recordDiagnostic, configInput = {}, responseHub) {
259
257
  const unpatchApiClient = ensureGemini4ApiClientPatch()
260
258
  const proto = PiAiAdapter?.prototype
261
259
  if (!proto || typeof proto.current !== 'function') return unpatchApiClient
262
260
  const origCurrent = proto.current
263
261
  const patchedProviders = new Map()
262
+ let active = true
264
263
  const ensureGemini4Capabilities = piProvider => {
265
264
  if (typeof piProvider?.getModels !== 'function') return
266
265
  try {
@@ -277,17 +276,24 @@ export function installGemini4PiAiPatch(recordDiagnostic) {
277
276
  ensureGemini4Capabilities(piProvider)
278
277
  if (piProvider.id === PROVIDER || patchedProviders.has(piProvider)) return
279
278
  const origStreamSimple = piProvider.streamSimple
280
- patchedProviders.set(piProvider, origStreamSimple)
281
- piProvider.streamSimple = function (requestModel, context, options = {}) {
282
- if (isGemini4Model(requestModel)) {
283
- return gemini4StreamSimple((m, c, o) => piProvider.stream(m, c, o), requestModel, context, options, defaultReasoning, requestModel.id, true, recordDiagnostic)
279
+ function patchedStreamSimple(requestModel, context, options = {}) {
280
+ if (active && isGemini4Model(requestModel)) {
281
+ const cfg = resolveConfigValues(configInput)
282
+ return gemini4StreamSimple(
283
+ (m, c, o) => piProvider.stream(m, c, o), requestModel, context, options,
284
+ defaultReasoning, requestModel.id, cfg.longDecode, recordDiagnostic,
285
+ resolveServicePolicy(cfg, requestModel.api, 'generate-content'),
286
+ { responseHub, retainRawResponses: cfg.retainRawResponses },
287
+ )
284
288
  }
285
289
  return origStreamSimple.call(this, requestModel, context, options)
286
290
  }
291
+ patchedProviders.set(piProvider, { origStreamSimple, patchedStreamSimple })
292
+ piProvider.streamSimple = patchedStreamSimple
287
293
  }
288
294
  function patchedCurrent() {
289
295
  const snapshot = origCurrent.call(this)
290
- if (snapshot?.profiles instanceof Map) {
296
+ if (active && snapshot?.profiles instanceof Map) {
291
297
  for (const profile of snapshot.profiles.values()) {
292
298
  if (profile?.piProvider) wrapProvider(profile.piProvider, profile.reasoning)
293
299
  }
@@ -296,10 +302,12 @@ export function installGemini4PiAiPatch(recordDiagnostic) {
296
302
  }
297
303
  proto.current = patchedCurrent
298
304
  return () => {
305
+ if (!active) return
306
+ active = false
299
307
  unpatchApiClient()
300
308
  if (proto.current === patchedCurrent) proto.current = origCurrent
301
- for (const [piProvider, origStreamSimple] of patchedProviders.entries()) {
302
- piProvider.streamSimple = origStreamSimple
309
+ for (const [piProvider, { origStreamSimple, patchedStreamSimple }] of patchedProviders) {
310
+ if (piProvider.streamSimple === patchedStreamSimple) piProvider.streamSimple = origStreamSimple
303
311
  }
304
312
  patchedProviders.clear()
305
313
  }
@@ -463,13 +471,9 @@ export function createArgonAdapter(ctx, configInput, nativeVertex = googleVertex
463
471
  resolveConfigValues(configInput)
464
472
  const environment = launchEnvironmentOf(ctx)
465
473
  const resolveSecret = async name => {
466
- try {
467
- const cred = await ctx?.get?.('credentials')?.resolve?.(name)
468
- if (cred?.value) return cred.value
469
- } catch (error) {
470
- // Explicit billed auxiliary requests must not switch accounts on store failure.
471
- if (structuredOutput) throw error
472
- }
474
+ // A failed credential store must never silently select an ambient account.
475
+ const cred = await ctx?.get?.('credentials')?.resolve?.(name)
476
+ if (cred?.value) return cred.value
473
477
  return environment.get(name)?.value
474
478
  }
475
479
  const authContext = {
package/client.js CHANGED
@@ -614,7 +614,7 @@ window.__ModuleLoader__.load({
614
614
  inspectorOverviewCoverage: '已记录请求', inspectorOverviewCoverageComplete: '完整请求', inspectorOverviewPartial: '部分记录;不是完整总量',
615
615
  inspectorOverviewDenied: '无总览读取权限;请求列表仍可单独查看。', inspectorOverviewWindow: '当前本地保留窗口,非全历史或云账单;最多扫描最近 200 条,再按当前范围取最多 100 条。',
616
616
  inspectorOverviewLimited: '当前范围匹配记录超过显示上限,较早记录不含在内。', inspectorOverviewDates: '记录时间范围',
617
- inspectorOverviewCache: '按输入 Token 加权;仅全部请求的缓存与输入均完整有效时展示。',
617
+ inspectorOverviewCache: '按完整有效请求的输入 Token 加权计算。',
618
618
  inspectorOverviewCost: '已知费用小计(USD)', inspectorOverviewCostComplete: '完整费用估算(USD)',
619
619
  inspectorOverviewFields: '各项 Token 合计',
620
620
  })
@@ -652,7 +652,7 @@ window.__ModuleLoader__.load({
652
652
  inspectorOverviewCoverage: 'Reported requests', inspectorOverviewCoverageComplete: 'Complete requests', inspectorOverviewPartial: 'Partial records; not a complete total',
653
653
  inspectorOverviewDenied: 'No permission to read the overview; individual requests remain available in the list.', inspectorOverviewWindow: 'Current local retained window, not all history or cloud billing; scans at most the latest 200 records, then takes up to 100 for this scope.',
654
654
  inspectorOverviewLimited: 'Matching retained records exceed the display limit; earlier records are excluded.', inspectorOverviewDates: 'Record time range',
655
- inspectorOverviewCache: 'Weighted by input tokens; shown only when every request has complete, valid cache/input counts.',
655
+ inspectorOverviewCache: 'Weighted by input tokens across requests with complete, valid cache/input counts.',
656
656
  inspectorOverviewCost: 'Known cost subtotal (USD)', inspectorOverviewCostComplete: 'Complete cost estimate (USD)',
657
657
  inspectorOverviewFields: 'Token totals by field',
658
658
  })
@@ -713,11 +713,16 @@ window.__ModuleLoader__.load({
713
713
  })
714
714
  }
715
715
 
716
+ // toLocaleTimeString rebuilt a formatter for every rendered row. The cached
717
+ // one is byte-identical: hour/minute/second numeric with hour12:false keeps
718
+ // zh-CN and en-GB zero-padded hours and never rewrites a ko-KR pattern.
719
+ const timeFormatter = new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: 'numeric', second: 'numeric', hour12: false })
720
+
716
721
  function formatTimeShort(iso) {
717
722
  if (typeof iso !== 'string') return ''
718
723
  const d = new Date(iso)
719
724
  if (Number.isNaN(d.getTime())) return iso.slice(11, 19)
720
- return d.toLocaleTimeString([], { hour12: false })
725
+ return timeFormatter.format(d)
721
726
  }
722
727
 
723
728
  function formatDuration(ms) {
@@ -726,6 +731,10 @@ window.__ModuleLoader__.load({
726
731
  return (ms / 1000).toFixed(2) + 's'
727
732
  }
728
733
 
734
+ // Number#toLocaleString allocated a formatter per rendered value; the
735
+ // cached formatter prints identically, including 786432 -> "786,432".
736
+ const numberFormatter = new Intl.NumberFormat()
737
+
729
738
  function DiagnosticsPanel({ loadDiagnostics, t }) {
730
739
  const [open, setOpen] = React.useState(false)
731
740
  const [loading, setLoading] = React.useState(false)
@@ -757,7 +766,7 @@ window.__ModuleLoader__.load({
757
766
  if (open) void refresh()
758
767
  }, [open, refresh])
759
768
 
760
- const fmt = n => (typeof n === 'number' && Number.isFinite(n) ? Number(n).toLocaleString() : '-')
769
+ const fmt = n => (typeof n === 'number' && Number.isFinite(n) ? numberFormatter.format(n) : '-')
761
770
  const total = records.length
762
771
  const okCount = records.filter(r => r.outcome === 'done' || r.outcome === 'tool-calls' || r.outcome === 'max-tokens').length
763
772
  const contHops = records.reduce((acc, r) => acc + (r.continuationCount || 0), 0)
@@ -1114,9 +1123,11 @@ window.__ModuleLoader__.load({
1114
1123
  const OVERVIEW_CSS = '\n.argon-inspector .ag-scope-overview{margin:14px 0}.argon-inspector .ag-scope-overview .ag-overview{grid-template-columns:repeat(auto-fit,minmax(min(100%,180px),1fr));margin:12px 0}.argon-inspector .ag-overview-fields{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,140px),1fr));gap:14px;margin:12px 0}.argon-inspector .ag-overview-fields dd{margin:4px 0;font-variant-numeric:tabular-nums;font-size:17px}.argon-inspector .ag-overview-fields small{display:block;font-size:11px;color:var(--dsw-alias-label-secondary)}'
1115
1124
  function ScopeOverview({ overview, t, metric, busy, allowed }) {
1116
1125
  const coverage = value => t('inspectorOverviewCoverage') + ': ' + (value?.reportedRequests ?? 0) + '/' + overview.requestCount + ' · ' + t('inspectorOverviewCoverageComplete') + ': ' + (value?.completeRequests ?? 0) + '/' + overview.requestCount
1117
- const total = overview?.tokens?.totalTokens, cost = overview?.cost
1126
+ const cacheCoverage = () => t('inspectorOverviewCoverageComplete') + ': ' + (overview?.cache?.completeRequests ?? 0) + '/' + overview.requestCount + ' · ' + t('inspectorOverviewCache')
1127
+ const total = overview?.tokens?.totalTokens, cost = overview?.cost, cache = overview?.cache
1118
1128
  const money = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? '$' + value.toFixed(6) : '—'
1119
1129
  const completeCost = cost?.estimatedUsd != null
1130
+ const completeCache = overview?.requestCount > 0 && cache?.completeRequests === overview.requestCount
1120
1131
  const fields = [['inputTokens', 'inspectorInput'], ['cachedTokens', 'inspectorTokenCached'], ['outputTokens', 'inspectorTokenOutput'], ['thoughtTokens', 'inspectorTokenReasoning'], ['toolTokens', 'inspectorTokenTool']]
1121
1132
  return h('section', { className: 'card ag-scope-overview', 'data-overview': true, 'aria-label': t('inspectorOverview') },
1122
1133
  h('h3', null, t('inspectorOverview')),
@@ -1125,7 +1136,7 @@ window.__ModuleLoader__.load({
1125
1136
  overview.window?.limited ? h('p', { className: 'ag-notice' }, t('inspectorOverviewLimited')) : null,
1126
1137
  h('div', { className: 'ag-overview' },
1127
1138
  metric('overview-total', t('inspectorTokenTotal') + ' · ' + t(total?.complete ? 'inspectorOverviewComplete' : 'inspectorOverviewKnown'), tokenText(total?.knownSubtotal), coverage(total)),
1128
- metric('overview-cache', t('inspectorCacheHitRate'), typeof overview.cache?.percent === 'number' && Number.isFinite(overview.cache.percent) ? overview.cache.percent.toFixed(1) + '%' : '—', t('inspectorOverviewCache')),
1139
+ metric('overview-cache', t('inspectorCacheHitRate') + (typeof cache?.percent === 'number' && Number.isFinite(cache.percent) && !completeCache ? ' · ' + t('inspectorOverviewKnown') : ''), typeof cache?.percent === 'number' && Number.isFinite(cache.percent) ? cache.percent.toFixed(1) + '%' : '—', cacheCoverage()),
1129
1140
  metric('overview-cost', t(completeCost ? 'inspectorOverviewCostComplete' : 'inspectorOverviewCost'), money(completeCost ? cost.estimatedUsd : cost?.knownSubtotalUsd), coverage(cost))),
1130
1141
  h('dl', { className: 'ag-overview-fields', 'aria-label': t('inspectorOverviewFields') }, ...fields.map(([key, label]) => {
1131
1142
  const value = overview.tokens?.[key]
@@ -1137,28 +1148,68 @@ window.__ModuleLoader__.load({
1137
1148
  }
1138
1149
 
1139
1150
  const knownTokens = value => Number.isSafeInteger(value) && value >= 0
1140
- const tokenText = value => knownTokens(value) ? value.toLocaleString() : '—'
1151
+ const tokenText = value => knownTokens(value) ? numberFormatter.format(value) : '—'
1152
+ function resolveUsageCounts(usage, protocol) {
1153
+ if (!inspectorObject(usage)) return null
1154
+ const invalid = new Set(Array.isArray(usage.invalidCounts) ? usage.invalidCounts : [])
1155
+ const keys = ['inputTokens', 'cachedTokens', 'outputTokens', 'thoughtTokens', 'toolTokens', 'totalTokens']
1156
+ const result = Object.fromEntries(keys.map(key => [key, invalid.has(key) ? null : (knownTokens(usage[key]) ? usage[key] : null)]))
1157
+ const absent = key => usage[key] == null && !invalid.has(key)
1158
+ if (result.inputTokens !== null) {
1159
+ for (const key of ['cachedTokens', 'toolTokens']) if (absent(key)) result[key] = 0
1160
+ }
1161
+ if (protocol === 'generate-content' && absent('outputTokens') && result.inputTokens !== null && result.totalTokens !== null && result.toolTokens !== null) {
1162
+ const thoughts = absent('thoughtTokens') ? 0 : result.thoughtTokens
1163
+ const accounted = thoughts === null ? null : result.inputTokens + result.toolTokens + thoughts
1164
+ if (accounted !== null && knownTokens(accounted) && accounted === result.totalTokens) result.outputTokens = 0
1165
+ }
1166
+ if (result.outputTokens !== null && absent('thoughtTokens')) result.thoughtTokens = 0
1167
+ return result
1168
+ }
1169
+ function selectGcUsageRows(record) {
1170
+ const details = record?.usageDetails
1171
+ const allRows = (details?.rows ?? []).filter(row => row?.kind === 'gc-hop')
1172
+ const ledgerValid = allRows.length > 0 && allRows.length === record?.hopCount && !details?.omittedRows
1173
+ && allRows.every(row => knownTokens(row.index)) && new Set(allRows.map(row => row.index)).size === allRows.length
1174
+ if (!ledgerValid) return { rows: allRows, ledgerValid: false }
1175
+ const sorted = [...allRows].sort((a, b) => a.index - b.index)
1176
+ const hops = Array.isArray(record?.hops) && !record?.hopsDropped ? record.hops : []
1177
+ const byIndex = new Map(hops.filter(inspectorObject).map(hop => [hop.hopIndex, hop]))
1178
+ let start = 0
1179
+ if (['done', 'max-tokens', 'tool-calls'].includes(record?.outcome) && sorted.every((row, i) => row.index === i + 1)) {
1180
+ while (start + 1 < sorted.length) {
1181
+ const row = sorted[start], hop = byIndex.get(row.index), next = byIndex.get(sorted[start + 1].index)
1182
+ if (row.usage === null && row.complete === false
1183
+ && hop && hop.trigger === (start === 0 ? 'initial' : 'retry-original')
1184
+ && hop.usedContinuationToken === false && hop.chunkCount === 0 && hop.hasCheckpoint === false
1185
+ && ['transport-error', 'api-error'].includes(hop.outcome)
1186
+ && next && next.trigger === 'retry-original' && next.usedContinuationToken === false) start++
1187
+ else break
1188
+ }
1189
+ }
1190
+ return { rows: start > 0 ? sorted.slice(start) : allRows, ledgerValid: true }
1191
+ }
1141
1192
  function extractTokenMix(record) {
1142
1193
  const details = record?.usageDetails
1143
1194
  const keys = ['inputTokens', 'cachedTokens', 'outputTokens', 'thoughtTokens', 'toolTokens', 'totalTokens']
1144
1195
  let usage = null, complete = false, sourceCacheValid = true, sourceTotalsValid = true
1145
1196
  if (record?.protocol === 'generate-content') {
1146
- const rows = (details?.rows ?? []).filter(row => row.kind === 'gc-hop')
1147
- const ledger = rows.length > 0 && rows.length === record.hopCount && !details.omittedRows && new Set(rows.map(row => row.index)).size === rows.length
1197
+ const { rows, ledgerValid: ledger } = selectGcUsageRows(record)
1198
+ const usages = rows.map(row => resolveUsageCounts(row.usage, 'generate-content'))
1148
1199
  usage = Object.fromEntries(keys.map(key => {
1149
- const values = rows.map(row => row.usage?.[key])
1200
+ const values = usages.map(u => u?.[key])
1150
1201
  const sum = ledger && values.every(knownTokens) ? values.reduce((a, b) => a + b, 0) : null
1151
1202
  return [key, knownTokens(sum) ? sum : null]
1152
1203
  }))
1153
- sourceCacheValid = rows.every(row => knownTokens(row.usage?.inputTokens) && knownTokens(row.usage?.cachedTokens) && row.usage.cachedTokens <= row.usage.inputTokens)
1154
- sourceTotalsValid = rows.every(row => {
1155
- const parts = ['inputTokens', 'outputTokens', 'thoughtTokens', 'toolTokens'].map(key => row.usage?.[key])
1156
- return knownTokens(row.usage?.totalTokens) && parts.every(value => value == null || knownTokens(value))
1157
- && parts.filter(knownTokens).reduce((sum, value) => sum + value, 0) === row.usage.totalTokens
1204
+ sourceCacheValid = usages.every(u => knownTokens(u?.inputTokens) && knownTokens(u?.cachedTokens) && u.cachedTokens <= u.inputTokens)
1205
+ sourceTotalsValid = usages.every(u => {
1206
+ const parts = ['inputTokens', 'outputTokens', 'thoughtTokens', 'toolTokens'].map(key => u?.[key])
1207
+ return knownTokens(u?.totalTokens) && parts.every(value => value == null || knownTokens(value))
1208
+ && parts.filter(knownTokens).reduce((sum, value) => sum + value, 0) === u.totalTokens
1158
1209
  })
1159
1210
  complete = ledger && rows.every(row => row.complete === true)
1160
1211
  } else if (record?.protocol === 'interactions') {
1161
- usage = details?.aggregate
1212
+ usage = resolveUsageCounts(details?.aggregate, 'interactions')
1162
1213
  complete = details?.aggregateComplete === true
1163
1214
  }
1164
1215
  const read = key => knownTokens(usage?.[key]) ? usage[key] : null
@@ -1266,10 +1317,11 @@ window.__ModuleLoader__.load({
1266
1317
  h('div', { className: 'ag-subhead' }, t('inspectorStepHopTable') + ' (' + rows.length + ')'),
1267
1318
  h('div', { className: 'ag-hop-list' },
1268
1319
  ...rows.slice(0, 12).map((r, idx) => {
1269
- const pTok = r.usage?.inputTokens
1270
- const oTok = r.usage?.outputTokens
1271
- const tTok = r.usage?.thoughtTokens
1272
- const tot = r.usage?.totalTokens
1320
+ const resolved = resolveUsageCounts(r.usage, r.kind === 'interaction-step' ? 'interactions' : 'generate-content')
1321
+ const pTok = resolved?.inputTokens
1322
+ const oTok = resolved?.outputTokens
1323
+ const tTok = resolved?.thoughtTokens
1324
+ const tot = resolved?.totalTokens
1273
1325
  return h('div', { key: idx, className: 'ag-hop-row' },
1274
1326
  h('span', { className: 'ag-pill ag-pill-muted' }, (r.kind ?? 'hop') + ' #' + (r.index ?? idx)),
1275
1327
  h('span', { className: 'ag-hop-nums' }, t('inspectorInput') + ' ' + tokenText(pTok) + ' · ' + t('inspectorTokenOutput') + ' ' + tokenText(oTok) + ' · ' + t('inspectorTokenReasoning') + ' ' + tokenText(tTok)),
@@ -1596,7 +1648,7 @@ window.__ModuleLoader__.load({
1596
1648
  finally { writing.current = false; setPending(false) }
1597
1649
  }
1598
1650
 
1599
- const fmt = n => Number(n).toLocaleString()
1651
+ const fmt = n => numberFormatter.format(n)
1600
1652
  const allTokenPresets = [8192, 16384, 32768, 65536, 131072, 262144, 524288, 786432, 1048576]
1601
1653
  const maxTokenCaps = longDecode ? allTokenPresets : [8192, 16384, 32768, 65536]
1602
1654
  const contextWindowPresets = [262144, 524288, 1048576]
@@ -40,6 +40,7 @@ const tokenUsageSchema = z.object({
40
40
  }).strict()
41
41
 
42
42
  const normalizedUsageSchema = z.object({
43
+ invalidCounts: z.array(z.enum(USAGE_COUNT_KEYS)).max(USAGE_COUNT_KEYS.length).optional(),
43
44
  ...Object.fromEntries(USAGE_COUNT_KEYS.map(key => [key, count.nullable()])),
44
45
  ...Object.fromEntries(USAGE_DETAIL_KEYS.map(key => [key, z.array(z.object({ modality: z.enum(USAGE_MODALITIES), tokens: count }).strict()).max(USAGE_MODALITIES.length).nullable()])),
45
46
  }).strict()
@@ -1,8 +1,8 @@
1
1
  // GenerateContent manual continuation contract (reviewed 2026-10-16):
2
2
  // https://ai.google.dev/gemini-api/docs/generate-content/long-decode#option-2-loop
3
3
  // https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/gemini-4-argon
4
- // Only checkpoint-confirmed chunks may escape a resumable stream. Never append
5
- // partial output to the request, decrease its total budget, or retry committed text.
4
+ // Stream chunks directly before the first 32K checkpoint token; once a checkpoint
5
+ // is active, only checkpoint-confirmed chunks escape. Never append partial output.
6
6
  import { SERVICE_TIERS, serviceTierFromHeader, serviceTierFromTraffic } from './service-level.js'
7
7
  import { classifyRequestRegion } from './pricing.js'
8
8
  export const MAX_CONTINUATION_HOPS = 32
@@ -65,7 +65,9 @@ const fields = ['promptTokenCount', 'cachedContentTokenCount', 'candidatesTokenC
65
65
  function readUsage(raw, previous) {
66
66
  const result = { ...previous }
67
67
  for (const key of fields) {
68
- if (Number.isSafeInteger(raw[key]) && raw[key] >= 0) result[key] = raw[key]
68
+ // Keep an explicit invalid count distinguishable from an omitted zero.
69
+ // The ledger records only its invalid marker, never the upstream bad value.
70
+ if (raw[key] !== undefined) result[key] = Number.isSafeInteger(raw[key]) && raw[key] >= 0 ? raw[key] : null
69
71
  }
70
72
  for (const key of ['promptTokensDetails', 'cacheTokensDetails', 'candidatesTokensDetails', 'toolUsePromptTokensDetails', 'trafficType']) {
71
73
  if (Object.hasOwn(raw, key)) result[key] = raw[key]
@@ -161,7 +163,7 @@ export async function continueArgonRequestStream(apiClient, original, request, m
161
163
  }
162
164
 
163
165
  const refreshOriginalUsage = () => {
164
- if ((initialPrompt === undefined || !startToken) && latestUsage?.promptTokenCount !== undefined) initialPrompt = latestUsage.promptTokenCount
166
+ if ((initialPrompt === undefined || !startToken) && Number.isSafeInteger(latestUsage?.promptTokenCount)) initialPrompt = latestUsage.promptTokenCount
165
167
  if ((initialCached === undefined || !startToken) && initialPrompt !== undefined) initialCached = value(latestUsage, 'cachedContentTokenCount')
166
168
  }
167
169
  const accountCommitted = () => {
@@ -182,9 +184,18 @@ export async function continueArgonRequestStream(apiClient, original, request, m
182
184
  const stream = await original.call(apiClient, { ...request, body, httpOptions })
183
185
  for await (const chunk of stream) {
184
186
  throwIfAborted(request.abortSignal)
185
- const raw = await chunk.json()
187
+ let raw
188
+ try {
189
+ raw = await chunk.json()
190
+ } catch (error) {
191
+ hopTracker?.onChunk({ status: 200 })
192
+ throw error
193
+ }
186
194
  tracker?.observeResponse?.('gc-chunk', hop, raw)
187
- if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw streamError('Invalid Argon stream response.', 'ARGON_INVALID_RESPONSE')
195
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
196
+ hopTracker?.onChunk({ status: 200 })
197
+ throw streamError('Invalid Argon stream response.', 'ARGON_INVALID_RESPONSE')
198
+ }
188
199
  if (Object.hasOwn(raw, 'error')) {
189
200
  hopTracker?.onChunk({ status: 200 })
190
201
  throw inBandStreamError(raw.error)
@@ -215,6 +226,11 @@ export async function continueArgonRequestStream(apiClient, original, request, m
215
226
  yield wrap(raw, chunk.headers, latestUsage)
216
227
  continue
217
228
  }
229
+ if (!token && !newCheckpoint && !terminal && candidate?.finishReason !== 'CONTINUATION') {
230
+ refreshOriginalUsage()
231
+ yield wrap(raw, chunk.headers, latestUsage)
232
+ continue
233
+ }
218
234
  pendingBytes += Buffer.byteLength(JSON.stringify(raw))
219
235
  if (pendingBytes > MAX_PENDING_BYTES) throw streamError('Argon uncommitted stream exceeded the bounded checkpoint buffer.', 'ARGON_BUFFER_LIMIT')
220
236
  pending.push({ raw, headers: chunk.headers, usage: latestUsage ? { ...latestUsage } : undefined })
@@ -267,9 +283,9 @@ export async function continueArgonRequestStream(apiClient, original, request, m
267
283
  if (!failure && finishReason === 'CONTINUATION' && (!token || token === startToken)) {
268
284
  failure = streamError('Argon CONTINUATION did not provide a new checkpoint token.', 'ARGON_INVALID_CONTINUATION')
269
285
  }
270
- if (failure && !retryable(failure)) {
286
+ if (!token || (failure && !retryable(failure))) {
271
287
  hopTracker?.finish({ error: failure, aborted: false, finishReason, continued: false })
272
- throw failure
288
+ throw failure ?? streamError('Argon stream ended without a terminal finishReason.')
273
289
  }
274
290
  const progress = token !== startToken
275
291
  const cleanContinuation = finishReason === 'CONTINUATION' && !failure && progress
package/index.js CHANGED
@@ -117,7 +117,7 @@ export function apply(ctx, config) {
117
117
  })
118
118
  const recordDiagnostic = record => hub.record(record)
119
119
  const adapter = createArgonAdapter(ctx, () => config, undefined, undefined, recordDiagnostic, taskHub, responseHub)
120
- const unpatchPiAi = installGemini4PiAiPatch(recordDiagnostic)
120
+ const unpatchPiAi = installGemini4PiAiPatch(recordDiagnostic, () => config, responseHub)
121
121
  const registration = ctx.llm.registerAdapter([PROVIDER], adapter)
122
122
  ctx.effect(() => () => {
123
123
  unpatchPiAi()
@@ -1,5 +1,5 @@
1
1
  import {estimateDiagnosticCost} from './pricing.js'
2
- import {USAGE_COUNT_KEYS} from './usage-details.js'
2
+ import {USAGE_COUNT_KEYS,resolveUsageCounts,selectGcUsageRows} from './usage-details.js'
3
3
 
4
4
  const knownCount=value=>Number.isSafeInteger(value)&&value>=0
5
5
  const knownMoney=value=>typeof value==='number'&&Number.isFinite(value)&&value>=0&&value<=Number.MAX_SAFE_INTEGER
@@ -18,9 +18,8 @@ function requestSources(record) {
18
18
  const details=record.usageDetails
19
19
  if(!details)return {rows:[],complete:false}
20
20
  if(record.protocol==='generate-content') {
21
- const rows=(details.rows??[]).filter(row=>row.kind==='gc-hop')
22
- const complete=finalOutcome(record.outcome)&&rows.length>0&&rows.length===record.hopCount&&details.omittedRows===0
23
- &&rows.every(row=>row.complete===true&&knownCount(row.index))&&new Set(rows.map(row=>row.index)).size===rows.length
21
+ const {rows,ledgerValid}=selectGcUsageRows(record)
22
+ const complete=finalOutcome(record.outcome)&&ledgerValid&&rows.every(row=>row.complete===true)
24
23
  return {rows,complete}
25
24
  }
26
25
  if(record.protocol==='interactions')return {rows:[{usage:details.aggregate}],complete:finalOutcome(record.outcome)&&details.aggregateComplete===true}
@@ -29,17 +28,18 @@ function requestSources(record) {
29
28
 
30
29
  function requestSummary(record) {
31
30
  const {rows,complete}=requestSources(record)
31
+ const usages=rows.map(row=>resolveUsageCounts(row.usage,record.protocol))
32
32
  const tokens=Object.fromEntries(USAGE_COUNT_KEYS.map(key=>{
33
- const known=rows.map(row=>row.usage?.[key]).filter(knownCount)
33
+ const known=usages.map(usage=>usage?.[key]).filter(knownCount)
34
34
  const subtotal=sumKnown(known,knownCount)
35
35
  return [key,{subtotal,reported:known.length>0,complete:complete&&known.length===rows.length&&subtotal!==null}]
36
36
  }))
37
- const cacheComplete=tokens.inputTokens.complete&&tokens.cachedTokens.complete
38
- &&rows.every(row=>row.usage.cachedTokens<=row.usage.inputTokens)
37
+ const cacheInvalid=usages.some(usage=>knownCount(usage?.inputTokens)&&knownCount(usage?.cachedTokens)&&usage.cachedTokens>usage.inputTokens)
38
+ const cacheComplete=tokens.inputTokens.complete&&tokens.cachedTokens.complete&&!cacheInvalid
39
39
  // Keep pricing in one place; a duplicate/invalid hop ledger still cannot be
40
40
  // promoted to a complete estimate even if its individual rows are priced.
41
41
  const cost=['generate-content','interactions'].includes(record.protocol)?estimateDiagnosticCost(record):null
42
- return {tokens,cacheComplete,cost, costComplete:complete&&knownMoney(cost?.estimatedUsd)}
42
+ return {tokens,cacheInvalid,cacheComplete,cost, costComplete:complete&&knownMoney(cost?.estimatedUsd)}
43
43
  }
44
44
 
45
45
  // The caller supplies filtered, bounded records, verified when answer-scoped.
@@ -52,19 +52,31 @@ export function summarizeRequestOverview(records,window={limit:20,limited:false}
52
52
  const completeRequests=requests.filter(request=>request.tokens[key].complete).length
53
53
  return [key,{knownSubtotal,reportedRequests:reported.length,completeRequests,complete:requestCount>0&&completeRequests===requestCount&&knownSubtotal!==null}]
54
54
  }))
55
- const cacheCompleteRequests=requests.filter(request=>request.cacheComplete).length
56
- const percent=requestCount>0&&cacheCompleteRequests===requestCount&&tokens.inputTokens.complete&&tokens.cachedTokens.complete&&tokens.inputTokens.knownSubtotal>0
57
- ?tokens.cachedTokens.knownSubtotal/tokens.inputTokens.knownSubtotal*100:null
55
+ const eligibleCache=requests.filter(request=>request.cacheComplete)
56
+ const cacheCompleteRequests=eligibleCache.length
57
+ const eligibleInput=sumKnown(eligibleCache.map(request=>request.tokens.inputTokens.subtotal),knownCount)
58
+ const eligibleCached=sumKnown(eligibleCache.map(request=>request.tokens.cachedTokens.subtotal),knownCount)
59
+ const cacheOverflow=requests.some(request=>(request.tokens.inputTokens.reported&&request.tokens.inputTokens.subtotal===null)||(request.tokens.cachedTokens.reported&&request.tokens.cachedTokens.subtotal===null))
60
+ const percent=cacheCompleteRequests>0&&!requests.some(request=>request.cacheInvalid)&&!cacheOverflow&&eligibleInput!==null&&eligibleCached!==null&&eligibleInput>0
61
+ ?eligibleCached/eligibleInput*100:null
58
62
  const reportedCosts=requests.filter(request=>knownMoney(request.cost?.knownSubtotalUsd))
59
63
  const costSum=sumKnown(reportedCosts.map(request=>request.cost.knownSubtotalUsd),knownMoney)
60
64
  // A numeric but unrepresentable source cost must not silently disappear.
61
65
  const invalidCost=requests.some(request=>request.cost?.knownSubtotalUsd!=null&&!knownMoney(request.cost.knownSubtotalUsd))
62
66
  const knownSubtotalUsd=invalidCost||costSum===null?null:Math.round(costSum*1e9)/1e9
63
67
  const completeRequests=requests.filter(request=>request.costComplete).length
64
- const starts=records.map(record=>record.startedAt).filter(value=>typeof value==='string').sort()
68
+ // One pass over the retained snapshot replaces a full copy plus sort.
69
+ let oldestAt=null,newestAt=null
70
+ for(const record of records){
71
+ const startedAt=record.startedAt
72
+ if(typeof startedAt==='string'){
73
+ if(oldestAt===null||startedAt<oldestAt)oldestAt=startedAt
74
+ if(newestAt===null||startedAt>newestAt)newestAt=startedAt
75
+ }
76
+ }
65
77
  return {
66
78
  requestCount,
67
- window:{limit:window.limit??20,retainedWindowLimit:200,limited:window.limited===true,oldestAt:starts[0]??null,newestAt:starts.at(-1)??null},
79
+ window:{limit:window.limit??20,retainedWindowLimit:200,limited:window.limited===true,oldestAt,newestAt},
68
80
  tokens,
69
81
  cache:{percent,completeRequests:cacheCompleteRequests},
70
82
  cost:{knownSubtotalUsd,estimatedUsd:requestCount>0&&completeRequests===requestCount?knownSubtotalUsd:null,reportedRequests:reportedCosts.length,completeRequests,billingVerified:false},
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-vertex-argon",
3
- "version": "1.5.1",
3
+ "version": "1.5.3",
4
4
  "description": "Gemini API and Vertex AI Argon for DSH: long decode, explicit service tiers, response and usage inspection, and estimated costs.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -129,6 +129,6 @@
129
129
  "registry": "https://registry.npmjs.org/"
130
130
  },
131
131
  "scripts": {
132
- "test": "node --experimental-transform-types --import ./test/host-loader.mjs --test test/*.test.mjs"
132
+ "test": "node --experimental-transform-types --import ./test/offline-guard.mjs --import ./test/host-loader.mjs --test test/*.test.mjs"
133
133
  }
134
134
  }
package/pricing.js CHANGED
@@ -1,3 +1,5 @@
1
+ import { resolveUsageCounts, selectGcUsageRows } from './usage-details.js'
2
+
1
3
  // Public price snapshots, not account billing data. All amounts are USD per 1M tokens.
2
4
  export const PRICE_SNAPSHOT = Object.freeze({
3
5
  version: 'argon-public-2026-10-18', verifiedAt: '2026-10-18',
@@ -35,7 +37,8 @@ export function resolvePublicPrice({ route, tier, regionClass, at, model = 'gemi
35
37
  basis: vertex && promotional ? 'published-after-promotional-credits' : 'published-token-prices' }
36
38
  }
37
39
 
38
- export function estimateUsageCost({ usage, complete = false, ...selection }) {
40
+ export function estimateUsageCost({ usage, protocol, complete = false, ...selection }) {
41
+ usage = resolveUsageCounts(usage, protocol)
39
42
  const price = resolvePublicPrice(selection)
40
43
  const missing = [], components = { inputUsd: null, cachedUsd: null, outputUsd: null }
41
44
  if (complete !== true) missing.push('usage-not-final')
@@ -61,7 +64,7 @@ export function estimateUsageCost({ usage, complete = false, ...selection }) {
61
64
  export function estimateDiagnosticCost(record) {
62
65
  const details=record.usageDetails, gc=record.protocol==='generate-content'
63
66
  const missing=[], rows=[]
64
- const selection={route:record.route,model:record.model,regionClass:record.regionClass,at:record.startedAt}
67
+ const selection={route:record.route,model:record.model,regionClass:record.regionClass,at:record.startedAt,protocol:record.protocol}
65
68
  const estimate=(usage,complete,observed,index) => {
66
69
  const receipt=observed ?? (gc ? null : record.serviceTier?.observed)
67
70
  const tier=receipt ?? record.serviceTier?.requested
@@ -71,9 +74,10 @@ export function estimateDiagnosticCost(record) {
71
74
  }
72
75
  if(!details) missing.push('usage-details')
73
76
  else if(gc) {
74
- for(const row of details.rows)if(row.kind==='gc-hop')estimate(row.usage,row.complete,row.observedServiceTier,row.index)
77
+ const {rows:gcRows,ledgerValid}=selectGcUsageRows(record)
78
+ for(const row of gcRows)estimate(row.usage,row.complete,row.observedServiceTier,row.index)
75
79
  if(details.omittedRows)missing.push('omitted-usage-rows')
76
- if(rows.length!==record.hopCount||rows.length===0)missing.push('incomplete-hop-ledger')
80
+ if(!ledgerValid||rows.length===0)missing.push('incomplete-hop-ledger')
77
81
  } else estimate(details.aggregate,details.aggregateComplete,record.serviceTier?.observed,0)
78
82
  if(!['done','max-tokens','tool-calls'].includes(record.outcome))missing.push('request-not-complete')
79
83
  for(const row of rows)for(const value of row.missing)if(!missing.includes(value))missing.push(value)
package/usage-details.js CHANGED
@@ -5,6 +5,52 @@ export const MAX_USAGE_ROWS = 256
5
5
  const count = value => Number.isSafeInteger(value) && value >= 0 ? value : null
6
6
  const object = value => value !== null && typeof value === 'object' && !Array.isArray(value)
7
7
 
8
+ // Shared read-time interpretation for new samples and legacy persisted nulls.
9
+ // Missing optional counters are zero only beside a valid base counter. Invalid
10
+ // wire values carry a durable marker so normalization cannot launder them to zero.
11
+ export function resolveUsageCounts(usage, protocol) {
12
+ if (!object(usage)) return null
13
+ const invalid = new Set(Array.isArray(usage.invalidCounts) ? usage.invalidCounts : [])
14
+ const result = Object.fromEntries(USAGE_COUNT_KEYS.map(key => [key, invalid.has(key) ? null : count(usage[key])]))
15
+ const absent = key => usage[key] == null && !invalid.has(key)
16
+ if (result.inputTokens !== null) {
17
+ for (const key of ['cachedTokens', 'toolTokens']) if (absent(key)) result[key] = 0
18
+ }
19
+ // GC may omit a zero candidate count (e.g. a tool-only response). Require
20
+ // a reported total that proves zero; never infer a positive output or input.
21
+ if (protocol === 'generate-content' && absent('outputTokens') && result.inputTokens !== null && result.totalTokens !== null && result.toolTokens !== null) {
22
+ const thoughts = absent('thoughtTokens') ? 0 : result.thoughtTokens
23
+ const accounted = thoughts === null ? null : result.inputTokens + result.toolTokens + thoughts
24
+ if (accounted !== null && count(accounted) !== null && accounted === result.totalTokens) result.outputTokens = 0
25
+ }
26
+ if (result.outputTokens !== null && absent('thoughtTokens')) result.thoughtTokens = 0
27
+ return result
28
+ }
29
+
30
+ export function selectGcUsageRows(record) {
31
+ const details = record?.usageDetails
32
+ const allRows = (details?.rows ?? []).filter(row => row?.kind === 'gc-hop')
33
+ const ledgerValid = allRows.length > 0 && allRows.length === record?.hopCount && details?.omittedRows === 0
34
+ && allRows.every(row => count(row.index) !== null) && new Set(allRows.map(row => row.index)).size === allRows.length
35
+ if (!ledgerValid) return { rows: allRows, ledgerValid: false }
36
+ const sorted = [...allRows].sort((a, b) => a.index - b.index)
37
+ const hops = Array.isArray(record?.hops) && !record?.hopsDropped ? record.hops : []
38
+ const byIndex = new Map(hops.filter(object).map(hop => [hop.hopIndex, hop]))
39
+ let start = 0
40
+ if (['done', 'max-tokens', 'tool-calls'].includes(record?.outcome) && sorted.every((row, i) => row.index === i + 1)) {
41
+ while (start + 1 < sorted.length) {
42
+ const row = sorted[start], hop = byIndex.get(row.index), next = byIndex.get(sorted[start + 1].index)
43
+ if (row.usage === null && row.complete === false
44
+ && hop && hop.trigger === (start === 0 ? 'initial' : 'retry-original')
45
+ && hop.usedContinuationToken === false && hop.chunkCount === 0 && hop.hasCheckpoint === false
46
+ && ['transport-error', 'api-error'].includes(hop.outcome)
47
+ && next && next.trigger === 'retry-original' && next.usedContinuationToken === false) start++
48
+ else break
49
+ }
50
+ }
51
+ return { rows: start > 0 ? sorted.slice(start) : allRows, ledgerValid: true }
52
+ }
53
+
8
54
  function modalities(raw, protocol) {
9
55
  if (!Array.isArray(raw) || raw.length > USAGE_MODALITIES.length) return null
10
56
  const result = [], seen = new Set()
@@ -26,6 +72,8 @@ export function normalizeUsageDetails(protocol, raw) {
26
72
  ? ['input_tokens_by_modality', 'cached_tokens_by_modality', 'output_tokens_by_modality', 'tool_use_tokens_by_modality']
27
73
  : ['promptTokensDetails', 'cacheTokensDetails', 'candidatesTokensDetails', 'toolUsePromptTokensDetails']
28
74
  const result = Object.fromEntries(USAGE_COUNT_KEYS.map((key, i) => [key, count(raw[keys[i]])]))
75
+ const invalidCounts = USAGE_COUNT_KEYS.filter((key, i) => raw[keys[i]] !== undefined && result[key] === null)
76
+ if (invalidCounts.length) result.invalidCounts = invalidCounts
29
77
  for (const [i, key] of USAGE_DETAIL_KEYS.entries()) result[key] = modalities(raw[arrays[i]], protocol)
30
78
  return result
31
79
  }