agentus 0.15.1 → 0.15.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentus",
-  "version": "0.15.1",
-  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
+  "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.",
   "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,23 @@ 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). 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.
+    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.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,65 @@ 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,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+  };
+  const delta = (now: number, before: number | undefined): number =>
+    (before === undefined ? now : now >= before ? now - before : now);
+  const bill: TurnUsage = {
+    total: delta(cur.total, base?.total),
+    input: delta(cur.input, base?.input),
+    output: delta(cur.output, base?.output),
+    thought: delta(cur.thought, base?.thought),
+    cacheRead: delta(cur.cacheRead, base?.cacheRead),
+    cacheWrite: delta(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.
+    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;
+      })(),
+  };
+  // 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,41 @@ 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`). */
+export interface UsageTotals {
+  total: number;
+  input: number;
+  output: number;
+  thought: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** 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
+ *  (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;
+  total: number;
+  durationMs?: number;
+  cacheHitPercent?: number | null;
+  tps?: number | null;
 }
 
 export interface SessionModeState {
@@ -228,7 +263,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 +529,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;