@wierdbytes/pi-facelift 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.6.3
+
+- **New:** `tps` (output tokens/sec) next to the working timer — live `~`-prefixed estimate from streamed deltas and exact final from `usage.output`.
+
 ## 0.6.2
 
 - **Fix:** live `Working...` timer now uses the same duration format as the history line (`1m5s` instead of `65s`).

package/README.md

@@ -41,16 +41,21 @@ tool output.
 
   [cd]: ../common/README.md#diff
 - **working timer** — while the model streams, the `Working...` spinner
-  line gains a live ticking timer (`Working... 12s`). When the run
-  settles, a muted line is left behind in chat history (a durable custom
-  entry, not sent to the LLM) reporting two numbers:
+  line gains a live ticking timer and a token-rate estimate
+  (`Working... 12s · tps: ~756`). When the run settles, a muted line is
+  left behind in chat history (a durable custom entry, not sent to the
+  LLM):
 
-  `⏱ worked 45.2s (total: 1m15s)`
+  `⏱ worked 45.2s (total: 1m15s) · tps: 756`
 
   - `worked` — model-only time (request dispatch → response end, so
     time-to-first-token counts; tool execution is excluded).
   - `total` — wall-clock time from your prompt to the final response,
     including retries, tool calls, and all other overhead.
+  - `tps` — output tokens per second over the `worked` time. The live
+    value is an estimate from streamed deltas (~4 chars ≈ 1 token) and is
+    prefixed with `~`; the final value is exact, from the provider's
+    reported `usage.output`.
 
   Durations auto-format as `1h12m36s` — leading zero parts are dropped
   (`0h12m0s` → `12m0s`); sub-minute values keep one decimal (`45.2s`).

package/index.ts

@@ -1155,9 +1155,12 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 	// dispatch → assistant message_end, so tools between turns are
 	// excluded, time-to-first-token included) and `total` (wall-clock
 	// from user prompt to settle — retries, tools, overhead included).
-	// While streaming, a 1s ticker rewrites the working *message* (spinner
-	// frames are left alone). On `agent_settled` both are persisted as a
-	// durable custom entry rendered as a plain muted line in history.
+	// A `tps` figure accompanies both: live it is an estimate from streamed
+	// deltas (~4 chars/token, prefixed with `~`); final it is exact, from
+	// the provider's usage.output over the worked time. While streaming, a
+	// 1s ticker rewrites the working *message* (spinner frames are left
+	// alone). On `agent_settled` everything is persisted as a durable
+	// custom entry rendered as a plain muted line in history.
 	// ===================================================================
 
 	pi.registerEntryRenderer<WorkingTimeEntry>(WORKING_TIME_ENTRY, (entry, _opts, theme) => {
@@ -1177,7 +1180,9 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 	};
 
 	const renderWorkingMessage = (ctx: SessionContextLike): void => {
-		if (ctx.hasUI) ctx.ui.setWorkingMessage(workingMessageText(workingTracker.elapsedMs()));
+		if (ctx.hasUI) {
+			ctx.ui.setWorkingMessage(workingMessageText(workingTracker.elapsedMs(), workingTracker.liveTps()));
+		}
 	};
 
 	// `before_agent_start` fires right after the user submits the prompt,
@@ -1203,10 +1208,19 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 		workingTick = setInterval(() => renderWorkingMessage(ctx), 1000);
 	});
 
