agentus 0.15.3 → 0.15.4

package/README.md

@@ -57,7 +57,7 @@ background process comes back as a turn of its own), an **ACP session that write
 cockpit-side failure is diagnosable afterwards), and a **DeepSeek web backend** (search +
 extract on the model key) — come from the fork's integration build instead. That is a five-line install:
 [§ Which Hermes to run](docs/installation.md#which-hermes-to-run) — currently the tag
-`agentus/v0.22.0/merge-20261026-1237`, on Hermes `v0.22.0`.
+`agentus/v0.22.0/merge-20261028-1850`, on Hermes `v0.22.0`.
 
 The first slot you start will use the Hermes home **your own agent already uses**
 (`~/.hermes`) unless the backend row names another one — see "HERMES_HOME" below.

package/README.zh-CN.md

@@ -51,7 +51,7 @@ web bundle、配套 APK —— 然后直接退出，不启动任何东西）。
 以及 **DeepSeek 的 web 后端**（搜索 + 正文抓取，共用模型 key）—— 来自 fork 的集成构建（tag）。
 装法就五行：
 [§ 该跑哪份 Hermes](docs/installation.zh-CN.md#该跑哪份-hermes) —— 当前是 tag
-`agentus/v0.22.0/merge-20261026-1237`，基座 Hermes `v0.22.0`。
+`agentus/v0.22.0/merge-20261028-1850`，基座 Hermes `v0.22.0`。
 
 你启动的第一个 slot 会使用**你自己的 agent 已经在用的**那个 Hermes home（`~/.hermes`），除非后端那一行
 指定了另一个 —— 见下面的「HERMES_HOME」。

package/docs/installation.md

@@ -60,7 +60,7 @@ ref and gets rebuilt, while a tag never moves — so pin the tag. The `agentus/`
 ours apart from upstream's own tags (`v0.22.0`, `v0.22.0+canary.*`), and the timestamp in the
 last segment sorts, so "newest" is a `sort -V`.
 
-**Current integration build: `agentus/v0.22.0/merge-20261026-1237`** — the newest tag on the fork,
+**Current integration build: `agentus/v0.22.0/merge-20261028-1850`** — the newest tag on the fork,
 built on Hermes `v0.22.0`. This line is for orientation only, not the source of truth: the
 `TAG=$(…)` step below resolves the newest one on every run, so read it there if this sentence
 ever looks stale.

package/docs/installation.zh-CN.md

@@ -52,7 +52,7 @@ agentus/<hermes 内部版本>/merge-<YYYYMMDD-HHMM>
 tag。`agentus/` 这个前缀也把它和上游自己的 tag（`v0.22.0`、`v0.22.0+canary.*`）分开；最后一段是时间戳，
 可排序，所以「最新」就是一次 `sort -V`。
 
-**当前集成构建：`agentus/v0.22.0/merge-20261026-1237`** —— fork 上最新的那个 tag，基座 Hermes
+**当前集成构建：`agentus/v0.22.0/merge-20261028-1850`** —— fork 上最新的那个 tag，基座 Hermes
 `v0.22.0`。这行只为一眼看个大概，不是权威：下面的 `TAG=$(…)` 每次都会自己解析出最新，觉得这行过期就
 以它为准。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentus",
-  "version": "0.15.3",
-  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence \u2014 the agent lives in spawned CLI subprocesses.",
+  "version": "0.15.4",
+  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/packages/server/mock/agent.mjs

@@ -949,17 +949,23 @@ const agent = () => ({
       used: s.used,
       size: picked > 0 ? picked : Number(process.env.MOCK_USAGE_SIZE || 200_000),
     });
-    // The prompt response's `usage`, shaped like the hermes adapter's (issue #70). ACP's semantics
-    // are "Total … across all turns", so the counters ACCUMULATE on the session state — a cockpit
-    // that forgot to diff would show the whole conversation on every turn, and a two-turn QA sweep
-    // is what proves it does not. `cachedWriteTokens` is filled too, because the fork's adapter
-    // still omits it and the cockpit must not depend on that omission.
+    // The prompt response's `usage`, shaped like the hermes adapter's (issue #70, #71). ACP's
+    // semantics are "Total … across all turns", so the counters ACCUMULATE on the session state —
+    // a cockpit that forgot to diff would show the whole conversation on every turn, and a
+    // two-turn QA sweep is what proves it does not.
+    //
+    // Issue #71: `inputTokens` is the FULL prompt — hermes fills it from `prompt_tokens`, which
+    // its own accounting defines as fresh input + cache read + cache write. The mock therefore
+    // adds the cache buckets INTO the input counter, exactly as the real adapter does: a mock that
+    // kept them separate would let the old 「input + read + write」 denominator stay green.
+    // `cachedWriteTokens` is filled too, because the fork's adapter still omits it and the cockpit
+    // must not depend on that omission.
     const outChars = words.join(" ").length + MOCK_MARKDOWN.length;
     s.tokens = s.tokens || {
       totalTokens: 0, inputTokens: 0, outputTokens: 0, thoughtTokens: 0,
       cachedReadTokens: 0, cachedWriteTokens: 0,
     };
-    s.tokens.inputTokens += text.length + 200;
+    s.tokens.inputTokens += text.length + 200 + 4096 + 128;
     s.tokens.cachedReadTokens += 4096;
     s.tokens.cachedWriteTokens += 128;
     s.tokens.outputTokens += Math.ceil(outChars / 4);

package/packages/server/src/acp/session-manager.ts

@@ -3574,27 +3574,44 @@ export function turnUsageOf(
     input: input ?? 0,
     output: output ?? 0,
     thought: thought ?? 0,
-    cacheRead: cacheRead ?? 0,
-    cacheWrite: cacheWrite ?? 0,
+    // issue #71: never `?? 0` here — the baseline is also what a persisted session reloads, and a
+    // washed-in 0 is indistinguishable from a measured zero on the next diff.
+    cacheRead,
+    cacheWrite,
   };
   const delta = (now: number, before: number | undefined): number =>
     (before === undefined ? now : now >= before ? now - before : now);
+  // Issue #71: a bucket the agent never reports stays NULL through the bill. 「写 0」 reads as
+  // "this turn's cache writes were measured at zero", and cache writes are the billed kind
+  // (Anthropic 1.25×). Omission is the honest shape; see tokens.ts. A null BASELINE means the
+  // first reported value is the turn's own — undefined and null never had a prior count.
+  const deltaOpt = (now: number | null, before: number | null | undefined): number | null =>
+    (now === null ? null : delta(now, before ?? undefined));
+  // Computed up front: the hit rate below divides by THIS turn's prompt delta, not the raw one.
+  const billInput = delta(cur.input, base?.input);
+  const billCacheRead = deltaOpt(cur.cacheRead, base?.cacheRead);
   const bill: TurnUsage = {
     total: delta(cur.total, base?.total),
-    input: delta(cur.input, base?.input),
+    input: billInput,
     output: delta(cur.output, base?.output),
     thought: delta(cur.thought, base?.thought),
-    cacheRead: delta(cur.cacheRead, base?.cacheRead),
-    cacheWrite: delta(cur.cacheWrite, base?.cacheWrite),
+    cacheRead: billCacheRead,
+    cacheWrite: deltaOpt(cur.cacheWrite, base?.cacheWrite),
     durationMs,
-    // Webui's denominator: the FULL prompt = input + cache read + cache write. Only when the agent
-    // reports a cache bucket at all — otherwise the page says 「未上报」, not a 0% hit rate.
+    // Issue #71 — the denominator is this turn's prompt total, i.e. the billed `input` DELTA.
+    // ACP's Usage.inputTokens is the FULL prompt (hermes' adapter fills it with `prompt_tokens`,
+    // which by definition = fresh input + cache read + cache write; see agent/usage_pricing.py in
+    // the fork), so the cache buckets are a SUBSET of input, not peers beside it. Adding them
+    // back counted every cached token twice and pinned the reading at cacheRead/(input+cacheRead)
+    // ≈ 50% for any cache-heavy session — the exact defect #71 measured (real hits 91–100%, page
+    // 50%). webui keeps one invariant across both of its sources: the denominator is a number
+    // that already IS the full prompt (api/models.py passes input_tokens alone); its additive
+    // form exists only for a rollup that stored uncached input separately. We read the first
+    // source, so no addition. `min(100, …)` stays as a clamp against a skewed diff, never as the
+    // thing that makes the ratio believable: with correct semantics normal data cannot exceed 100.
     cacheHitPercent: cacheRead === null && cacheWrite === null
       ? null
-      : (() => {
-        const prompt = (input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
-        return prompt > 0 ? Math.min(100, Math.round(((cacheRead ?? 0) / prompt) * 100)) : null;
-      })(),
+      : (billInput > 0 ? Math.min(100, Math.round(((billCacheRead ?? 0) / billInput) * 100)) : null),
   };
   // Average speed: this turn's OWN output over wall time (tool calls included, so a long tool
   // turn honestly reads slow rather than being dressed up as model speed).

package/packages/shared/src/index.ts

@@ -140,29 +140,34 @@ export interface UsageView {
   totals?: UsageTotals | null;
 }
 
-/** Cumulative token buckets a turn's usage is measured against (ACP `Usage`). */
+/** Cumulative token buckets a turn's usage is measured against (ACP `Usage`).
+ *  `cacheRead`/`cacheWrite` are null = the agent never reports that bucket (issue #71); a
+ *  baseline of null diffs the first REPORTED value as the turn's own, same as undefined. */
 export interface UsageTotals {
   total: number;
   input: number;
   output: number;
   thought: number;
-  cacheRead: number;
-  cacheWrite: number;
+  cacheRead: number | null;
+  cacheWrite: number | null;
 }
 
 /** One turn's token bill (issue #70) — the DELTA of the agent's cumulative counters.
  *
- *  `cacheHitPercent` uses the webui's definition (prompt cache reads over the full prompt total:
- *  input + cache read + cache write), and is null when the agent reports no cache buckets at all —
- *  a Qoder session must read as unavailable, not as a 0% hit rate. `tps` is the turn AVERAGE
+ *  `cacheHitPercent` is cacheRead / input, where ACP's `inputTokens` is ALREADY the full prompt
+ *  (fresh + cache read + cache write — issue #71; do not add the buckets back, it counts cached
+ *  tokens twice and pins the reading near 50%). Null when the agent reports no cache buckets at
+ *  all — a Qoder session must read as unavailable, not as a 0% hit rate. `tps` is the turn AVERAGE
  *  (output tokens over wall time, tool calls included); it is deliberately labelled as an average
  *  rather than sold as instantaneous speed. */
 export interface TurnUsage {
   input: number;
   output: number;
   thought: number;
-  cacheRead: number;
-  cacheWrite: number;
+  /** NULL = the agent never reports this bucket (issue #71). A reported 0 is a real 0 — the
+   *  two must not collapse into one number, or 「写 0」 lies about cache writes (1.25× billed). */
+  cacheRead: number | null;
+  cacheWrite: number | null;
   total: number;
   durationMs?: number;
   cacheHitPercent?: number | null;