@moxxy/plugin-usage-stats 0.26.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { type Plugin } from '@moxxy/sdk';
+export interface BuildUsageStatsPluginOptions {
+    /** Override the on-disk aggregate path. Tests inject a tmp file here. */
+    readonly statsPath?: string;
+}
+/**
+ * Records cross-session token usage. On shutdown it folds THIS run's
+ * `provider_response` events by `<provider>/<model>` and merges the delta into
+ * `~/.moxxy/usage.json` — a forward-going aggregate the `/usage` panel renders
+ * and `/usage clear` resets.
+ *
+ * Resume-safe by construction: restored events are seeded into the log WITHOUT
+ * firing subscribers, and `onInit` runs after seeding. `onInit` records the
+ * highest restored event seq, and `onShutdown` folds only events with a
+ * strictly greater seq — the live suffix of this run. A session's usage is
+ * therefore counted exactly once — when it closes — never re-counted on resume,
+ * and the seq boundary stays correct even on a rebased mirror (baseSeq > 0).
+ *
+ * `/new`-safe: `Session.reset()` calls `log.clear()`, which restarts the
+ * authoritative seq stream at 0 WITHOUT re-firing `onInit`. Without reacting to
+ * that, the post-`/new` events (seqs 0,1,2…) would all fall at or below the
+ * pre-`/new` boundary and be silently dropped. We subscribe to the log's
+ * `onClear` and re-baseline the cursor to `null` so the post-`/new` suffix is
+ * folded from the new base.
+ *
+ * Flush-on-close means a hard kill (SIGKILL) drops the in-progress session's
+ * delta; that's the accepted trade-off for a single, contention-free write.
+ *
+ * Best-effort, never load-blocking: both hooks are internally fault-tolerant.
+ * A hostile or half-implemented reader (one whose `ofType`/`onClear` throws)
+ * degrades — init falls back to the fold-whole-suffix default and shutdown
+ * records nothing for the run — instead of rejecting the hook. This holds even
+ * when the hooks are invoked directly (outside the host's lifecycle dispatcher).
+ */
+export declare function buildUsageStatsPlugin(opts?: BuildUsageStatsPluginOptions): Plugin;
+export default buildUsageStatsPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,MAAM,EAEZ,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,4BAAiC,GAAG,MAAM,CA4FrF;AAmBD,eAAe,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,150 @@
+import { definePlugin, summarizeTokensByModel, } from '@moxxy/sdk';
+import { mergeUsageStats } from '@moxxy/core';
+/**
+ * Records cross-session token usage. On shutdown it folds THIS run's
+ * `provider_response` events by `<provider>/<model>` and merges the delta into
+ * `~/.moxxy/usage.json` — a forward-going aggregate the `/usage` panel renders
+ * and `/usage clear` resets.
+ *
+ * Resume-safe by construction: restored events are seeded into the log WITHOUT
+ * firing subscribers, and `onInit` runs after seeding. `onInit` records the
+ * highest restored event seq, and `onShutdown` folds only events with a
+ * strictly greater seq — the live suffix of this run. A session's usage is
+ * therefore counted exactly once — when it closes — never re-counted on resume,
+ * and the seq boundary stays correct even on a rebased mirror (baseSeq > 0).
+ *
+ * `/new`-safe: `Session.reset()` calls `log.clear()`, which restarts the
+ * authoritative seq stream at 0 WITHOUT re-firing `onInit`. Without reacting to
+ * that, the post-`/new` events (seqs 0,1,2…) would all fall at or below the
+ * pre-`/new` boundary and be silently dropped. We subscribe to the log's
+ * `onClear` and re-baseline the cursor to `null` so the post-`/new` suffix is
+ * folded from the new base.
+ *
+ * Flush-on-close means a hard kill (SIGKILL) drops the in-progress session's
+ * delta; that's the accepted trade-off for a single, contention-free write.
+ *
+ * Best-effort, never load-blocking: both hooks are internally fault-tolerant.
+ * A hostile or half-implemented reader (one whose `ofType`/`onClear` throws)
+ * degrades — init falls back to the fold-whole-suffix default and shutdown
+ * records nothing for the run — instead of rejecting the hook. This holds even
+ * when the hooks are invoked directly (outside the host's lifecycle dispatcher).
+ */
+export function buildUsageStatsPlugin(opts = {}) {
+    // Boundary tracked by event SEQ, not by index/length. `log.length` is a count
+    // of held events while `log.slice(from)` is SEQ-addressed; the two only
+    // coincide on a base-0 log. On a rebased mirror (baseSeq > 0, e.g. partial
+    // replay), a length-as-seq cursor would clamp to the base and re-fold the
+    // entire restored prefix, double-counting usage. Capturing the highest seq
+    // restored at init and folding only events with a strictly greater seq is
+    // base-independent. `null` (no onInit, or a post-`/new` re-baseline) folds the
+    // whole log — the documented suffix-from-base default.
+    //
+    // Keyed by sessionId so one shared plugin instance stays correct across
+    // multiple sessions (the runner/thin-client model hosts many in one process);
+    // a single scalar would let one session's onInit clobber another's cursor.
+    // The map self-cleans in onShutdown, so it cannot grow unbounded.
+    const cursors = new Map();
+    // Per-session `onClear` unsubscribers, so we tear the listener down on
+    // shutdown rather than leaking one per init.
+    const clearUnsubs = new Map();
+    return definePlugin({
+        name: '@moxxy/plugin-usage-stats',
+        hooks: {
+            onInit(ctx) {
+                // Usage stats are a best-effort, non-load-blocking layer: a hostile or
+                // half-implemented reader (e.g. one whose `ofType`/`onClear` throws)
+                // must NEVER take down init.
+                //
+                // The two steps are isolated so a failure in one can't poison the other.
+                // The boundary is the load-bearing correctness value: if `onClear`
+                // registration throws AFTER a valid boundary was computed, we must KEEP
+                // that boundary — discarding it (resetting to `null`) would re-fold the
+                // whole restored prefix on shutdown and DOUBLE-COUNT the resumed
+                // session's usage into the lifetime aggregate. A failed boundary
+                // computation, by contrast, falls back to `null` (the documented
+                // fold-whole-suffix default) so the run is still counted, just from base.
+                try {
+                    cursors.set(ctx.sessionId, boundarySeq(ctx.log));
+                }
+                catch {
+                    cursors.set(ctx.sessionId, null);
+                }
+                try {
+                    const extras = ctx.log;
+                    if (typeof extras.onClear === 'function') {
+                        // Replace any stale listener from a prior init of the same session id.
+                        clearUnsubs.get(ctx.sessionId)?.();
+                        const unsub = extras.onClear(() => {
+                            // `clear()` reset the seq stream to base 0; fold the post-wipe
+                            // suffix from the start rather than against the now-stale boundary.
+                            cursors.set(ctx.sessionId, null);
+                        });
+                        clearUnsubs.set(ctx.sessionId, unsub);
+                    }
+                }
+                catch {
+                    // No `/new` re-baseline wired for this run — the boundary captured
+                    // above still stands. A session that never clears is unaffected; one
+                    // that does would over-count the post-`/new` suffix, the lesser evil
+                    // versus crashing init or dropping the boundary.
+                }
+            },
+            async onShutdown(ctx) {
+                // Tear down the per-session state first and unconditionally, so a later
+                // throw in the fold/merge can't strand the `onClear` listener or leave a
+                // cursor in the map (which would otherwise grow unbounded under a hosting
+                // model that reuses one instance across many sessions).
+                try {
+                    clearUnsubs.get(ctx.sessionId)?.();
+                }
+                catch {
+                    // An unsubscribe that throws must not block the merge below.
+                }
+                clearUnsubs.delete(ctx.sessionId);
+                const initMaxSeq = cursors.has(ctx.sessionId) ? cursors.get(ctx.sessionId) : null;
+                cursors.delete(ctx.sessionId);
+                // Best-effort: a throwing reader or a failed fold degrades to "record
+                // nothing for this run" rather than rejecting the hook (which the host
+                // would log as a spurious failure). `mergeUsageStats` already swallows
+                // its own write errors; this guards the read/fold side too.
+                try {
+                    // Only `provider_response` events carry token usage; scan that indexed
+                    // subset (O(matches)) instead of copying + filtering the full event log
+                    // (O(total session events)) on this 5s-timeboxed shutdown path.
+                    const responses = ctx.log.ofType('provider_response');
+                    const live = initMaxSeq === null ? responses : responses.filter((e) => e.seq > initMaxSeq);
+                    if (live.length === 0)
+                        return;
+                    const delta = summarizeTokensByModel(live);
+                    await mergeUsageStats(delta, opts.statsPath);
+                }
+                catch {
+                    // Drop this run's usage rather than crash shutdown — explicitly the
+                    // accepted trade-off for an optional, contention-free aggregate.
+                }
+            },
+        },
+    });
+}
+/**
+ * Highest held seq — the resume boundary — without copying the log. Prefers the
+ * O(1) `baseSeq + length - 1` identity (every held event has `seq === base +
+ * index`); falls back to scanning the indexed `provider_response` subset when a
+ * reader doesn't expose `baseSeq`. `null` for an empty log. Using the response
+ * subset for the fallback is sound: `onShutdown` only folds responses, so a
+ * boundary at the max restored response seq still excludes every restored
+ * response and includes every live one.
+ */
+function boundarySeq(log) {
+    if (log.length === 0)
+        return null;
+    if (typeof log.baseSeq === 'number')
+        return log.baseSeq + log.length - 1;
+    let max = null;
+    for (const e of log.ofType('provider_response'))
+        if (max === null || e.seq > max)
+            max = e.seq;
+    return max;
+}
+export default buildUsageStatsPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@moxxy/plugin-usage-stats",
+  "version": "0.26.0",
+  "description": "Records cross-session token usage. On session close it folds this run's provider_response events by provider/model and merges the delta into ~/.moxxy/usage.json (a forward-going aggregate surfaced in the /usage panel and reset by /usage clear).",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "usage",
+    "tokens",
+    "stats"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-usage-stats"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "hooks"
+    }
+  },
+  "dependencies": {
+    "@moxxy/core": "0.26.0",
+    "@moxxy/sdk": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,457 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  asEventId,
+  asSessionId,
+  asTurnId,
+  type AppContext,
+  type EventLogReader,
+  type MoxxyEvent,
+} from '@moxxy/sdk';
+import { loadUsageStats } from '@moxxy/core';
+import { buildUsageStatsPlugin } from './index.js';
+
+const sid = asSessionId('s1');
+const tid = asTurnId('t1');
+
+function resp(seq: number, model: string, inputTokens: number): MoxxyEvent {
+  return {
+    id: asEventId(`e${seq}`),
+    seq,
+    ts: seq,
+    sessionId: sid,
+    turnId: tid,
+    source: 'system',
+    type: 'provider_response',
+    provider: 'anthropic',
+    model,
+    inputTokens,
+    outputTokens: 1,
+  } as MoxxyEvent;
+}
+
+function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {
+  // Faithfully model the real EventLog: `length` is a COUNT of held events,
+  // while `slice(from)`/`at(seq)` are SEQ-addressed (translated through the
+  // log's base). On a rebased mirror the held events' seqs start above 0.
+  const base = events.length > 0 ? events[0]!.seq : 0;
+  return {
+    length: events.length,
+    at: (seq: number) => events[seq - base],
+    slice: (from = base, to = base + events.length) =>
+      events.slice(Math.max(0, from - base), Math.max(0, to - base)),
+    ofType: ((type: string) => events.filter((e) => e.type === type)) as EventLogReader['ofType'],
+    byTurn: (turnId) => events.filter((e) => e.turnId === turnId),
+    toJSON: () => events,
+  };
+}
+
+function ctxFor(events: ReadonlyArray<MoxxyEvent>): AppContext {
+  return { sessionId: sid, cwd: '/tmp', log: reader(events), env: {} };
+}
+
+/**
+ * A stateful fake that mirrors the real `EventLog`'s clear semantics: holding
+ * events with a base seq, exposing `baseSeq` + `onClear`, and on `clear()`
+ * emptying the events AND resetting `base` to 0 while firing clear listeners —
+ * exactly the `/new` (`Session.reset()`) lifecycle that restarts the seq stream.
+ */
+class FakeLog {
+  private events: MoxxyEvent[];
+  private base: number;
+  private readonly clearListeners = new Set<() => void>();
+  constructor(seed: ReadonlyArray<MoxxyEvent> = []) {
+    this.events = [...seed];
+    this.base = seed.length > 0 ? seed[0]!.seq : 0;
+  }
+  get length() {
+    return this.events.length;
+  }
+  get baseSeq() {
+    return this.base;
+  }
+  at(seq: number) {
+    return this.events[seq - this.base];
+  }
+  slice(from = this.base, to = this.base + this.events.length) {
+    return this.events.slice(Math.max(0, from - this.base), Math.max(0, to - this.base));
+  }
+  ofType(type: string) {
+    return this.events.filter((e) => e.type === type);
+  }
+  byTurn(turnId: unknown) {
+    return this.events.filter((e) => e.turnId === turnId);
+  }
+  toJSON() {
+    return this.events;
+  }
+  onClear(fn: () => void) {
+    this.clearListeners.add(fn);
+    return () => this.clearListeners.delete(fn);
+  }
+  /** Test-only: how many clear listeners are currently registered. Lets a test
+   * assert the plugin actually tears its `onClear` subscription down on shutdown
+   * (no leaked listener under a one-instance-many-sessions host). */
+  get clearListenerCount() {
+    return this.clearListeners.size;
+  }
+  /** Append more live events after `onInit` has captured the boundary. */
+  push(...more: MoxxyEvent[]) {
+    this.events.push(...more);
+  }
+  /** `/new` wipe: empty events, reset base to 0, fire clear listeners. */
+  clear() {
+    this.events = [];
+    this.base = 0;
+    for (const fn of [...this.clearListeners]) fn();
+  }
+}
+
+function ctxForLog(log: FakeLog, sessionId = sid): AppContext {
+  return { sessionId, cwd: '/tmp', log: log as unknown as EventLogReader, env: {} };
+}
+
+let tmpDir: string;
+let statsPath: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-usage-plugin-'));
+  statsPath = path.join(tmpDir, 'usage.json');
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('usage-stats plugin', () => {
+  it('folds the whole session for a fresh (non-resumed) run', async () => {
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const events = [resp(0, 'opus', 100), resp(1, 'opus', 50)];
+
+    await plugin.hooks!.onInit!(ctxFor([])); // boots with empty log
+    await plugin.hooks!.onShutdown!(ctxFor(events));
+
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.calls).toBe(2);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(150);
+  });
+
+  it('skips restored events on resume and folds only the live suffix', async () => {
+    const restored = [resp(0, 'opus', 1000), resp(1, 'opus', 2000)];
+    const liveSuffix = [resp(2, 'opus', 30)];
+    const plugin = buildUsageStatsPlugin({ statsPath });
+
+    // onInit fires after restored events are already seeded into the log.
+    await plugin.hooks!.onInit!(ctxFor(restored));
+    // onShutdown sees restored + live.
+    await plugin.hooks!.onShutdown!(ctxFor([...restored, ...liveSuffix]));
+
+    const file = await loadUsageStats(statsPath);
+    // Only the single live call (30 tokens) is counted — not the 3000 restored.
+    expect(file.models['anthropic/opus']!.calls).toBe(1);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(30);
+  });
+
+  it('writes nothing when no live events were produced', async () => {
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    await plugin.hooks!.onInit!(ctxFor([resp(0, 'opus', 100)]));
+    await plugin.hooks!.onShutdown!(ctxFor([resp(0, 'opus', 100)]));
+    // No new events past the cursor → file never created.
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+
+  it('counts only live events on a rebased mirror (baseSeq > 0), not the restored prefix', async () => {
+    // A partial-replay mirror primes the log with restored events at seqs that
+    // start above 0. A length-as-seq cursor would clamp to the base and re-fold
+    // the entire restored prefix, double-counting. Tracking the boundary by seq
+    // is base-independent.
+    const restored = [resp(100, 'opus', 1000), resp(101, 'opus', 2000), resp(102, 'opus', 4000)];
+    const liveSuffix = [resp(103, 'opus', 30)];
+    const plugin = buildUsageStatsPlugin({ statsPath });
+
+    await plugin.hooks!.onInit!(ctxFor(restored));
+    await plugin.hooks!.onShutdown!(ctxFor([...restored, ...liveSuffix]));
+
+    const file = await loadUsageStats(statsPath);
+    // Only the single live call (30 tokens) — never the 7000 restored tokens.
+    expect(file.models['anthropic/opus']!.calls).toBe(1);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(30);
+  });
+
+  it('counts the post-/new (log clear/reset) suffix that restarts at seq 0', async () => {
+    // Regression: `Session.reset()` (the `/new` flow) calls `log.clear()`, which
+    // empties the events AND resets base to 0 — restarting the authoritative seq
+    // stream WITHOUT re-firing onInit. A boundary captured at init (e.g. 102 from
+    // a restored prefix) would then drop every post-/new event (seqs 0,1,2…),
+    // silently losing the whole session's usage. The plugin must re-baseline on
+    // clear and fold the post-wipe suffix.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const log = new FakeLog([resp(100, 'opus', 1000), resp(101, 'opus', 2000)]);
+
+    await plugin.hooks!.onInit!(ctxForLog(log)); // boundary captured at seq 101
+    log.clear(); // /new — events emptied, base reset to 0, onClear fires
+    log.push(resp(0, 'opus', 40), resp(1, 'opus', 60)); // post-/new live events
+
+    await plugin.hooks!.onShutdown!(ctxForLog(log));
+
+    const file = await loadUsageStats(statsPath);
+    // Both post-/new calls counted (100 tokens) — not dropped as <= old boundary.
+    expect(file.models['anthropic/opus']!.calls).toBe(2);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(100);
+  });
+
+  it('isolates the cursor per session so concurrent sessions on one instance never clobber each other', async () => {
+    // One shared plugin instance, two interleaved session lifecycles. A single
+    // scalar cursor would let session B's onInit overwrite session A's boundary;
+    // keying by sessionId keeps both correct.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const sidA = asSessionId('A');
+    const sidB = asSessionId('B');
+    const logA = new FakeLog([resp(0, 'opus', 1000)]); // A restored 1 event (seq 0)
+    const logB = new FakeLog([]); // B is a fresh run
+
+    await plugin.hooks!.onInit!(ctxForLog(logA, sidA)); // A boundary = 0
+    await plugin.hooks!.onInit!(ctxForLog(logB, sidB)); // B boundary = null (would clobber A's scalar)
+
+    logA.push(resp(1, 'opus', 5)); // A's single live call
+    logB.push(resp(0, 'opus', 7)); // B's single live call
+
+    await plugin.hooks!.onShutdown!(ctxForLog(logA, sidA));
+    await plugin.hooks!.onShutdown!(ctxForLog(logB, sidB));
+
+    const file = await loadUsageStats(statsPath);
+    // A counts only its live call (5), B counts its only call (7) → 2 calls, 12.
+    expect(file.models['anthropic/opus']!.calls).toBe(2);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(12);
+  });
+
+  it('folds the whole log when onShutdown fires without a preceding onInit (cursor defaults to null)', async () => {
+    // Documents the deliberate null-cursor default: the "counted exactly once on
+    // resume" guarantee hinges on onInit running first to capture the restored
+    // prefix length. On an abnormal lifecycle (onShutdown with no onInit) the
+    // cursor is absent → treated as null → the entire log is folded — accepted
+    // behavior, asserted here so a future guard change is a conscious one.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const events = [resp(0, 'opus', 100), resp(1, 'opus', 50)];
+
+    await plugin.hooks!.onShutdown!(ctxFor(events)); // no onInit called
+
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.calls).toBe(2);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(150);
+  });
+
+  it('onShutdown degrades to a no-op (resolves, writes nothing) when the reader throws', async () => {
+    // Worst case: a hostile/half-implemented reader whose `ofType` throws on the
+    // 5s-timeboxed shutdown path. The plugin must swallow it — usage stats are an
+    // optional, best-effort layer — and resolve instead of rejecting the hook
+    // (which the host would log as a spurious failure). No file is written.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const hostile = {
+      length: 1,
+      at: () => undefined,
+      slice: () => [],
+      ofType: () => {
+        throw new Error('reader exploded');
+      },
+      byTurn: () => [],
+      toJSON: () => [],
+    } as unknown as EventLogReader;
+    const ctx = { sessionId: sid, cwd: '/tmp', log: hostile, env: {} } as AppContext;
+
+    await expect(plugin.hooks!.onShutdown!(ctx)).resolves.toBeUndefined();
+    // Nothing folded → file never created.
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+
+  it('onInit degrades gracefully when boundarySeq/onClear throw, still counting the run', async () => {
+    // A reader that throws from `ofType` (the boundarySeq fallback) AND from
+    // `onClear` at init time must not crash init. The cursor falls back to null
+    // (fold-whole-suffix default), so a subsequent shutdown with a WORKING reader
+    // still records the run rather than silently losing it.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const throwingInit = {
+      length: 3, // non-empty → boundarySeq won't early-return; no baseSeq → hits ofType
+      at: () => undefined,
+      slice: () => [],
+      ofType: () => {
+        throw new Error('ofType exploded at init');
+      },
+      byTurn: () => [],
+      toJSON: () => [],
+      onClear: () => {
+        throw new Error('onClear exploded at init');
+      },
+    } as unknown as EventLogReader;
+    const initCtx = { sessionId: sid, cwd: '/tmp', log: throwingInit, env: {} } as AppContext;
+
+    // onInit is synchronous; it must not throw despite ofType + onClear both
+    // throwing. (`Promise.resolve` tolerates the sync void return.)
+    expect(() => plugin.hooks!.onInit!(initCtx)).not.toThrow();
+
+    // Now shut down with a healthy reader: null cursor folds the whole log.
+    await plugin.hooks!.onShutdown!(ctxFor([resp(0, 'opus', 10), resp(1, 'opus', 20)]));
+
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.calls).toBe(2);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(30);
+  });
+
+  it('onShutdown tears down the onClear listener even when the fold/merge path throws (no leak)', async () => {
+    // The unsubscribe + map deletes must run before (and regardless of) the
+    // fold/merge, so a throwing reader can't strand the onClear listener or leave
+    // the cursor map growing unbounded under a one-instance-many-sessions host.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    let unsubscribed = false;
+    let throwFromOfType = false;
+    const log = {
+      length: 0,
+      at: () => undefined,
+      slice: () => [],
+      ofType: () => {
+        if (throwFromOfType) throw new Error('shutdown reader exploded');
+        return [];
+      },
+      byTurn: () => [],
+      toJSON: () => [],
+      onClear: () => () => {
+        unsubscribed = true;
+      },
+    } as unknown as EventLogReader;
+    const ctx = { sessionId: sid, cwd: '/tmp', log, env: {} } as AppContext;
+
+    await plugin.hooks!.onInit!(ctx); // registers the clear listener (ofType ok: empty log path)
+    throwFromOfType = true; // now the fold path will throw on shutdown
+    await expect(plugin.hooks!.onShutdown!(ctx)).resolves.toBeUndefined();
+    // Listener was unsubscribed despite the fold throwing → no leak.
+    expect(unsubscribed).toBe(true);
+  });
+
+  it('degrades to a no-op when the reader returns a non-array from ofType (not just when it throws)', async () => {
+    // Worst case beyond a throwing reader: a half-implemented/hostile reader
+    // whose `ofType` returns garbage (a number, null) instead of an array. The
+    // plugin does `responses.filter(...)`, which raises a TypeError on a
+    // non-array — it must be swallowed by the same best-effort guard, resolving
+    // the hook and writing nothing rather than crashing the timeboxed shutdown.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    for (const bogus of [42, null, 'nope', { length: 1 }] as unknown[]) {
+      const garbageReader = {
+        length: 1,
+        at: () => undefined,
+        slice: () => [],
+        ofType: () => bogus,
+        byTurn: () => [],
+        toJSON: () => [],
+      } as unknown as EventLogReader;
+      const ctx = { sessionId: sid, cwd: '/tmp', log: garbageReader, env: {} } as AppContext;
+      await expect(plugin.hooks!.onShutdown!(ctx)).resolves.toBeUndefined();
+    }
+    // No call ever produced a fold-able array → file never created.
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+
+  it('onShutdown for a session that never ran onInit folds the whole log and leaves no leaked state', async () => {
+    // Abnormal lifecycle on a SHARED instance: onShutdown arrives for a session
+    // id the plugin never saw onInit for (absent cursor → treated as null →
+    // whole-log fold). It must not throw on the map.delete of an absent key, and
+    // a SECOND shutdown for the same id must behave identically (idempotent,
+    // never resurrecting a stale cursor) — proving the map self-cleans even on
+    // the no-onInit path so it can't grow unbounded under a many-sessions host.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const events = [resp(0, 'opus', 100)];
+
+    await expect(plugin.hooks!.onShutdown!(ctxFor(events))).resolves.toBeUndefined();
+    // A repeat shutdown re-folds the same whole log (cursor still absent → null),
+    // so it must not throw; the aggregate doubles, which is the documented
+    // whole-log-fold default, asserted so a future guard change is deliberate.
+    await expect(plugin.hooks!.onShutdown!(ctxFor(events))).resolves.toBeUndefined();
+
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.calls).toBe(2);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(200);
+  });
+
+  it('a re-init of the same session id replaces (does not stack) the onClear listener', async () => {
+    // Worst case under a host that re-dispatches onInit for the same session id
+    // without an intervening onShutdown (e.g. a buggy/abnormal lifecycle, or a
+    // resume that re-inits). Each init must REPLACE the prior onClear listener,
+    // not add a second one — otherwise listeners would accumulate (a leak) and a
+    // single clear() would fire stale closures. We assert the real FakeLog only
+    // ever holds one listener across repeated inits, and exactly zero after
+    // shutdown.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const log = new FakeLog([resp(0, 'opus', 10)]);
+
+    await plugin.hooks!.onInit!(ctxForLog(log));
+    await plugin.hooks!.onInit!(ctxForLog(log));
+    await plugin.hooks!.onInit!(ctxForLog(log));
+    expect(log.clearListenerCount).toBe(1); // replaced each time, never stacked
+
+    await plugin.hooks!.onShutdown!(ctxForLog(log));
+    expect(log.clearListenerCount).toBe(0); // fully torn down
+  });
+
+  it('preserves a valid resume boundary when onClear registration throws (no double-count)', async () => {
+    // Regression: `boundarySeq` succeeds (a clean restored prefix, seqs 100..102)
+    // but the reader's `onClear` registration throws. The boundary is the
+    // load-bearing correctness value — it must SURVIVE the onClear failure.
+    // Discarding it (resetting the cursor to null) would re-fold the entire
+    // restored prefix on shutdown and DOUBLE-COUNT 7000 restored tokens into the
+    // lifetime aggregate. Only the single live call (30) may be counted.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const restored = [resp(100, 'opus', 1000), resp(101, 'opus', 2000), resp(102, 'opus', 4000)];
+    const onClearThrows = {
+      length: restored.length,
+      baseSeq: 100, // boundarySeq takes the O(1) path → 100 + 3 - 1 = 102
+      at: () => undefined,
+      slice: () => [],
+      ofType: ((type: string) =>
+        type === 'provider_response' ? restored : []) as EventLogReader['ofType'],
+      byTurn: () => [],
+      toJSON: () => restored,
+      onClear: () => {
+        throw new Error('onClear registration exploded');
+      },
+    } as unknown as EventLogReader;
+    const initCtx = { sessionId: sid, cwd: '/tmp', log: onClearThrows, env: {} } as AppContext;
+
+    expect(() => plugin.hooks!.onInit!(initCtx)).not.toThrow();
+    // Shut down with restored prefix + one live call. The preserved boundary (102)
+    // must exclude every restored response and include only the live one.
+    await plugin.hooks!.onShutdown!(ctxFor([...restored, resp(103, 'opus', 30)]));
+
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.calls).toBe(1);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(30); // not 7030
+  });
+
+  it('actually tears down the real onClear listener on shutdown (no leaked subscription)', async () => {
+    // The prior "no leak" test used a hand-rolled fake whose unsubscribe just
+    // flipped a flag; it could not prove the real subscription was removed. Here
+    // the stateful FakeLog tracks live listeners, so we assert the count returns
+    // to zero after shutdown — and that a post-shutdown clear() can't resurrect a
+    // cursor entry by firing a stale listener.
+    const plugin = buildUsageStatsPlugin({ statsPath });
+    const log = new FakeLog([resp(0, 'opus', 100)]);
+
+    await plugin.hooks!.onInit!(ctxForLog(log));
+    expect(log.clearListenerCount).toBe(1); // listener registered
+
+    log.push(resp(1, 'opus', 50));
+    await plugin.hooks!.onShutdown!(ctxForLog(log));
+    expect(log.clearListenerCount).toBe(0); // torn down — no leak
+
+    // A clear() now fires no plugin listener; a second shutdown sees an absent
+    // cursor (null) and folds the (post-clear, empty) log → still no crash.
+    log.clear();
+    await expect(plugin.hooks!.onShutdown!(ctxForLog(log))).resolves.toBeUndefined();
+
+    const file = await loadUsageStats(statsPath);
+    // Only the first run's live call (50) — the restored 100 was excluded, and
+    // the post-shutdown clear added nothing.
+    expect(file.models['anthropic/opus']!.calls).toBe(1);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(50);
+  });
+});