+	pi.on("message_update", (event, _ctx) => {
+		if (!faceliftConfig.showWorkingTime) return;
+		const e = event as { message?: { role?: string }; assistantMessageEvent?: { delta?: unknown } };
+		if (e.message?.role !== "assistant") return;
+		const delta = e.assistantMessageEvent?.delta;
+		if (typeof delta === "string" && delta.length > 0) workingTracker.addDelta(delta.length);
+	});
+
 	pi.on("message_end", (event, _ctx) => {
 		if (!faceliftConfig.showWorkingTime) return;
-		const role = (event as { message?: { role?: string } }).message?.role;
-		if (role !== "assistant") return;
+		const msg = (event as { message?: { role?: string; usage?: { output?: number } } }).message;
+		if (msg?.role !== "assistant") return;
+		if (typeof msg.usage?.output === "number") workingTracker.recordExactTokens(msg.usage.output);
 		workingTracker.endSegment();
 		stopWorkingTick();
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wierdbytes/pi-facelift",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Cosmetic facelift for built-in pi tool output — open-right rounded frames, syntax-highlighted reads, status-aware bash summaries, find/grep.",
   "type": "module",
   "files": [

package/working-time.test.ts

@@ -67,6 +67,38 @@ describe("WorkingTimeTracker", () => {
 		expect(t.settle()?.totalMs).toBe(3000);
 	});
 
+	it("estimates live tps from streamed deltas over worked time", () => {
+		let now = 0;
+		const t = new WorkingTimeTracker(() => now);
+		t.beginRun();
+		t.beginSegment();
+		t.addDelta(4000); // ~1000 estimated tokens at 4 chars/token
+		now = 2000; // 2s of worked time
+		expect(t.estimatedTokens()).toBe(1000);
+		expect(t.liveTps()).toBe(500); // 1000 tokens / 2s
+	});
+
+	it("liveTps is 0 before any time elapses", () => {
+		const t = new WorkingTimeTracker(() => 0);
+		t.beginRun();
+		t.beginSegment();
+		t.addDelta(400);
+		expect(t.liveTps()).toBe(0);
+	});
+
+	it("computes exact final tps from recorded tokens over worked ms", () => {
+		let now = 0;
+		const t = new WorkingTimeTracker(() => now);
+		t.beginRun();
+		t.beginSegment();
+		now = 2000;
+		t.recordExactTokens(1500);
+		t.endSegment();
+		const entry = t.settle();
+		expect(entry?.tokens).toBe(1500);
+		expect(entry?.tps).toBe(750); // 1500 tokens / 2s worked
+	});
+
 	it("excludes the gap between segments (tool execution time)", () => {
 		let now = 0;
 		const t = new WorkingTimeTracker(() => now);
@@ -143,16 +175,23 @@ describe("formatClock", () => {
 
 describe("workingMessageText / workingTimeLine", () => {
 	it("formats the live message using formatClock rules", () => {
-		expect(workingMessageText(0)).toBe("Working... 0.0s");
-		expect(workingMessageText(1999)).toBe("Working... 2.0s");
-		expect(workingMessageText(65_000)).toBe("Working... 1m5s");
-		expect(workingMessageText(720_000)).toBe("Working... 12m0s");
+		expect(workingMessageText(0, 0)).toBe("Working... 0.0s · tps: ~0");
+		expect(workingMessageText(1999, 120)).toBe("Working... 2.0s · tps: ~120");
+		expect(workingMessageText(65_000, 756)).toBe("Working... 1m5s · tps: ~756");
+		expect(workingMessageText(720_000, 800)).toBe("Working... 12m0s · tps: ~800");
 	});
 
-	it("renders a muted history line with worked + total", () => {
+	it("renders a muted history line with worked, total and exact tps", () => {
 		const dim = (s: string) => `<dim>${s}</dim>`;
-		const entry: WorkingTimeEntry = { ms: 45_200, totalMs: 75_000, startedAt: 0, endedAt: 0 };
-		expect(workingTimeLine(entry, dim)).toBe("<dim>⏱ worked 45.2s (total: 1m15s)</dim>");
+		const entry: WorkingTimeEntry = {
+			ms: 45_200,
+			totalMs: 75_000,
+			tokens: 34_200,
+			tps: 756,
+			startedAt: 0,
+			endedAt: 0,
+		};
+		expect(workingTimeLine(entry, dim)).toBe("<dim>⏱ worked 45.2s (total: 1m15s) · tps: 756</dim>");
 	});
 });
 
@@ -243,6 +282,30 @@ describe("working-time wiring", () => {
 		expect(data.totalMs).toBe(10500); // 500 + 5000 + 3000 + 2000
 	});
 
+	it("tracks live estimated tps (~) and final exact tps from usage.output", () => {
+		vi.useFakeTimers();
+		const { fire, entries, ctx } = loadExtension();
+		fire("before_agent_start", {});
+		fire("agent_start", {});
+		fire("before_provider_request", {});
+		// Stream ~4000 chars => ~1000 estimated tokens over 2s of worked time.
+		fire("message_update", {
+			message: { role: "assistant" },
+			assistantMessageEvent: { type: "text_delta", delta: "x".repeat(4000) },
+		});
+		vi.advanceTimersByTime(2000);
+		const calls = ctx.ui.setWorkingMessage.mock.calls.map((c) => c[0]);
+		expect(calls).toContain("Working... 2.0s · tps: ~500");
+		// Final exact tokens come from usage.output, not the estimate.
+		fire("message_end", { message: { role: "assistant", usage: { output: 1500 } } });
+		fire("agent_settled", {});
+		vi.useRealTimers();
+		expect(entries).toHaveLength(1);
+		const data = entries[0].data as WorkingTimeEntry;
+		expect(data.tokens).toBe(1500);
+		expect(data.tps).toBe(750); // 1500 / 2s worked
+	});
+
 	it("ignores non-assistant message_end (does not close the segment early)", () => {
 		vi.useFakeTimers();
 		const { fire, entries } = loadExtension();
@@ -267,8 +330,8 @@ describe("working-time wiring", () => {
 		fire("before_provider_request", {});
 		vi.advanceTimersByTime(2000);
 		const calls = ctx.ui.setWorkingMessage.mock.calls.map((c) => c[0]);
-		expect(calls[0]).toBe("Working... 0.0s");
-		expect(calls).toContain("Working... 2.0s");
+		expect(calls[0]).toBe("Working... 0.0s · tps: ~0");
+		expect(calls).toContain("Working... 2.0s · tps: ~0");
 		fire("message_end", asst);
 		fire("agent_settled", {});
 		vi.useRealTimers();
@@ -283,10 +346,10 @@ describe("working-time wiring", () => {
 		expect(renderer).toBeDefined();
 		const theme = { fg: (_k: string, s: string) => `dim(${s})` };
 		const out = renderer!(
-			{ data: { ms: 1500, totalMs: 4000, startedAt: 0, endedAt: 0 } },
+			{ data: { ms: 1500, totalMs: 4000, tokens: 300, tps: 200, startedAt: 0, endedAt: 0 } },
 			{ expanded: false },
 			theme,
 		) as MockText;
-		expect(out.getText()).toBe("dim(⏱ worked 1.5s (total: 4.0s))");
+		expect(out.getText()).toBe("dim(⏱ worked 1.5s (total: 4.0s) · tps: 200)");
 	});
 });

package/working-time.ts

@@ -14,6 +14,12 @@
  *     (`before_agent_start`) until the run settles (`agent_settled`).
  *     Retries, tool calls, and every other overhead are included.
  *
+ * A tokens-per-second (`tps`) figure accompanies both displays:
+ *   • Live: estimated from streamed deltas (~4 chars ≈ 1 token), marked
+ *     with a leading `~` to show it is an estimate.
+ *   • Final: exact, from the provider's `usage.output` divided by the
+ *     model-only `worked` time.
+ *
  * Two consumers:
  *   • Live: while the current assistant message streams, a 1s interval
  *     calls `setWorkingMessage` with a ticking timer (spinner frames are
@@ -29,12 +35,19 @@
 /** Custom entry type used with `pi.appendEntry` / `registerEntryRenderer`. */
 export const WORKING_TIME_ENTRY = "facelift-working-time";
 
+/** Rough chars-per-token ratio used to estimate live tokens from streamed deltas. */
+export const CHARS_PER_TOKEN = 4;
+
 /** Payload stored on the durable working-time entry. */
 export interface WorkingTimeEntry {
 	/** Model-only streaming time for the run, in milliseconds (tools excluded). */
 	ms: number;
 	/** Wall-clock time from user prompt to final response, in milliseconds. */
 	totalMs: number;
+	/** Exact output tokens reported by the provider for this run. */
+	tokens: number;
+	/** Exact tokens-per-second over the model-only `worked` time. */
+	tps: number;
 	/** Epoch ms when the run started (user prompt submitted). */
 	startedAt: number;
 	/** Epoch ms when the run settled. */
@@ -49,8 +62,9 @@ export interface WorkingTimeEntry {
  *   before_agent_start      → beginRun()   (total clock starts here)
  *   agent_start             → ensureRun()  (fallback if before_agent_start skipped)
  *   before_provider_request → beginSegment() + start the live ticker
- *   message_end     (asst)  → endSegment()   + stop the ticker
- *   agent_settled           → settle() ⇒ { ms, totalMs }, then reset
+ *   message_update  (asst)  → addDelta()     (feed the live tps estimate)
+ *   message_end     (asst)  → recordExactTokens() + endSegment() + stop ticker
+ *   agent_settled           → settle() ⇒ { ms, totalMs, tokens, tps }, reset
  *
  * Retries / auto-compaction fire their own agent_start but pi only emits
  * `agent_settled` when it truly stops, so a run is measured end-to-end.
@@ -60,16 +74,20 @@ export class WorkingTimeTracker {
 	private accumulatorMs = 0;
 	private segmentStart: number | undefined;
 	private runStart: number | undefined;
+	private runEstChars = 0;
+	private runExactTokens = 0;
 
 	constructor(now: () => number = () => Date.now()) {
 		this.now = now;
 	}
 
-	/** Start a fresh run, discarding any prior accumulated time. */
+	/** Start a fresh run, discarding any prior accumulated time/tokens. */
 	beginRun(): void {
 		this.accumulatorMs = 0;
 		this.segmentStart = undefined;
 		this.runStart = this.now();
+		this.runEstChars = 0;
+		this.runExactTokens = 0;
 	}
 
 	/** Start a run only if one isn't already in progress (idempotent). */
@@ -102,6 +120,31 @@ export class WorkingTimeTracker {
 		return this.runStart !== undefined;
 	}
 
+	/** Accumulate streamed delta characters (input for the live tps estimate). */
+	addDelta(chars: number): void {
+		if (chars > 0) this.runEstChars += chars;
+	}
+
+	/** Record exact output tokens reported for a finished assistant message. */
+	recordExactTokens(tokens: number): void {
+		if (tokens > 0) this.runExactTokens += tokens;
+	}
+
+	/** Estimated tokens received so far this run (~4 chars per token). */
+	estimatedTokens(): number {
+		return this.runEstChars / CHARS_PER_TOKEN;
+	}
+
+	/**
+	 * Live tokens-per-second: estimated tokens over worked time so far.
+	 * Returns 0 until some measurable time has elapsed.
+	 */
+	liveTps(): number {
+		const elapsed = this.elapsedMs();
+		if (elapsed <= 0) return 0;
+		return Math.round(this.estimatedTokens() / (elapsed / 1000));
+	}
+
 	/**
 	 * Finalize the run and return the durable entry, or `undefined` when
 	 * no measurable time accrued (guards against junk 0ms entries).
@@ -112,24 +155,28 @@ export class WorkingTimeTracker {
 		const endedAt = this.now();
 		const ms = this.accumulatorMs;
 		const startedAt = this.runStart;
+		const tokens = this.runExactTokens;
 		this.accumulatorMs = 0;
 		this.segmentStart = undefined;
 		this.runStart = undefined;
+		this.runEstChars = 0;
+		this.runExactTokens = 0;
 		if (startedAt === undefined || ms <= 0) return undefined;
-		return { ms, totalMs: Math.max(0, endedAt - startedAt), startedAt, endedAt };
+		const tps = tokens > 0 ? Math.round(tokens / (ms / 1000)) : 0;
+		return { ms, totalMs: Math.max(0, endedAt - startedAt), tokens, tps, startedAt, endedAt };
 	}
 }
 
 /**
- * Build the live working message, e.g. `Working... 1m5s`. Uses the same
- * `formatClock` rules as the durable history line so the live and final
- * displays stay consistent. The animated spinner frames are drawn by pi
- * separately (via `setWorkingIndicator`), so this only supplies the
- * trailing text — preserving whatever spinner the user/other extensions
- * have configured.
+ * Build the live working message, e.g. `Working... 1m5s · tps: ~756`. Uses
+ * the same `formatClock` rules as the durable history line so the live and
+ * final displays stay consistent. `liveTps` is an estimate (hence the `~`).
+ * The animated spinner frames are drawn by pi separately (via
+ * `setWorkingIndicator`), so this only supplies the trailing text —
+ * preserving whatever spinner the user/other extensions have configured.
  */
-export function workingMessageText(elapsedMs: number): string {
-	return `Working... ${formatClock(elapsedMs)}`;
+export function workingMessageText(elapsedMs: number, liveTps: number): string {
+	return `Working... ${formatClock(elapsedMs)} · tps: ~${liveTps}`;
 }
 
 /**
@@ -156,8 +203,8 @@ export function formatClock(ms: number): string {
 
 /**
  * Render the durable entry body as a plain muted line (no frame):
- * `⏱ worked 45.2s (total: 1m15s)`.
+ * `⏱ worked 45.2s (total: 1m15s) · tps: 756`. The tps here is exact (no `~`).
  */
 export function workingTimeLine(entry: WorkingTimeEntry, dim: (s: string) => string): string {
-	return dim(`⏱ worked ${formatClock(entry.ms)} (total: ${formatClock(entry.totalMs)})`);
+	return dim(`⏱ worked ${formatClock(entry.ms)} (total: ${formatClock(entry.totalMs)}) · tps: ${entry.tps}`);
 }