agentus 0.15.2 → 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.2",
-  "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",
@@ -92,7 +92,9 @@
     "tus-mode-sweep": "node scripts/qa/tus-mode-sweep.mjs",
     "usage-row-sweep": "node scripts/qa/usage-row-sweep.mjs",
     "call-brief-sweep": "node scripts/qa/call-brief-sweep.mjs",
-    "reply-on-done": "node scripts/qa/reply-on-done.mjs"
+    "reply-on-done": "node scripts/qa/reply-on-done.mjs",
+    "turn-usage": "tsx scripts/qa/turn-usage.mts",
+    "turn-usage-sweep": "node scripts/qa/turn-usage-sweep.mjs"
   },
   "engines": {
     "node": ">=22.5"

package/packages/server/mock/agent.mjs

@@ -949,7 +949,29 @@ const agent = () => ({
       used: s.used,
       size: picked > 0 ? picked : Number(process.env.MOCK_USAGE_SIZE || 200_000),
     });
-    return { stopReason: "end_turn" };
+    // 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 + 4096 + 128;
+    s.tokens.cachedReadTokens += 4096;
+    s.tokens.cachedWriteTokens += 128;
+    s.tokens.outputTokens += Math.ceil(outChars / 4);
+    s.tokens.thoughtTokens += 32;
+    s.tokens.totalTokens = s.tokens.inputTokens + s.tokens.outputTokens + s.tokens.thoughtTokens;
+    return { stopReason: "end_turn", usage: s.tokens };
   },
 });
 

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

@@ -49,6 +49,8 @@ import type {
   SessionModeState,
   StatusNoteItem,
   TurnTrace,
+  TurnUsage,
+  UsageTotals,
 } from "../../../shared/src/index.js";
 import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, clampTitle, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
 import { PLAN_GUIDANCE_ACTIVE, PLAN_GUIDANCE_INTRO, PLAN_GUIDANCE_NATIVE } from "../../../shared/src/index.js";
@@ -1564,13 +1566,30 @@ export class SessionManager {
       // The agent has the block (a cancelled turn still received it): NOW the boundary is spent.
       settleVoice();
       this.#finalizePlan(sessionId, terminalState);
-      // Turn END is the second and last ordering event of a turn (issue #50): start moved the session,
-      // this settles it where the conversation now is. Mid-turn rows deliberately do NOT touch — see
-      // #touch.
+      const durationMs = Date.now() - turnStartedAt;
+      // issue #70: the agent's CUMULATIVE token counters arrive on the prompt RESPONSE — a frame
+      // nothing else reads — so the per-turn bill and the cache-hit rate were simply thrown away.
+      // One row per turn, at the tail of the reply it bills: persisted, because a reload must show
+      // the same numbers (the agent will never re-send them), and it sits AFTER the reply by seq.
+      const bill = turnUsageOf(res?.usage, s.info.usage?.totals ?? null, durationMs);
+      if (bill) {
+        s.info.usage = {
+          ...(s.info.usage ?? { used: 0, size: 0, cost: null, at: Date.now() }),
+          totals: bill.totals,
+          at: Date.now(),
+        };
+      }
       this.#touch(s);
-      this.#emit({ t: "turn-end", sessionId, stopReason: res?.stopReason, durationMs: Date.now() - turnStartedAt });
+      const usageRow = this.#store.appendMessage({
+        sessionId,
+        kind: "turn-usage",
+        payload: bill ? bill.bill : { available: false, durationMs },
+        createdAt: Date.now(),
+      });
+      this.#emit({ t: "message", message: usageRow });
+      this.#emit({ t: "turn-end", sessionId, stopReason: res?.stopReason, durationMs, ...(bill ? { usage: bill.bill } : {}) });
       // #59: 谁在等这一轮结束（跨会话 send --reply-on-done）
-      this.#settleTurnReplies(sessionId, mine, { stopReason: res?.stopReason ?? null, durationMs: Date.now() - turnStartedAt });
+      this.#settleTurnReplies(sessionId, mine, { stopReason: res?.stopReason ?? null, durationMs });
     } catch (err) {
       this.#finalizePlan(sessionId, "failed");
       this.#touch(s);
@@ -2654,6 +2673,10 @@ export class SessionManager {
           size: Number.isFinite(size) ? size : 0,
           cost: uu.cost && typeof uu.cost.amount === "number" ? uu.cost.amount : null,
           at: Date.now(),
+          // issue #70: this frame carries NO token breakdown, so the cumulative baseline that the
+          // per-turn bills are subtracted from must survive it — replacing the object wholesale is
+          // what would make the next bill report the whole session again.
+          ...(live.info.usage?.totals ? { totals: live.info.usage.totals } : {}),
         };
         this.#updateSession(live);
         this.#emit({ t: "usage", sessionId: live.info.id, usage: live.info.usage });
@@ -3520,6 +3543,82 @@ function normConfigOptions(raw: unknown): ConfigOptionView[] {
     });
 }
 