package/src/index.ts

@@ -0,0 +1,169 @@
+import {
+  definePlugin,
+  summarizeTokensByModel,
+  type EventLogReader,
+  type Plugin,
+  type SessionId,
+} from '@moxxy/sdk';
+import { mergeUsageStats } from '@moxxy/core';
+
+export interface BuildUsageStatsPluginOptions {
+  /** Override the on-disk aggregate path. Tests inject a tmp file here. */
+  readonly statsPath?: string;
+}
+
+/**
+ * Optional capabilities the concrete `EventLog` exposes beyond the
+ * `EventLogReader` contract. `ctx.log` is the live `EventLog` at runtime
+ * (`Session.appContext()` hands us `log.asReader()`, which returns the log
+ * itself), so we duck-type these. A reader that lacks them (e.g. a test fake)
+ * just degrades to the contract-only path — never crashes.
+ */
+interface EventLogExtras {
+  /** Seq of the first held event; lets us compute the boundary in O(1). */
+  readonly baseSeq?: number;
+  /** Fires after `clear()`/`/new` empties the log and restarts seqs at 0. */
+  onClear?(fn: () => void): () => void;
+}
+
+/**
+ * Records cross-session token usage. On shutdown it folds THIS run's
+ * `provider_response` events by `<provider>/<model>` and merges the delta into
+ * `~/.moxxy/usage.json` — a forward-going aggregate the `/usage` panel renders
+ * and `/usage clear` resets.
+ *
+ * Resume-safe by construction: restored events are seeded into the log WITHOUT
+ * firing subscribers, and `onInit` runs after seeding. `onInit` records the
+ * highest restored event seq, and `onShutdown` folds only events with a
+ * strictly greater seq — the live suffix of this run. A session's usage is
+ * therefore counted exactly once — when it closes — never re-counted on resume,
+ * and the seq boundary stays correct even on a rebased mirror (baseSeq > 0).
+ *
+ * `/new`-safe: `Session.reset()` calls `log.clear()`, which restarts the
+ * authoritative seq stream at 0 WITHOUT re-firing `onInit`. Without reacting to
+ * that, the post-`/new` events (seqs 0,1,2…) would all fall at or below the
+ * pre-`/new` boundary and be silently dropped. We subscribe to the log's
+ * `onClear` and re-baseline the cursor to `null` so the post-`/new` suffix is
+ * folded from the new base.
+ *
+ * Flush-on-close means a hard kill (SIGKILL) drops the in-progress session's
+ * delta; that's the accepted trade-off for a single, contention-free write.
+ *
+ * Best-effort, never load-blocking: both hooks are internally fault-tolerant.
+ * A hostile or half-implemented reader (one whose `ofType`/`onClear` throws)
+ * degrades — init falls back to the fold-whole-suffix default and shutdown
+ * records nothing for the run — instead of rejecting the hook. This holds even
+ * when the hooks are invoked directly (outside the host's lifecycle dispatcher).
+ */
+export function buildUsageStatsPlugin(opts: BuildUsageStatsPluginOptions = {}): Plugin {
+  // Boundary tracked by event SEQ, not by index/length. `log.length` is a count
+  // of held events while `log.slice(from)` is SEQ-addressed; the two only
+  // coincide on a base-0 log. On a rebased mirror (baseSeq > 0, e.g. partial
+  // replay), a length-as-seq cursor would clamp to the base and re-fold the
+  // entire restored prefix, double-counting usage. Capturing the highest seq
+  // restored at init and folding only events with a strictly greater seq is
+  // base-independent. `null` (no onInit, or a post-`/new` re-baseline) folds the
+  // whole log — the documented suffix-from-base default.
+  //
+  // Keyed by sessionId so one shared plugin instance stays correct across
+  // multiple sessions (the runner/thin-client model hosts many in one process);
+  // a single scalar would let one session's onInit clobber another's cursor.
+  // The map self-cleans in onShutdown, so it cannot grow unbounded.
+  const cursors = new Map<SessionId, number | null>();
+  // Per-session `onClear` unsubscribers, so we tear the listener down on
+  // shutdown rather than leaking one per init.
+  const clearUnsubs = new Map<SessionId, () => void>();
+  return definePlugin({
+    name: '@moxxy/plugin-usage-stats',
+    hooks: {
+      onInit(ctx) {
+        // Usage stats are a best-effort, non-load-blocking layer: a hostile or
+        // half-implemented reader (e.g. one whose `ofType`/`onClear` throws)
+        // must NEVER take down init.
+        //
+        // The two steps are isolated so a failure in one can't poison the other.
+        // The boundary is the load-bearing correctness value: if `onClear`
+        // registration throws AFTER a valid boundary was computed, we must KEEP
+        // that boundary — discarding it (resetting to `null`) would re-fold the
+        // whole restored prefix on shutdown and DOUBLE-COUNT the resumed
+        // session's usage into the lifetime aggregate. A failed boundary
+        // computation, by contrast, falls back to `null` (the documented
+        // fold-whole-suffix default) so the run is still counted, just from base.
+        try {
+          cursors.set(ctx.sessionId, boundarySeq(ctx.log));
+        } catch {
+          cursors.set(ctx.sessionId, null);
+        }
+        try {
+          const extras = ctx.log as EventLogReader & EventLogExtras;
+          if (typeof extras.onClear === 'function') {
+            // Replace any stale listener from a prior init of the same session id.
+            clearUnsubs.get(ctx.sessionId)?.();
+            const unsub = extras.onClear(() => {
+              // `clear()` reset the seq stream to base 0; fold the post-wipe
+              // suffix from the start rather than against the now-stale boundary.
+              cursors.set(ctx.sessionId, null);
+            });
+            clearUnsubs.set(ctx.sessionId, unsub);
+          }
+        } catch {
+          // No `/new` re-baseline wired for this run — the boundary captured
+          // above still stands. A session that never clears is unaffected; one
+          // that does would over-count the post-`/new` suffix, the lesser evil
+          // versus crashing init or dropping the boundary.
+        }
+      },
+      async onShutdown(ctx) {
+        // Tear down the per-session state first and unconditionally, so a later
+        // throw in the fold/merge can't strand the `onClear` listener or leave a
+        // cursor in the map (which would otherwise grow unbounded under a hosting
+        // model that reuses one instance across many sessions).
+        try {
+          clearUnsubs.get(ctx.sessionId)?.();
+        } catch {
+          // An unsubscribe that throws must not block the merge below.
+        }
+        clearUnsubs.delete(ctx.sessionId);
+        const initMaxSeq = cursors.has(ctx.sessionId) ? cursors.get(ctx.sessionId)! : null;
+        cursors.delete(ctx.sessionId);
+        // Best-effort: a throwing reader or a failed fold degrades to "record
+        // nothing for this run" rather than rejecting the hook (which the host
+        // would log as a spurious failure). `mergeUsageStats` already swallows
+        // its own write errors; this guards the read/fold side too.
+        try {
+          // Only `provider_response` events carry token usage; scan that indexed
+          // subset (O(matches)) instead of copying + filtering the full event log
+          // (O(total session events)) on this 5s-timeboxed shutdown path.
+          const responses = ctx.log.ofType('provider_response');
+          const live =
+            initMaxSeq === null ? responses : responses.filter((e) => e.seq > initMaxSeq);
+          if (live.length === 0) return;
+          const delta = summarizeTokensByModel(live);
+          await mergeUsageStats(delta, opts.statsPath);
+        } catch {
+          // Drop this run's usage rather than crash shutdown — explicitly the
+          // accepted trade-off for an optional, contention-free aggregate.
+        }
+      },
+    },
+  });
+}
+
+/**
+ * Highest held seq — the resume boundary — without copying the log. Prefers the
+ * O(1) `baseSeq + length - 1` identity (every held event has `seq === base +
+ * index`); falls back to scanning the indexed `provider_response` subset when a
+ * reader doesn't expose `baseSeq`. `null` for an empty log. Using the response
+ * subset for the fallback is sound: `onShutdown` only folds responses, so a
+ * boundary at the max restored response seq still excludes every restored
+ * response and includes every live one.
+ */
+function boundarySeq(log: EventLogReader & EventLogExtras): number | null {
+  if (log.length === 0) return null;
+  if (typeof log.baseSeq === 'number') return log.baseSeq + log.length - 1;
+  let max: number | null = null;
+  for (const e of log.ofType('provider_response')) if (max === null || e.seq > max) max = e.seq;
+  return max;
+}
+
+export default buildUsageStatsPlugin;