@iaziz786/cmd-footer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Aziz
+
+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/README.md

@@ -0,0 +1,93 @@
+# cmd-footer
+
+[Command Code](https://commandcode.ai) mod that puts cache hit ratio and decode
+throughput in the footer, next to the input panel.
+
+The footer segment looks like:
+
+```text
+cache last 99.5% | avg 97.8% | 250 t/s
+```
+
+| Segment | Meaning |
+|---|---|
+| `cache last` | Cache hit ratio of the last request: cache reads over prompt tokens |
+| `avg` | Session-wide ratio, weighted by tokens rather than averaged per request |
+| `t/s` | Decode rate of the last reply: output tokens over the stream window |
+
+`cache last` turns red when a request re-billed tokens that should have been
+cache reads, even when the ratio still looks healthy. A 99% request that
+re-reads 3k tokens shows red, because those tokens cost full price.
+
+Type `/cache` for the detailed line: token counts, request count, decode rate,
+and whether the last turn re-billed.
+
+## Install
+
+```bash
+cmd mods add npm:@iaziz786/cmd-footer
+```
+
+Or try it without installing:
+
+```bash
+cmd --mod ./src/cmd-footer.ts
+```
+
+## How the numbers are measured
+
+**Cache ratio.** `cacheReadTokens / inputTokens`. The AI SDK reports
+`inputTokens` as the whole prompt, with cache reads and writes already inside
+it, so the ratio is the cached share of that total.
+
+**Decode rate.** Output tokens over the span from the first streamed delta to
+the end of the response, so the wait for the first token is excluded. Three
+conditions make a measurement untrustworthy and the previous reading is kept
+instead:
+
+- fewer than 4 stream deltas, or a window shorter than 300ms: delivery could
+  not be observed as a stream
+- a rate above 400 t/s: a proxy buffered the reply and flushed it in one burst,
+  which compresses the window and invents impossible throughput
+
+**Miss detection.** A request re-billed when the prompt of the previous request
+was not read back from cache. Re-bills at or below 1024 tokens are treated as
+cache breakpoint granularity noise. A compaction clears the baseline, so
+freshly compacted content is not mistaken for a re-bill. Providers that never
+report caching never show a miss.
+
+The flag covers the whole run rather than a single request, because one prompt
+can take several model calls and an early call can miss while the last one
+hits.
+
+## Tuning
+
+The thresholds are exported constants in `src/cmd-footer.ts`:
+
+| Constant | Default | Effect |
+|---|---|---|
+| `MAX_PLAUSIBLE_RATE` | 400 | Raise it on faster hardware, or the rate stops updating |
+| `MISS_NOISE_FLOOR_TOKENS` | 1024 | Lower it to flag smaller re-bills |
+| `MIN_RATE_SPAN_MS` | 300 | Shortest window that can resolve a rate |
+| `MIN_RATE_CHUNKS` | 4 | Fewest deltas that count as a stream |
+
+## Persistence
+
+Totals survive `/reload` and resuming a session. One entry per run is written
+through the session API, so a restored session continues its average instead of
+starting over. A new session starts at zero.
+
+## Develop
+
+```bash
+bun test
+```
+
+## Publish
+
+Publishing runs on version tags. The tag must match `package.json`.
+
+```bash
+npm version patch
+git push --follow-tags
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@iaziz786/cmd-footer",
+	"version": "0.1.0",
+	"description": "Command Code mod that puts cache hit ratio and decode throughput in the footer.",
+	"keywords": ["command-code", "cmd", "mod", "footer", "cache", "tokens", "tps"],
+	"type": "module",
+	"license": "MIT",
+	"author": "Mohammad Aziz",
+	"homepage": "https://github.com/iAziz786/cmd-footer#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+ssh://git@github.com/iAziz786/cmd-footer.git"
+	},
+	"files": ["src", "README.md", "LICENSE"],
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"scripts": {
+		"test": "bun test",
+		"prepublishOnly": "bun test"
+	},
+	"commandcode": {
+		"mods": ["./src/cmd-footer.ts"]
+	}
+}

package/src/cmd-footer.ts

@@ -0,0 +1,449 @@
+import type {ModApi} from '@commandcode/harness';
+
+// Namespaced because session.getCustomEntries filters by customType alone, so
+// the type is the identity - it is not scoped per mod.
+export const CUSTOM_TYPE = 'cache-ratio/usage';
+
+export const DIM = '\u001b[2m';
+export const GREEN = '\u001b[32m';
+export const YELLOW = '\u001b[33m';
+export const RED = '\u001b[31m';
+export const CYAN = '\u001b[36m';
+export const RESET = '\u001b[0m';
+
+/** Fewer deltas than this over the window means delivery was bursty. */
+export const MIN_RATE_CHUNKS = 4;
+
+/** Spans shorter than this cannot resolve a decode rate. */
+export const MIN_RATE_SPAN_MS = 300;
+
+/**
+ * Public decode ceilings run a few hundred t/s; anything above is suspect.
+ * Raise this if a genuinely fast model starts showing a stale rate.
+ */
+export const MAX_PLAUSIBLE_RATE = 400;
+
+export interface RateWindow {
+	/** model_request_start timestamp: post-headers, pre-first-chunk. */
+	readonly startTs: number;
+	/** model_request_end timestamp. */
+	readonly endTs: number;
+	/** First delta timestamp; falls back to startTs when absent. */
+	readonly firstDeltaTs?: number;
+	/** Streamed delta events observed (text + thinking). */
+	readonly chunkCount: number;
+}
+
+interface UsageLike {
+	// AI SDK semantics: inputTokens is the prompt TOTAL. Cache read and cache
+	// write tokens are subsets of it, not additions to it.
+	readonly inputTokens?: number;
+	readonly cacheReadTokens?: number;
+	readonly cacheWriteTokens?: number;
+}
+
+/**
+ * Re-billed prompt tokens at or below this are cache breakpoint granularity
+ * noise, not a miss. Same floor pi's footer uses.
+ */
+export const MISS_NOISE_FLOOR_TOKENS = 1024;
+
+/** Previous request, the baseline a miss is judged against. */
+export interface PreviousRequest {
+	readonly promptTokens: number;
+	readonly reportedCache: boolean;
+}
+
+interface CacheTotals {
+	readonly cachedTokens: number;
+	readonly promptTokens: number;
+}
+
+interface CacheStat extends CacheTotals {
+	readonly ratio: number | null;
+}
+
+interface Snapshot {
+	readonly last: number | null;
+	readonly average: number | null;
+	readonly requests: number;
+	readonly cachedTokens: number;
+	readonly promptTokens: number;
+}
+
+interface CacheState {
+	readonly last: CacheStat | null;
+	readonly totals: CacheTotals;
+	readonly requests: number;
+}
+
+// The on-disk shape. Flat numbers only: the session file is append-only JSONL,
+// so a snapshot must survive being read back by a later process.
+interface PersistedState {
+	readonly cachedTokens: number;
+	readonly promptTokens: number;
+	readonly requests: number;
+	readonly lastCachedTokens: number;
+	readonly lastPromptTokens: number;
+}
+
+export function tokenCount(value: number | undefined): number {
+	return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+export function ratioOf(totals: CacheTotals): number | null {
+	return totals.promptTokens > 0
+		? totals.cachedTokens / totals.promptTokens
+		: null;
+}
+
+export function cacheStat(usage: UsageLike): CacheStat {
+	const cachedTokens = tokenCount(usage.cacheReadTokens);
+	const promptTokens = tokenCount(usage.inputTokens);
+	return {cachedTokens, promptTokens, ratio: ratioOf({cachedTokens, promptTokens})};
+}
+
+export function combine(totals: CacheTotals, next: CacheTotals): CacheTotals {
+	return {
+		cachedTokens: totals.cachedTokens + next.cachedTokens,
+		promptTokens: totals.promptTokens + next.promptTokens,
+	};
+}
+
+export function emptyState(): CacheState {
+	return {last: null, totals: {cachedTokens: 0, promptTokens: 0}, requests: 0};
+}
+
+export function applyRequest(state: CacheState, stat: CacheStat): CacheState {
+	return {
+		last: stat,
+		totals: combine(state.totals, stat),
+		requests: state.requests + 1,
+	};
+}
+
+export function snapshotOf(state: CacheState): Snapshot {
+	return {
+		last: state.last?.ratio ?? null,
+		average: ratioOf(state.totals),
+		requests: state.requests,
+		cachedTokens: state.last?.cachedTokens ?? 0,
+		promptTokens: state.last?.promptTokens ?? 0,
+	};
+}
+
+export function serializeState(state: CacheState): PersistedState {
+	return {
+		cachedTokens: state.totals.cachedTokens,
+		promptTokens: state.totals.promptTokens,
+		requests: state.requests,
+		lastCachedTokens: state.last?.cachedTokens ?? 0,
+		lastPromptTokens: state.last?.promptTokens ?? 0,
+	};
+}
+
+function nonNegative(value: unknown): number | null {
+	return typeof value === 'number' && Number.isFinite(value) && value >= 0
+		? value
+		: null;
+}
+
+// Restore is the one place that reads data written by an older process, so it
+// validates instead of trusting the shape.
+export function parseState(data: unknown): CacheState | null {
+	if (typeof data !== 'object' || data === null) return null;
+	const raw = data as Record<string, unknown>;
+
+	const cachedTokens = nonNegative(raw.cachedTokens);
+	const promptTokens = nonNegative(raw.promptTokens);
+	const requests = nonNegative(raw.requests);
+	const lastCached = nonNegative(raw.lastCachedTokens);
+	const lastPrompt = nonNegative(raw.lastPromptTokens);
+	if (
+		cachedTokens === null ||
+		promptTokens === null ||
+		requests === null ||
+		lastCached === null ||
+		lastPrompt === null
+	) {
+		return null;
+	}
+
+	const last: CacheStat | null =
+		lastPrompt > 0
+			? {
+					cachedTokens: lastCached,
+					promptTokens: lastPrompt,
+					ratio: ratioOf({cachedTokens: lastCached, promptTokens: lastPrompt}),
+				}
+			: null;
+
+	return {last, totals: {cachedTokens, promptTokens}, requests};
+}
+
+export function formatPercent(ratio: number | null): string {
+	return ratio === null ? 'n/a' : `${(ratio * 100).toFixed(1)}%`;
+}
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return String(count);
+	if (count < 1_000_000) return `${(count / 1000).toFixed(1)}k`;
+	return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+export function colorFor(ratio: number | null): string {
+	if (ratio === null) return DIM;
+	if (ratio >= 0.8) return GREEN;
+	if (ratio >= 0.5) return YELLOW;
+	return RED;
+}
+
+/**
+ * Decode throughput: output tokens over the span from the first streamed delta
+ * to the end of the response, so the wait for the first token is excluded.
+ *
+ * The span is only trustworthy when delivery was genuinely incremental. A proxy
+ * that buffers the whole reply and flushes it in one burst compresses the span
+ * toward zero and reports impossible rates, so those measurements are rejected
+ * instead of shown.
+ */
+export function computeTokenRate(
+	outputTokens: number,
+	window: RateWindow,
+): number | undefined {
+	if (outputTokens <= 0) return undefined;
+
+	const rateStartTs = window.firstDeltaTs ?? window.startTs;
+	const spanMs = window.endTs - rateStartTs;
+	if (window.chunkCount < MIN_RATE_CHUNKS || spanMs < MIN_RATE_SPAN_MS) {
+		return undefined;
+	}
+
+	const rate = outputTokens / (spanMs / 1000);
+	return Number.isFinite(rate) && rate <= MAX_PLAUSIBLE_RATE ? rate : undefined;
+}
+
+export function formatRate(rate: number | undefined): string | null {
+	return rate === undefined ? null : `${Math.round(rate)} t/s`;
+}
+
+/**
+ * A miss is previous-prompt tokens that should have been cache reads but were
+ * re-billed. Ported from pi's footer with one adaptation: there prompt tokens
+ * are `input + cacheRead + cacheWrite`, here `inputTokens` is already the total.
+ *
+ * Hits, the first request, and providers that never report caching are not
+ * misses. Small re-bills are noise, not misses.
+ */
+export function detectMiss(
+	previous: PreviousRequest | undefined,
+	usage: UsageLike,
+): boolean {
+	const promptTokens = tokenCount(usage.inputTokens);
+	if (!previous || promptTokens <= 0) return false;
+
+	const cacheRead = tokenCount(usage.cacheReadTokens);
+	const cacheWrite = tokenCount(usage.cacheWriteTokens);
+	// A zero-cache request only counts when caching was seen before: on a
+	// cache-read-only provider that is a total miss, while on a provider that
+	// has never reported caching it means nothing.
+	if (cacheRead + cacheWrite === 0 && !previous.reportedCache) return false;
+
+	// min() guards a shrunk context: a prompt that got smaller cannot have been
+	// re-billed beyond its own size.
+	return Math.min(previous.promptTokens, promptTokens) - cacheRead > MISS_NOISE_FLOOR_TOKENS;
+}
+
+export function nextPrevious(
+	usage: UsageLike,
+	reportedCache: boolean,
+): PreviousRequest | undefined {
+	const promptTokens = tokenCount(usage.inputTokens);
+	if (promptTokens <= 0) return undefined;
+	return {
+		promptTokens,
+		reportedCache:
+			reportedCache ||
+			tokenCount(usage.cacheReadTokens) + tokenCount(usage.cacheWriteTokens) > 0,
+	};
+}
+
+/** A miss outranks the ratio: a healthy percentage can still hide re-billed tokens. */
+export function lastColor(ratio: number | null, missed: boolean): string {
+	return missed ? RED : colorFor(ratio);
+}
+
+// The rate segment is omitted, not shown as 0, while no measurement exists:
+// "0 t/s" would claim the model is stalled rather than unknown.
+function rateSuffix(rate: number | undefined, color: boolean): string {
+	const text = formatRate(rate);
+	if (text === null) return '';
+	return color ? ` ${DIM}|${RESET} ${CYAN}${text}${RESET}` : ` | ${text}`;
+}
+
+export function plainStatus(
+	snapshot: Snapshot,
+	rate: number | undefined,
+	missed: boolean,
+): string {
+	return (
+		`cache last ${formatPercent(snapshot.last)} | avg ${formatPercent(snapshot.average)}` +
+		rateSuffix(rate, false) +
+		(missed ? ' | miss' : '')
+	);
+}
+
+// The footer renders through Ink's <Text>, which normalizes these codes instead
+// of stripping them. Headless hosts print notices to a log, so they get the
+// plain variant.
+export function statusLine(
+	snapshot: Snapshot,
+	rate: number | undefined,
+	missed: boolean,
+): string {
+	return (
+		`${DIM}cache${RESET} last ${lastColor(snapshot.last, missed)}${formatPercent(snapshot.last)}${RESET}` +
+		` ${DIM}| avg${RESET} ${colorFor(snapshot.average)}${formatPercent(snapshot.average)}${RESET}` +
+		rateSuffix(rate, true)
+	);
+}
+
+export function detailLine(
+	snapshot: Snapshot,
+	rate: number | undefined,
+	missed: boolean,
+): string {
+	if (snapshot.requests === 0) return 'No request yet this session.';
+	const speed = formatRate(rate);
+	return (
+		`cache hit last ${formatPercent(snapshot.last)} ` +
+		`(${formatTokens(snapshot.cachedTokens)}/${formatTokens(snapshot.promptTokens)} prompt tokens) | ` +
+		`avg ${formatPercent(snapshot.average)} over ${snapshot.requests} request(s)` +
+		(speed === null ? '' : ` | ${speed} decode`) +
+		(missed ? ' | cache miss in last turn' : '')
+	);
+}
+
+export default function (cmd: ModApi): void {
+	let state = emptyState();
+	let restored = false;
+	let dirty = false;
+
+	// Decode window for the request in flight. cmd streams text and thinking
+	// deltas; tool-call arguments arrive whole, so they contribute no deltas.
+	let stream: {startTs: number; firstDeltaTs?: number; chunkCount: number} | null = null;
+	let rate: number | undefined;
+
+	// Miss tracking. A run is cmd's user turn: one prompt, several requests. An
+	// early request can miss while the last one hits, so the flag lives for the
+	// run rather than per request.
+	let previous: PreviousRequest | undefined;
+	let missedThisRun = false;
+
+	const repaint = (): void => {
+		const snapshot = snapshotOf(state);
+		if (cmd.ui.capabilities.status) cmd.ui.setStatus(statusLine(snapshot, rate, missedThisRun));
+		else cmd.ui.notify(plainStatus(snapshot, rate, missedThisRun));
+	};
+
+	// Seeding is idempotent: session_start covers the normal path, and the first
+	// request covers a host that binds without firing it. Restoring must happen
+	// before any request is counted, or the totals restart from zero.
+	const restore = (): void => {
+		if (restored) return;
+		const store = cmd.session;
+		if (!store) return;
+		restored = true;
+
+		const entries = store.getCustomEntries({customType: CUSTOM_TYPE});
+		const parsed = parseState(entries.at(-1)?.data);
+		if (!parsed) return;
+
+		state = parsed;
+		// Rebuild the miss baseline so a reload can still judge the next request.
+		// reportedCache is approximated from the last ratio: a request with cache
+		// reads proves the provider reports caching.
+		if (state.last) {
+			previous = {
+				promptTokens: state.last.promptTokens,
+				reportedCache: state.last.cachedTokens > 0,
+			};
+		}
+		if (cmd.ui.capabilities.status) {
+			cmd.ui.setStatus(statusLine(snapshotOf(state), rate, missedThisRun));
+		}
+	};
+
+	cmd.on('session_start', restore);
+
+	cmd.on('run_start', () => {
+		missedThisRun = false;
+	});
+
+	// Context legitimately changed, so the next request is new content being
+	// billed, not the old prompt being re-billed.
+	cmd.on('compaction_done', () => {
+		previous = undefined;
+	});
+
+	cmd.on('model_request_start', () => {
+		stream = {startTs: Date.now(), chunkCount: 0};
+	});
+
+	const noteDelta = (): void => {
+		if (!stream) return;
+		stream.firstDeltaTs ??= Date.now();
+		stream.chunkCount += 1;
+	};
+
+	cmd.on('text_delta', noteDelta);
+	cmd.on('thinking_delta', noteDelta);
+
+	cmd.on('model_request_end', event => {
+		const usage = (event as {usage?: UsageLike}).usage;
+		if (!usage) return;
+		restore();
+
+		const open = stream;
+		stream = null;
+
+		if (detectMiss(previous, usage)) missedThisRun = true;
+		previous = nextPrevious(usage, previous?.reportedCache ?? false) ?? previous;
+
+		state = applyRequest(state, cacheStat(usage));
+		dirty = true;
+
+		// A window that cannot be trusted keeps the previous reading: dropping
+		// to nothing would read as a stall, when the truth is "unmeasurable".
+		if (open) {
+			const measured = computeTokenRate(tokenCount(usage.outputTokens), {
+				startTs: open.startTs,
+				endTs: Date.now(),
+				...open.firstDeltaTs === undefined ? {} : {firstDeltaTs: open.firstDeltaTs},
+				chunkCount: open.chunkCount,
+			});
+			if (measured !== undefined) rate = measured;
+		}
+
+		repaint();
+	});
+
+	// One entry per run, not per request: the latest snapshot is all a restore
+	// needs, and the session tree grows one row per message instead of one row
+	// per model call.
+	cmd.on('run_end', () => {
+		const store = cmd.session;
+		if (!store || !dirty) return;
+		dirty = false;
+		store.appendCustomEntry({
+			customType: CUSTOM_TYPE,
+			data: serializeState(state),
+		});
+	});
+
+	cmd.addCommand({
+		name: 'cache',
+		description: 'Cache hit ratio and decode rate: last request and session average',
+		handler: () => ({message: detailLine(snapshotOf(state), rate, missedThisRun)}),
+	});
+}