+/** One turn's token bill, from the agent's CUMULATIVE counters (issue #70).
+ *
+ *  ACP documents `PromptResponse.usage` as "Total … across all turns", so a turn's number is a
+ *  subtraction against the baseline kept beside the context gauge (`UsageView.totals`). Three
+ *  deliberate rules:
+ *  · a bucket the agent did not report stays ABSENT — a Qoder session must read 「未上报」, never a
+ *    made-up zero;
+ *  · a total that SHRANK means the agent's counters reset (a resumed process): the raw value is
+ *    then this turn's own number and the baseline resets, instead of emitting a negative bill;
+ *  · a turn that reported nothing at all returns null (the row still says 「未上报」).
+ *  The FIRST bill of a session that predates this baseline is therefore cumulative — one turn of
+ *  honest over-reporting beats inventing a difference. */
+export function turnUsageOf(
+  raw: unknown, base: UsageTotals | null | undefined, durationMs: number,
+): { bill: TurnUsage; totals: UsageTotals } | null {
+  const u = (raw && typeof raw === "object" ? raw : null) as Record<string, unknown> | null;
+  if (!u) return null;
+  const num = (v: unknown): number | null =>
+    (typeof v === "number" && Number.isFinite(v) ? Math.max(0, Math.round(v)) : null);
+  const total = num(u.totalTokens);
+  const input = num(u.inputTokens);
+  const output = num(u.outputTokens);
+  const thought = num(u.thoughtTokens);
+  const cacheRead = num(u.cachedReadTokens);
+  const cacheWrite = num(u.cachedWriteTokens);
+  if ([total, input, output, thought, cacheRead, cacheWrite].every((x) => x === null)) return null;
+  const cur: UsageTotals = {
+    total: total ?? (input ?? 0) + (output ?? 0),
+    input: input ?? 0,
+    output: output ?? 0,
+    thought: thought ?? 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: billInput,
+    output: delta(cur.output, base?.output),
+    thought: delta(cur.thought, base?.thought),
+    cacheRead: billCacheRead,
+    cacheWrite: deltaOpt(cur.cacheWrite, base?.cacheWrite),
+    durationMs,
+    // 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
+      : (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).
+  bill.tps = bill.output > 0 && durationMs > 0 ? Math.round((bill.output / (durationMs / 1000)) * 10) / 10 : null;
+  return { bill, totals: cur };
+}
+
 function errMessage(e: unknown): string {
   if (e && typeof e === "object" && "message" in e) return String((e as { message: unknown }).message);
   return String(e);

package/packages/shared/src/index.ts

@@ -132,6 +132,46 @@ export interface UsageView {
   size: number;
   cost?: number | null;
   at: number;
+  /** SESSION-CUMULATIVE token counters from `PromptResponse.usage`, as the agent reported them
+   *  (ACP's own semantics: "Total ... across all turns"). Kept beside the context gauge because
+   *  that is the only place a reload can learn them again — `usage_update` carries no token
+   *  breakdown, and the per-turn numbers are differences of these. Absent = the agent never
+   *  reported any (Qoder), which reads as "not available", NEVER as measured zero. */
+  totals?: UsageTotals | null;
+}
+
+/** 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 | null;
+  cacheWrite: number | null;
+}
+
+/** One turn's token bill (issue #70) — the DELTA of the agent's cumulative counters.
+ *
+ *  `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;
+  /** 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;
+  tps?: number | null;
 }
 
 export interface SessionModeState {
@@ -228,7 +268,10 @@ export type ServerEvent =
       /** Wall time from the moment the turn was announced to the moment the agent answered (ms).
        *  Exists so a notification can say "用时 1m12s" instead of a protocol token like `end_turn`,
        *  which is a fact about the wire, not about the operator's wait (absent when unknowable). */
-      durationMs?: number }
+      durationMs?: number;
+      /** What this turn cost in tokens (issue #70), subtracted from the agent's cumulative
+       *  counters. Absent when the agent reports none — the page then says 「未上报」, never 0. */
+      usage?: TurnUsage | null }
   /** per-turn trace: what model/effort/mode this turn is actually running with
    *  (AionUi F-DISPLAY-11 lineage — "why did it behave differently?" ) */
   /** `pid` is the id of the prompt that started this turn, copied from the client's command (issue
@@ -491,8 +534,11 @@ export interface StoredMessage {
    *  `approval` = an approval request as a transcript row (it asks a question, then carries the
    *  decision), and `project-skills` = the agent reporting that this repo ships skills it is NOT
    *  loading. Both are DUrable on purpose: a modal that vanishes leaves no record of what was
-   *  asked or what was answered. */
-  kind: "user" | "agent" | "thought" | "tool" | "plan" | "meta" | "note" | "approval" | "project-skills";
+   *  asked or what was answered. `turn-usage` = one turn's token bill (issue #70): it is written at
+   *  turn-end, so it sits at the TAIL of the reply it bills, and it is persisted because a reload
+   *  must show the same numbers instead of losing the one part of the turn the agent will never
+   *  re-send. */
+  kind: "user" | "agent" | "thought" | "tool" | "plan" | "meta" | "note" | "approval" | "project-skills" | "turn-usage";
   payload: unknown; // raw ACP content/update fragment (kept lossless)
   toolCallId?: string; // set for kind=tool; upsert key
   createdAt: number;