@danypops/pi-jittor 0.3.1 → 0.4.0

package/extension/src/index.ts

@@ -12,6 +12,7 @@ import {
 	loadOpenAiTextTokenCounter,
 	MAX_DYNAMIC_ROUTES,
 	type MetricObservation,
+	MILLISECONDS_PER_DAY,
 	type ModelCandidate,
 	type ModelTaskDomain,
 	type ModelTaskType,
@@ -33,6 +34,7 @@ import {
 	validateTaskFocusEvent,
 } from "@danypops/jittor";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { showCacheEconomicsPanel } from "./observability/cache-economics-view.ts";
 import {
 	basePromptSegment,
 	buildBasePromptItems,
@@ -161,6 +163,23 @@ interface PiRouteModel {
 	cost?: { input?: number; output?: number };
 }
 
+/**
+ * Pi's own `--models`/`enabledModels` scoping (`ctx.scopedModels`, the same set the `/scoped-models`
+ * command shows) is the authority for which models a session may actually use -- e.g. a "work"
+ * profile scoped to one provider/model set versus a "personal" profile scoped to a different one.
+ * `ctx.modelRegistry.getAvailable()` enumerates every authenticated model on the host regardless of
+ * that restriction (Pi's own docs warn against using it for a model picker for exactly this reason:
+ * "instead of enumerating the whole catalogue via ctx.modelRegistry.getAvailable()"). Every Jittor
+ * call site that builds a candidate/route set for routing or ranking must prefer the scoped set
+ * when one is configured, or a scoped session keeps seeing -- and can be automatically routed onto
+ * -- another profile's models. An empty scopedModels list means "no scoping configured" (matching
+ * Pi's own semantics), not "scoped to nothing", so it still falls back to the full catalog.
+ */
+function scopedOrAvailableModels(ctx: ExtensionContext): PiRouteModel[] {
+	if (ctx.scopedModels.length > 0) return ctx.scopedModels.map((entry) => entry.model as PiRouteModel);
+	return ctx.modelRegistry.getAvailable() as PiRouteModel[];
+}
+
 const THINKING_DESCENDING = ["max", "xhigh", "high", "medium", "low", "minimal", "off"] as const;
 
 function supportsThinking(model: PiRouteModel, level: string): boolean {
@@ -237,7 +256,7 @@ async function syncAvailableRoutes(pi: ExtensionAPI, client: JittorExtensionClie
 		await client.call("router.available_routes", { routes: [], session_id, ...secret });
 		return;
 	}
-	const models = ctx.modelRegistry.getAvailable() as PiRouteModel[];
+	const models = scopedOrAvailableModels(ctx);
 	const routes = routesFromPi(models, ctx.model as PiRouteModel, pi.getThinkingLevel());
 	await client.call("router.available_routes", { routes, session_id, ...secret });
 }
@@ -292,16 +311,24 @@ async function applyDecision(
 	);
 }
 
+let assistantUsageRunSequence = 0;
+
 /**
  * taskId, when a Papyrus task is focused, tags the metric for cost-per-task correlation. thinking
  * comes from pi.getThinkingLevel() at message_end time, not from the message itself -- AssistantMessage
- * has no thinking field of its own, and the level can't have changed mid-message.
+ * has no thinking field of its own, and the level can't have changed mid-message. sessionId tags every
+ * row so cache economics (see @danypops/jittor's cache-economics.ts) can correlate a cache write back
+ * to this same session's own context-prefix reset evidence, without ever widening scope by provider/model.
+ * runId ties every metric emitted for this one turn together (a counter, not just observedAt, since
+ * two turns can share a millisecond) so cache economics can resolve per-turn (e.g. tiered) catalog
+ * pricing against this turn's own real size instead of a blended sum across a whole query window.
  */
 function assistantUsageMetrics(
 	message: unknown,
 	observedAt: number,
 	taskId: string | null = null,
 	thinking: string | null = null,
+	sessionId: string | null = null,
 ): MetricObservation[] {
 	if (typeof message !== "object" || message === null || Array.isArray(message)) return [];
 	const value = message as Record<string, unknown>;
@@ -313,11 +340,14 @@ function assistantUsageMetrics(
 	const provider = typeof value.provider === "string" ? value.provider : "unknown";
 	const model = typeof value.model === "string" ? value.model : "unknown";
 	const scope = `${provider}:${model}`;
+	const runId = `pi-usage-${metricObservedAt}-${++assistantUsageRunSequence}`;
 	const attributes = {
 		provider,
 		model,
+		runId,
 		...(taskId === null ? {} : { taskId }),
 		...(thinking === null || thinking.length === 0 ? {} : { thinking }),
+		...(sessionId === null || sessionId.length === 0 ? {} : { sessionId }),
 	};
 	const metrics: MetricObservation[] = [];
 	for (const [field, metric, tokenScope] of [
@@ -348,9 +378,23 @@ function assistantUsageMetrics(
 				},
 			});
 	}
-	const cost = typeof usage.cost === "object" && usage.cost !== null ? (usage.cost as Record<string, unknown>).total : undefined;
+	const costBreakdown = typeof usage.cost === "object" && usage.cost !== null ? (usage.cost as Record<string, unknown>) : undefined;
+	const cost = costBreakdown?.total;
 	if (typeof cost === "number" && Number.isFinite(cost))
 		metrics.push({ source: "pi", scope, metric: "cost", value: cost, unit: "usd", observedAt: metricObservedAt, attributes });
+	// Itemized provider-reported cost, when the provider breaks it out -- the real dollar figures cache
+	// economics needs (see cache-economics.ts) instead of ever re-deriving them from catalog prices when
+	// the provider already told us. Never fabricated: omitted entirely when a field is absent.
+	for (const [field, metric] of [
+		["input", "input-cost"],
+		["output", "output-cost"],
+		["cacheRead", "cache-read-cost"],
+		["cacheWrite", "cache-write-cost"],
+	] as const satisfies ReadonlyArray<readonly [string, string]>) {
+		const amount = costBreakdown?.[field];
+		if (typeof amount === "number" && Number.isFinite(amount))
+			metrics.push({ source: "pi", scope, metric, value: amount, unit: "usd", observedAt: metricObservedAt, attributes });
+	}
 	return metrics;
 }
 
@@ -529,7 +573,7 @@ export function registerJittorExtension(
 	};
 
 	pi.registerCommand("jittor", {
-		description: "Jittor settings, routing status, benchmarks, and Codex recovery controls",
+		description: "Jittor settings, routing status, benchmarks, cache economics, and Codex recovery controls",
 		handler: async (args, ctx) => {
 			const action = args.trim().toLowerCase();
 			if (action === "" || action === "settings") {
@@ -569,7 +613,7 @@ export function registerJittorExtension(
 					ctx.ui.notify("Usage: /jittor benchmarks [coding|general] [research|planning|general]", "warning");
 					return;
 				}
-				const candidates = benchmarkCandidatesFromPi(ctx.modelRegistry.getAvailable() as PiRouteModel[], pi.getThinkingLevel());
+				const candidates = benchmarkCandidatesFromPi(scopedOrAvailableModels(ctx), pi.getThinkingLevel());
 				await showBenchmarkPanel(
 					ctx,
 					client,
@@ -580,6 +624,10 @@ export function registerJittorExtension(
 				);
 				return;
 			}
+			if (action === "cache") {
+				await showCacheEconomicsPanel(ctx, client, 7 * MILLISECONDS_PER_DAY);
+				return;
+			}
 			if (action === "outcome accepted" || action === "outcome rejected") {
 				const explicitOutcome = action.endsWith("accepted") ? ("accepted" as const) : ("rejected" as const);
 				const outcomeMetric = localRunTelemetry.explicitOutcomeMetric(explicitOutcome);
@@ -929,7 +977,13 @@ export function registerJittorExtension(
 				event.message.errorMessage,
 			);
 		}
-		const metrics = assistantUsageMetrics(event.message, Date.now(), focusedTaskId, pi.getThinkingLevel());
+		const metrics = assistantUsageMetrics(
+			event.message,
+			Date.now(),
+			focusedTaskId,
+			pi.getThinkingLevel(),
+			ctx.sessionManager.getSessionId(),
+		);
 		if (metrics.length > 0) {
 			const amount = (name: string): number =>
 				metrics

package/extension/src/observability/cache-economics-view.ts

@@ -0,0 +1,155 @@
+import type {
+	CacheEconomicsAggregateTotals,
+	CacheEconomicsModelSummary,
+	CacheEconomicsSummary,
+	CacheEconomicsTaskSummary,
+} from "@danypops/jittor";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { BorderedSelectPanel, type TextMeasure } from "malevich-tui-components";
+
+export interface CacheEconomicsPanelTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+type CacheEconomicsPanelAction = "refresh" | "close";
+
+const hostTextMeasure: TextMeasure = { visibleWidth, truncateToWidth };
+
+export interface CacheEconomicsPanelClient {
+	call(operation: string, input: unknown): Promise<any>;
+}
+
+function formatUsd(amount: number): string {
+	return `$${amount.toFixed(Math.abs(amount) < 0.01 && amount !== 0 ? 4 : 2)}`;
+}
+
+function costField(amountUsd: number | null, basis: "provider-reported" | "catalog-estimate" | "unknown"): string {
+	if (amountUsd === null) return "unknown";
+	return basis === "catalog-estimate" ? `${formatUsd(amountUsd)} (est.)` : formatUsd(amountUsd);
+}
+
+function aggregateFields(totals: CacheEconomicsAggregateTotals): string {
+	const payback = totals.paybackAchieved === null ? "n/a" : totals.paybackAchieved ? "yes" : "not yet";
+	return [
+		`read ${totals.cacheReadTokens.toLocaleString()} tok (${costField(totals.cacheReadCostUsd, totals.cacheReadCostBasis)})`,
+		`write ${totals.cacheWriteTokens.toLocaleString()} tok (${costField(totals.cacheWriteCostUsd, totals.cacheWriteCostBasis)})`,
+		`savings ${totals.savingsUsd === null ? "unknown" : formatUsd(totals.savingsUsd)}`,
+		`payback ${payback}`,
+	].join(" · ");
+}
+
+function freshnessSuffix(catalogFreshness: "fresh" | "stale" | null): string {
+	return catalogFreshness === "stale" ? " -- stale catalog snapshot used for the estimate(s) above" : "";
+}
+
+function modelLine(model: CacheEconomicsModelSummary): string {
+	return `${model.provider}/${model.model}: ${aggregateFields(model)}${freshnessSuffix(model.catalogFreshness)}`;
+}
+
+function taskLine(task: CacheEconomicsTaskSummary): string {
+	return `${task.taskId}: ${aggregateFields(task)}${freshnessSuffix(task.catalogFreshness)}`;
+}
+
+/** Plain multi-line text, shared by TUI notify and non-TUI notify -- a full interactive panel is deferred; this already satisfies "bounded query plus Pi presentation" without a new widget. */
+export function renderCacheEconomicsView(summary: CacheEconomicsSummary): string[] {
+	const lines = [
+		`Cache economics (${new Date(summary.since).toISOString().slice(0, 10)} .. ${new Date(summary.until).toISOString().slice(0, 10)})${summary.truncated ? " -- query limit reached, totals are a lower bound" : ""}`,
+	];
+	if (summary.models.length === 0) lines.push("No cache activity recorded in this window.");
+	else lines.push(...summary.models.map((model) => `- ${modelLine(model)}`));
+	if (summary.tasks.length > 0) {
+		lines.push(`By task: ${summary.tasks.length}`);
+		lines.push(...summary.tasks.map((task) => `- ${taskLine(task)}`));
+	}
+	const unattributed = summary.unattributedCacheActivity;
+	if (unattributed.cacheReadTokens > 0 || unattributed.cacheWriteTokens > 0) {
+		lines.push(
+			`Unattributed (no task focused): read ${unattributed.cacheReadTokens.toLocaleString()} tok (${costField(unattributed.cacheReadCostUsd, unattributed.cacheReadCostBasis)}) · write ${unattributed.cacheWriteTokens.toLocaleString()} tok (${costField(unattributed.cacheWriteCostUsd, unattributed.cacheWriteCostBasis)})`,
+		);
+	}
+	if (summary.stablePrefixChurn.length > 0) {
+		lines.push(`Stable-prefix churn (${summary.stablePrefixChurn.length} snapshot(s), oldest first):`);
+		for (const point of summary.stablePrefixChurn) {
+			lines.push(
+				`- ${new Date(point.observedAt).toISOString()} session ${point.sessionId}: ${point.stablePrefixTokens.toLocaleString()} tok${point.resetReason === null ? "" : ` (${point.resetReason} reset)`}`,
+			);
+		}
+	}
+	if (summary.missedOpportunities.length > 0) {
+		lines.push(`Candidate missed-cache opportunities: ${summary.missedOpportunities.length}`);
+		for (const candidate of summary.missedOpportunities.slice(0, 10)) {
+			lines.push(
+				`- session ${candidate.sessionId}: ${candidate.resetReason} reset, then ${candidate.cacheWriteTokens.toLocaleString()} cache-write tok${candidate.cacheWriteCostUsd === null ? "" : ` (${formatUsd(candidate.cacheWriteCostUsd)})`}`,
+			);
+		}
+	}
+	return lines;
+}
+
+export async function showCacheEconomicsView(
+	ctx: ExtensionCommandContext,
+	client: CacheEconomicsPanelClient,
+	windowMs: number,
+	now: () => number = Date.now,
+): Promise<void> {
+	const until = now();
+	const since = Math.max(0, until - windowMs);
+	const summary = (await client.call("cache.economics", { since, until })) as CacheEconomicsSummary;
+	ctx.ui.notify(renderCacheEconomicsView(summary).join("\n"), "info");
+}
+
+/** The same content as renderCacheEconomicsView, wrapped in a titled, bordered, scrollable frame -- mirrors optimization/model-selection-panel.ts's renderBenchmarkView/BorderedSelectPanel pattern. */
+export function renderCacheEconomicsPanel(summary: CacheEconomicsSummary, width: number, theme: CacheEconomicsPanelTheme): string[] {
+	const safeWidth = Math.max(1, width);
+	const lines = renderCacheEconomicsView(summary);
+	const content = {
+		invalidate: () => {},
+		render: (availableWidth: number): string[] => lines.map((line) => truncateToWidth(line, availableWidth, "…")),
+	};
+	return new BorderedSelectPanel({
+		title: "Jittor Cache Economics",
+		list: content,
+		helpText: "r refresh · Esc close",
+		theme: {
+			border: (text) => theme.fg("borderMuted", text),
+			title: theme.bold,
+			help: (text) => theme.fg("dim", text),
+		},
+		measure: hostTextMeasure,
+	}).render(safeWidth);
+}
+
+/**
+ * Interactive scrollable panel for /jittor cache, mirroring showBenchmarkPanel: a plain notify
+ * outside TUI mode (unchanged from showCacheEconomicsView's own behavior), an interactive
+ * BorderedSelectPanel with an 'r' refresh keybinding inside it.
+ */
+export async function showCacheEconomicsPanel(
+	ctx: ExtensionCommandContext,
+	client: CacheEconomicsPanelClient,
+	windowMs: number,
+	now: () => number = Date.now,
+): Promise<void> {
+	for (;;) {
+		const until = now();
+		const since = Math.max(0, until - windowMs);
+		const summary = (await client.call("cache.economics", { since, until })) as CacheEconomicsSummary;
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify(renderCacheEconomicsView(summary).join("\n"), "info");
+			return;
+		}
+		const action = await ctx.ui.custom<CacheEconomicsPanelAction>((_tui, theme, _keybindings, done) => ({
+			invalidate() {},
+			render(width: number): string[] {
+				return renderCacheEconomicsPanel(summary, width, theme);
+			},
+			handleInput(data: string): void {
+				if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) done("close");
+				else if (data === "r") done("refresh");
+			},
+		}));
+		if (!action || action === "close") return;
+	}
+}

package/extension/src/service-client.ts

@@ -50,6 +50,7 @@ const OPERATION_RETRY_MODE = {
 	"router.clear_override": "once",
 	"router.current_route": "once",
 	"router.available_routes": "once",
+	"cache.economics": "retry",
 } as const satisfies Record<OperationName, "retry" | "once">;
 
 export function operationRetryMode(operation: OperationName): "retry" | "once" {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-jittor",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Pi extension for Jittor token and context observability with optimization controls backed by the @danypops/jittor daemon",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],
@@ -15,7 +15,7 @@
     "@danypops/vehicle-client": "^0.5.1",
     "@danypops/vehicle-core": "^0.12.1",
     "@danypops/vehicle-server": "^0.17.0",
-    "@danypops/jittor": "^0.17.0",
+    "@danypops/jittor": "^0.18.0",
     "malevich-tui-components": "^0.16.1"
   },
   "peerDependencies": {