@danypops/pi-jittor 0.3.1 → 0.5.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,8 @@ import {
 	validateTaskFocusEvent,
 } from "@danypops/jittor";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { jittorArgumentCompletions, jittorUsageError } from "./jittor-command.ts";
+import { showJittorShell } from "./jittor-shell.ts";
 import {
 	basePromptSegment,
 	buildBasePromptItems,
@@ -49,14 +52,12 @@ import { type CompactionProgress, type IntegratedFooterState, installIntegratedF
 import { LocalRunTelemetry } from "./observability/model-run.ts";
 import { captureProviderContextSnapshot } from "./observability/provider-context-snapshot.ts";
 import { ProviderResponseTelemetry } from "./observability/provider-response.ts";
-import { buildFooterBudget, providerBudgetMetricQuery, showJittorPanel } from "./observability/status.ts";
+import { buildFooterBudget, providerBudgetMetricQuery } from "./observability/status.ts";
 import { showUsagePanel } from "./observability/usage.ts";
-import { showBenchmarkPanel } from "./optimization/model-selection-panel.ts";
 import { CodexRecoveryCapability, type CodexRecoveryRuntime, SYSTEM_RECOVERY_RUNTIME } from "./optimization/recovery/codex.ts";
 import { callJittor } from "./service-client.ts";
 import { cacheSessionSecret, forgetSessionSecret, sessionSecretField } from "./session-identity.ts";
 import { type CodexRecoveryControl, type EnforcementControl, persistentEnforcementControl, type UsageBudgetControl } from "./settings.ts";
-import { showSettingsPanel } from "./settings-tui.ts";
 
 export { formatFooterStatus } from "./observability/status.ts";
 export type { CodexRecoveryRuntime } from "./optimization/recovery/codex.ts";
@@ -161,6 +162,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 +255,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 +310,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 +339,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 +377,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,22 +572,54 @@ 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",
+		getArgumentCompletions: jittorArgumentCompletions,
 		handler: async (args, ctx) => {
 			const action = args.trim().toLowerCase();
-			if (action === "" || action === "settings") {
-				await showSettingsPanel(ctx, enforcement, codexRecovery, usageBudgets, {
-					setEnforcement: async (enabled) => (enabled ? enable(ctx) : disable(ctx)),
-					setFooter: async (enabled) => {
-						await enforcement.setFooterEnabled(enabled);
-						showFooter(ctx);
-						if (enabled) await refreshFooter(client, footerState, ctx.sessionManager.getSessionId()).catch(() => undefined);
-					},
-					setRecovery: async (enabled) => {
-						if (!enabled) cancelRecovery(true);
-						await codexRecovery.setCodexRecoveryEnabled(enabled);
+			const usageError = jittorUsageError(action);
+			if (usageError) {
+				ctx.ui.notify(usageError, "warning");
+				return;
+			}
+			// One shared JittorShellDeps builder for every /jittor entry point below -- all four tabs
+			// (Settings/Status/Benchmarks/Cache) are reachable from a single opened shell regardless of
+			// which subcommand opened it, so every entry point needs the full dependency set, not just
+			// its own tab's. `benchmarksTask` overrides the domain/type only for an explicit
+			// "/jittor benchmarks ..." invocation; every other entry point defaults to general/general
+			// (only meaningfully exercised if the user tab-cycles into Benchmarks from elsewhere).
+			const buildShellDeps = (benchmarksTask?: {
+				domain: ModelTaskDomain;
+				type: ModelTaskType;
+			}): Parameters<typeof showJittorShell>[1] => ({
+				settings: {
+					enforcement,
+					recovery: codexRecovery,
+					budgets: usageBudgets,
+					effects: {
+						setEnforcement: async (enabled) => (enabled ? enable(ctx) : disable(ctx)),
+						setFooter: async (enabled) => {
+							await enforcement.setFooterEnabled(enabled);
+							showFooter(ctx);
+							if (enabled) await refreshFooter(client, footerState, ctx.sessionManager.getSessionId()).catch(() => undefined);
+						},
+						setRecovery: async (enabled) => {
+							if (!enabled) cancelRecovery(true);
+							await codexRecovery.setCodexRecoveryEnabled(enabled);
+						},
 					},
-				});
+				},
+				status: { client },
+				benchmarks: {
+					client,
+					candidates: benchmarkCandidatesFromPi(scopedOrAvailableModels(ctx), pi.getThinkingLevel()),
+					currentIdentity: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "",
+					domain: benchmarksTask?.domain ?? "general",
+					type: benchmarksTask?.type ?? "general",
+				},
+				cache: { client, windowMs: 7 * MILLISECONDS_PER_DAY },
+			});
+			if (action === "" || action === "settings") {
+				await showJittorShell(ctx, buildShellDeps(), "settings");
 				return;
 			}
 			if (action === "benchmarks" || action.startsWith("benchmarks ")) {
@@ -569,17 +644,17 @@ 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());
-				await showBenchmarkPanel(
+				await showJittorShell(
 					ctx,
-					client,
-					candidates,
-					`${ctx.model.provider}/${ctx.model.id}`,
-					requestedDomain ?? "general",
-					requestedType ?? "general",
+					buildShellDeps({ domain: requestedDomain ?? "general", type: requestedType ?? "general" }),
+					"benchmarks",
 				);
 				return;
 			}
+			if (action === "cache") {
+				await showJittorShell(ctx, buildShellDeps(), "cache");
+				return;
+			}
 			if (action === "outcome accepted" || action === "outcome rejected") {
 				const explicitOutcome = action.endsWith("accepted") ? ("accepted" as const) : ("rejected" as const);
 				const outcomeMetric = localRunTelemetry.explicitOutcomeMetric(explicitOutcome);
@@ -653,13 +728,13 @@ export function registerJittorExtension(
 				);
 				return;
 			}
-			// Reached only for the explicit "status" keyword or any other unrecognized text; bare "" is
-			// handled above by the settings branch, so this always has a non-empty, non-settings action.
+			// Reached only for the explicit "status" keyword -- jittorUsageError above already rejected
+			// anything else this handler doesn't recognize, so this is never an unrecognized fallback.
 			if (!enforcement.isEnabled()) {
 				ctx.ui.notify("Jittor is monitor-only. Run /jittor on to re-enable blocking.", "info");
 				return;
 			}
-			await showJittorPanel(ctx, client);
+			await showJittorShell(ctx, buildShellDeps(), "status");
 		},
 	});
 
@@ -929,7 +1004,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/jittor-command.ts

@@ -0,0 +1,110 @@
+/**
+ * The full argument grammar for /jittor, as one small data table -- the single source of truth
+ * both jittorUsageError (validation) and jittorArgumentCompletions (tab-completion) read from, so
+ * the two can never drift apart (a phrase added to one is automatically valid/completable in the
+ * other). /jittor's own registerCommand handler in index.ts owns dispatching a validated phrase to
+ * its real behavior; this module only ever answers "is this a real phrase" and "what could this
+ * become".
+ *
+ * `benchmarks` is deliberately excluded from LEAF_PHRASES: its own domain/type combinatorics
+ * (TASK_DOMAINS x TASK_TYPES, either order) already have a dedicated, tested malformed-usage
+ * branch in index.ts with its own specific error message -- this module defers to it entirely
+ * for validation, and only mirrors its real phrase space for completions.
+ */
+import { TASK_DOMAINS, TASK_TYPES } from "@danypops/jittor";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+export const JITTOR_TOP_LEVEL_COMMANDS = [
+	"settings",
+	"status",
+	"benchmarks",
+	"cache",
+	"outcome",
+	"recovery",
+	"on",
+	"off",
+	"footer",
+	"context",
+] as const;
+
+/** Every real, currently-supported phrase EXCEPT benchmarks (see module doc comment). */
+const LEAF_PHRASES = [
+	"",
+	"settings",
+	"status",
+	"cache",
+	"context",
+	"on",
+	"enable",
+	"off",
+	"disable",
+	"outcome accepted",
+	"outcome rejected",
+	"recovery",
+	"recovery status",
+	"recovery on",
+	"recovery enable",
+	"recovery off",
+	"recovery disable",
+	"recovery cancel",
+	"footer on",
+	"footer enable",
+	"footer off",
+	"footer disable",
+] as const;
+
+/** Real benchmarks phrases: bare, one axis alone, or both axes in either accepted word order -- mirrors index.ts's own lenient two-word-any-order parsing, for completions only. */
+function benchmarksPhrases(): string[] {
+	const phrases: string[] = ["benchmarks"];
+	for (const domain of TASK_DOMAINS) phrases.push(`benchmarks ${domain}`);
+	for (const type of TASK_TYPES) phrases.push(`benchmarks ${type}`);
+	for (const domain of TASK_DOMAINS) {
+		for (const type of TASK_TYPES) {
+			phrases.push(`benchmarks ${domain} ${type}`, `benchmarks ${type} ${domain}`);
+		}
+	}
+	return phrases;
+}
+
+/**
+ * null when `action` (already trimmed/lowercased by the caller, matching index.ts's own
+ * convention) is a real, currently-supported phrase; otherwise a human-readable message naming
+ * exactly what was wrong and what the real alternatives are -- never a silent fallback to
+ * unrelated behavior (the bug class this replaces: an unrecognized word, or a valid command with
+ * an unrecognized trailing argument, used to silently open the status panel instead).
+ */
+export function jittorUsageError(action: string): string | null {
+	if ((LEAF_PHRASES as readonly string[]).includes(action)) return null;
+	if (action === "benchmarks" || action.startsWith("benchmarks ")) return null;
+
+	const words = action.split(/\s+/).filter(Boolean);
+	const firstWord = words[0]!;
+	if (!(JITTOR_TOP_LEVEL_COMMANDS as readonly string[]).includes(firstWord)) {
+		return `Unknown /jittor command "${firstWord}". Allowed: ${JITTOR_TOP_LEVEL_COMMANDS.join(", ")}.`;
+	}
+	const subPhrases = LEAF_PHRASES.filter((phrase) => phrase.startsWith(`${firstWord} `));
+	if (subPhrases.length === 0) return `/jittor ${firstWord} does not take any arguments.`;
+	const subArguments = subPhrases.map((phrase) => phrase.slice(firstWord.length + 1));
+	return `Unknown /jittor ${firstWord} argument "${words.slice(1).join(" ")}". Allowed: ${subArguments.join(", ")}.`;
+}
+
+let cachedCompletionPhrases: string[] | undefined;
+function completionPhrases(): string[] {
+	if (!cachedCompletionPhrases) cachedCompletionPhrases = [...LEAF_PHRASES.filter((phrase) => phrase.length > 0), ...benchmarksPhrases()];
+	return cachedCompletionPhrases;
+}
+
+/**
+ * Every real phrase (see completionPhrases) that could still result from typing more after
+ * `argumentPrefix`, matching pi-tui's own SlashCommand.getArgumentCompletions contract: `value` is
+ * the FULL replacement for the entire argument text typed so far (pi-tui's own applyCompletion
+ * replaces the whole prefix span with it, not just the trailing word), so every candidate here is a
+ * complete phrase, not a per-word delta. Matching is case-insensitive on the typed prefix (a human
+ * may capitalize while typing); returned values are always canonical lowercase.
+ */
+export function jittorArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+	const needle = argumentPrefix.toLowerCase();
+	const matches = completionPhrases().filter((phrase) => phrase.startsWith(needle));
+	if (matches.length === 0) return null;
+	return matches.map((value) => ({ value, label: value }));
+}