@danypops/pi-jittor 0.5.4 → 0.6.0

package/extension/src/index.ts

@@ -6,7 +6,10 @@ import {
 	CONTEXT_HUB_CONTRIBUTION_CHANNEL,
 	CompactionTelemetry,
 	type ContextAssessment,
+	classifyEffort,
 	classifyTaskFromTools,
+	declaredEffortFromTaskFocusEvent,
+	EFFORT_CLASSIFICATION_MAX_TOOL_NAMES,
 	FOOTER_COMPACTION_RENDER_INTERVAL_MS,
 	HmacContextFingerprinter,
 	loadOpenAiTextTokenCounter,
@@ -15,6 +18,7 @@ import {
 	MILLISECONDS_PER_DAY,
 	type ModelCandidate,
 	type ModelTaskDomain,
+	type ModelTaskEffort,
 	type ModelTaskType,
 	PAPYRUS_CONTEXT_INJECTION_CHANNEL,
 	PAPYRUS_TASK_FOCUS_CHANNEL,
@@ -54,10 +58,19 @@ import { captureProviderContextSnapshot } from "./observability/provider-context
 import { ProviderResponseTelemetry } from "./observability/provider-response.ts";
 import { buildFooterBudget, providerBudgetMetricQuery } from "./observability/status.ts";
 import { showUsagePanel } from "./observability/usage.ts";
+import { candidateIdentityOf, decideAutoMode, newAutoModeSessionState, recordAutoModeDismissal } from "./optimization/auto-mode.ts";
+import { showAutoModeSuggestion } from "./optimization/auto-mode-dialog.ts";
+import { fetchBenchmarkRanking } 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 {
+	type AutoModeControl,
+	type CodexRecoveryControl,
+	type EnforcementControl,
+	persistentEnforcementControl,
+	type UsageBudgetControl,
+} from "./settings.ts";
 
 export { formatFooterStatus } from "./observability/status.ts";
 export type { CodexRecoveryRuntime } from "./optimization/recovery/codex.ts";
@@ -108,6 +121,28 @@ function recoveryControl(enforcement: EnforcementControl): CodexRecoveryControl
 		: { isCodexRecoveryEnabled: () => false, setCodexRecoveryEnabled() {} };
 }
 
+/**
+ * Falls back to "off" (never "suggest", the real persisted default in persistentEnforcementControl
+ * itself) when the passed-in control doesn't implement AutoModeControl -- e.g. a test harness's
+ * minimal enforcement-only fake. Matches usageBudgetControl/recoveryControl's own conservative
+ * fallback stubs: assume the feature is off/unconfigured rather than defaulting it on somewhere
+ * a caller never actually wired real persisted state for it.
+ */
+function autoModeControl(enforcement: EnforcementControl): AutoModeControl {
+	const candidate = enforcement as EnforcementControl & Partial<AutoModeControl>;
+	return typeof candidate.getAutoMode === "function" &&
+		typeof candidate.setAutoMode === "function" &&
+		typeof candidate.isAutoModeVerbose === "function" &&
+		typeof candidate.setAutoModeVerbose === "function"
+		? {
+				getAutoMode: () => candidate.getAutoMode!(),
+				setAutoMode: (mode) => candidate.setAutoMode!(mode),
+				isAutoModeVerbose: () => candidate.isAutoModeVerbose!(),
+				setAutoModeVerbose: (verbose) => candidate.setAutoModeVerbose!(verbose),
+			}
+		: { getAutoMode: () => "off", setAutoMode() {}, isAutoModeVerbose: () => false, setAutoModeVerbose() {} };
+}
+
 async function recordMetrics(client: JittorExtensionClient, metrics: MetricObservation[]): Promise<void> {
 	if (metrics.length === 0) return;
 	// One atomic transaction rather than a per-metric RPC loop: a later observation in the same
@@ -404,12 +439,57 @@ export function registerJittorExtension(
 	codexRecovery: CodexRecoveryControl = recoveryControl(enforcement),
 	recoveryRuntime: CodexRecoveryRuntime = SYSTEM_RECOVERY_RUNTIME,
 	contextGrowth: ContextGrowthCapability = new ContextGrowthCapability(),
+	autoMode: AutoModeControl = autoModeControl(enforcement),
 ): void {
 	const footerState: IntegratedFooterState = { providerBudget: null };
 	const usageBudgets = usageBudgetControl(enforcement);
 	let compactionTelemetry = new CompactionTelemetry();
 	let contextGrowthTurn = 0;
 	const localRunTelemetry = new LocalRunTelemetry();
+	// Auto mode's own turn-boundary state: the just-received user text and the completed prior
+	// turn's tool-call mix feed classifyEffort; autoModeState remembers the last-seen effort and
+	// any dismissed suggestion (see optimization/auto-mode.ts's own anti-nag doc comment).
+	let pendingUserText: string | null = null;
+	let currentTurnToolNames: string[] = [];
+	let priorTurnToolNames: string[] = [];
+	const autoModeState = newAutoModeSessionState();
+	let autoModeSwitchNotifiedThisSession = false;
+	// Advisory/best-effort by construction: any failure here must never block or halt the turn the
+	// way budget enforcement's own fail-closed halt does -- callers wrap this in try/catch and swallow.
+	// Bind-beforehand: a Papyrus task focused with a declared `extra.effort` pins routing to that
+	// effort for as long as it stays focused -- no live per-turn detection needed for that task.
+	// Live classification remains the fallback whenever no task is focused, or the focused task
+	// declares no effort. Reset semantics mirror focusedTaskId's own handling below.
+	const runAutoModeTurn = async (ctx: ExtensionContext): Promise<void> => {
+		const mode = autoMode.getAutoMode();
+		if (mode === "off" || !ctx.model) return;
+		const candidates = benchmarkCandidatesFromPi(scopedOrAvailableModels(ctx), pi.getThinkingLevel());
+		if (candidates.length === 0) return;
+		const currentCandidate: ModelCandidate = { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() };
+		const effort = declaredEffort ?? classifyEffort({ userText: pendingUserText ?? "", priorTurnToolNames }).effort;
+		const ranking = await fetchBenchmarkRanking(ctx, client, candidates, "general", "general", effort, currentCandidate);
+		const decision = decideAutoMode({ mode, effort, ranking, state: autoModeState });
+		if (decision.kind === "switch") {
+			const applied = await applyRoute(pi, ctx, decision.candidate);
+			if (applied && !autoModeSwitchNotifiedThisSession) {
+				ctx.ui.notify(`Jittor auto-switched to ${candidateIdentityOf(decision.candidate)} (effort: ${effort}).`, "info");
+				autoModeSwitchNotifiedThisSession = true;
+			}
+		} else if (decision.kind === "suggest") {
+			const choice = await showAutoModeSuggestion(
+				ctx,
+				decision.candidate,
+				effort,
+				decision.utilityDelta,
+				decision.confidence,
+				ranking,
+				`${currentCandidate.provider}/${currentCandidate.model}`,
+				autoMode.isAutoModeVerbose(),
+			);
+			if (choice === "switch") await applyRoute(pi, ctx, decision.candidate);
+			else recordAutoModeDismissal(autoModeState, decision.candidate);
+		}
+	};
 	const providerResponseTelemetry = new ProviderResponseTelemetry();
 	const codexRecoveryCapability = new CodexRecoveryCapability(pi, codexRecovery, recoveryRuntime);
 	const contextHub = new ContextHubCapability();
@@ -494,11 +574,14 @@ export function registerJittorExtension(
 	// affect this one's attribution.
 	let currentSessionId: string | undefined;
 	let focusedTaskId: string | null = null;
+	// Read by runAutoModeTurn (declared above, only ever invoked later) as the bind-beforehand pin.
+	let declaredEffort: ModelTaskEffort | null = null;
 	const stopPapyrusTaskFocus = pi.events?.on?.(PAPYRUS_TASK_FOCUS_CHANNEL, (payload) => {
 		try {
 			const event = validateTaskFocusEvent(payload);
 			if (event.sessionId !== undefined && event.sessionId !== currentSessionId) return;
 			focusedTaskId = applyTaskFocusEvent(event);
+			declaredEffort = declaredEffortFromTaskFocusEvent(event);
 		} catch {
 			// Reject malformed or stale cross-extension events without retaining payloads or crashing the extension.
 		}
@@ -595,6 +678,7 @@ export function registerJittorExtension(
 					enforcement,
 					recovery: codexRecovery,
 					budgets: usageBudgets,
+					autoMode,
 					effects: {
 						setEnforcement: async (enabled) => (enabled ? enable(ctx) : disable(ctx)),
 						setFooter: async (enabled) => {
@@ -606,6 +690,8 @@ export function registerJittorExtension(
 							if (!enabled) cancelRecovery(true);
 							await codexRecovery.setCodexRecoveryEnabled(enabled);
 						},
+						setAutoMode: (mode) => autoMode.setAutoMode(mode),
+						setAutoModeVerbose: (verbose) => autoMode.setAutoModeVerbose(verbose),
 					},
 				},
 				status: { client },
@@ -615,6 +701,11 @@ export function registerJittorExtension(
 					currentIdentity: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "",
 					domain: benchmarksTask?.domain ?? "general",
 					type: benchmarksTask?.type ?? "general",
+					// This on-demand panel is not tied to a live turn, so it always uses the neutral
+					// "medium" effort (matching the pre-effort-axis cost weighting exactly) -- live
+					// per-turn effort detection feeds the turn_start Auto-mode decision path instead.
+					effort: "medium",
+					currentCandidate: ctx.model ? { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() } : null,
 				},
 				cache: { client, windowMs: 7 * MILLISECONDS_PER_DAY },
 			});
@@ -821,6 +912,7 @@ export function registerJittorExtension(
 	pi.on("session_start", async (_event, ctx) => {
 		currentSessionId = ctx.sessionManager.getSessionId();
 		focusedTaskId = null;
+		declaredEffort = null;
 		finishCompactionUi();
 		compactionTelemetry = new CompactionTelemetry();
 		contextGrowthTurn = 0;
@@ -918,7 +1010,13 @@ export function registerJittorExtension(
 	});
 
 	pi.on("input", async (event, ctx) => {
-		if (event.source !== "extension") cancelRecovery(true);
+		if (event.source !== "extension") {
+			cancelRecovery(true);
+			// Auto mode's own effort classifier reads this at the next turn_start -- captured
+			// unconditionally (independent of enforcement.isEnabled()) since Auto mode is a
+			// separate, independently-toggled feature from budget enforcement.
+			pendingUserText = event.text;
+		}
 		if (event.source === "extension" || !enforcement.isEnabled()) return { action: "continue" as const };
 		try {
 			const next = (await client.call("router.decide", { session_id: ctx.sessionManager.getSessionId() })) as PolicyDecision;
@@ -950,20 +1048,26 @@ export function registerJittorExtension(
 		codexRecoveryCapability.resetTurn();
 		providerResponseTelemetry.resetTurn();
 		localRunTelemetry.beginTurn(event.timestamp);
-		if (!enforcement.isEnabled()) return;
-		try {
-			await syncCurrentRoute(pi, client, ctx);
-			await syncAvailableRoutes(pi, client, ctx);
-			await applyDecision(
-				pi,
-				client,
-				ctx,
-				(await client.call("router.decide", { session_id: ctx.sessionManager.getSessionId() })) as PolicyDecision,
-			);
-			await refreshFooter(client, footerState, ctx.sessionManager.getSessionId());
-		} catch {
-			halt(ctx, "Jittor could not verify or apply a safe route");
+		// Budget/enforcement routing is safety-critical and always wins on conflict: Auto mode is
+		// only evaluated when budget pressure required no action this turn (action === "continue"),
+		// so the two decision sources never fight over the model mid-turn.
+		let budgetActedThisTurn = false;
+		if (enforcement.isEnabled()) {
+			try {
+				await syncCurrentRoute(pi, client, ctx);
+				await syncAvailableRoutes(pi, client, ctx);
+				const budgetDecision = (await client.call("router.decide", {
+					session_id: ctx.sessionManager.getSessionId(),
+				})) as PolicyDecision;
+				budgetActedThisTurn = budgetDecision.action !== "continue";
+				await applyDecision(pi, client, ctx, budgetDecision);
+				await refreshFooter(client, footerState, ctx.sessionManager.getSessionId());
+			} catch {
+				halt(ctx, "Jittor could not verify or apply a safe route");
+				return;
+			}
 		}
+		if (!budgetActedThisTurn) await runAutoModeTurn(ctx).catch(() => undefined);
 	});
 
 	pi.on("message_update", async (event) => {
@@ -974,6 +1078,10 @@ export function registerJittorExtension(
 		localRunTelemetry.onToolExecutionEnd(event.toolName, event.isError);
 		const classification = classifyTaskFromTools([event.toolName]);
 		compactionTelemetry.observeToolClass(`${classification.domain}-${classification.type}`, event.isError);
+		// Bounded accumulation for the effort classifier's tool-call-mix signal -- classifyEffort
+		// itself would slice defensively too, but there's no reason to grow this array unboundedly
+		// across a very long turn in the meantime.
+		if (currentTurnToolNames.length < EFFORT_CLASSIFICATION_MAX_TOOL_NAMES) currentTurnToolNames.push(event.toolName);
 	});
 
 	pi.on("after_provider_response", async (event, ctx) => {
@@ -991,6 +1099,8 @@ export function registerJittorExtension(
 		if (typeof tokens === "number" && Number.isFinite(tokens)) contextGrowth.observe(++contextGrowthTurn, tokens);
 		const metrics = localRunTelemetry.completeTurn(event.message, pi.getThinkingLevel());
 		await recordMetrics(client, metrics).catch(() => undefined);
+		priorTurnToolNames = currentTurnToolNames;
+		currentTurnToolNames = [];
 	});
 
 	pi.on("message_end", async (event, ctx) => {

package/extension/src/jittor-shell.ts

@@ -19,7 +19,7 @@
  * shell first opens. Switching to a tab that has never been visited fetches it once, on first
  * visit, not before.
  */
-import type { ModelCandidate, ModelRankingResult, ModelTaskDomain, ModelTaskType, RouterStatus } from "@danypops/jittor";
+import type { ModelCandidate, ModelRankingResult, ModelTaskDomain, ModelTaskEffort, ModelTaskType, RouterStatus } from "@danypops/jittor";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { BorderedSelectPanel, type MnemonicContext, type TabBarTheme, TabbedContainer, type TextMeasure } from "malevich-tui-components";
@@ -46,7 +46,7 @@ import {
 	fetchBenchmarkRanking,
 	showBenchmarkPanel,
 } from "./optimization/model-selection-panel.ts";
-import type { CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
+import type { AutoModeControl, CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
 import {
 	createSettingsPanel,
 	runSettingsAction,
@@ -64,6 +64,7 @@ export interface JittorShellDeps {
 		enforcement: EnforcementControl;
 		recovery: CodexRecoveryControl;
 		budgets: UsageBudgetControl;
+		autoMode: AutoModeControl;
 		effects: SettingsEffects;
 	};
 	status: { client: JittorPanelClient };
@@ -73,6 +74,8 @@ export interface JittorShellDeps {
 		currentIdentity: string;
 		domain: ModelTaskDomain;
 		type: ModelTaskType;
+		effort: ModelTaskEffort;
+		currentCandidate: ModelCandidate | null;
 	};
 	cache: { client: CacheEconomicsPanelClient; windowMs: number; now?: () => number };
 }
@@ -158,7 +161,7 @@ async function ensureLoaded(
 ): Promise<void> {
 	// Settings reads already-in-memory persisted state -- no daemon round trip, so eagerly keeping
 	// it fresh costs nothing and never violates "no network call for a tab never visited".
-	state.settings = settingsSnapshot(deps.settings.enforcement, deps.settings.recovery, deps.settings.budgets);
+	state.settings = settingsSnapshot(deps.settings.enforcement, deps.settings.recovery, deps.settings.budgets, deps.settings.autoMode);
 	if (activeKey === "status" && state.status === undefined) {
 		state.status = await fetchStatusSnapshot(deps.status.client, ctx.sessionManager.getSessionId());
 	}
@@ -169,6 +172,8 @@ async function ensureLoaded(
 			deps.benchmarks.candidates,
 			deps.benchmarks.domain,
 			deps.benchmarks.type,
+			deps.benchmarks.effort,
+			deps.benchmarks.currentCandidate,
 		);
 	}
 	if (activeKey === "cache" && state.cache === undefined) {
@@ -205,7 +210,14 @@ function tabBarTheme(theme: ShellTheme): TabBarTheme {
  */
 async function showNonTuiFallback(ctx: ExtensionCommandContext, deps: JittorShellDeps, initialTab: JittorTabKey): Promise<void> {
 	if (initialTab === "settings")
-		return showSettingsPanel(ctx, deps.settings.enforcement, deps.settings.recovery, deps.settings.budgets, deps.settings.effects);
+		return showSettingsPanel(
+			ctx,
+			deps.settings.enforcement,
+			deps.settings.recovery,
+			deps.settings.budgets,
+			deps.settings.autoMode,
+			deps.settings.effects,
+		);
 	if (initialTab === "status") return showJittorPanel(ctx, deps.status.client);
 	if (initialTab === "benchmarks")
 		return showBenchmarkPanel(
@@ -215,6 +227,8 @@ async function showNonTuiFallback(ctx: ExtensionCommandContext, deps: JittorShel
 			deps.benchmarks.currentIdentity,
 			deps.benchmarks.domain,
 			deps.benchmarks.type,
+			deps.benchmarks.effort,
+			deps.benchmarks.currentCandidate,
 		);
 	return showCacheEconomicsPanel(ctx, deps.cache.client, deps.cache.windowMs, deps.cache.now);
 }
@@ -314,6 +328,7 @@ export async function showJittorShell(
 				deps.settings.recovery,
 				deps.settings.budgets,
 				deps.settings.effects,
+				deps.settings.autoMode,
 			);
 			continue;
 		}

package/extension/src/optimization/auto-mode-dialog.ts

@@ -0,0 +1,108 @@
+/**
+ * Suggest-mode's real interactive surface: a compact one-line Dialog (Switch / Details / Not
+ * now) with Details expanding into the existing benchmark panel's full component/confidence/
+ * provenance breakdown before the user decides -- both verbosity levels are supported, never
+ * just one. Reuses `createBenchmarkPanel` rather than building a second detail renderer.
+ */
+
+import type { ModelCandidate, ModelRankingResult, ModelTaskEffort } from "@danypops/jittor";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Dialog, type TextMeasure } from "malevich-tui-components";
+import { candidateIdentityOf } from "./auto-mode.ts";
+import { createBenchmarkPanel } from "./model-selection-panel.ts";
+
+export type AutoModeSuggestionChoice = "switch" | "dismiss";
+
+interface SuggestionTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+const hostTextMeasure: TextMeasure = { visibleWidth, truncateToWidth };
+
+function summaryLine(candidate: ModelCandidate, effort: ModelTaskEffort, utilityDelta: number, confidence: number): string {
+	return `Jittor suggests ${candidateIdentityOf(candidate)} for this turn -- effort: ${effort}, +${utilityDelta.toFixed(2)} utility, ${(confidence * 100).toFixed(0)}% confidence.`;
+}
+
+/** Shows the existing benchmark breakdown as a read-only detail view; any dismissal (Esc, "r", Ctrl+C) returns control to the caller, which re-shows the compact decision dialog. */
+async function showSuggestionDetails(ctx: ExtensionContext, ranking: ModelRankingResult, currentIdentity: string): Promise<void> {
+	await ctx.ui.custom<"close">((_tui, theme: SuggestionTheme, _keybindings, done) => {
+		const panel = createBenchmarkPanel(ranking, currentIdentity, theme, () => done("close"), true);
+		return {
+			invalidate: () => panel.invalidate(),
+			render: (width: number) => panel.render(width),
+			handleInput(data: string): void {
+				if (matchesKey(data, "ctrl+c")) {
+					done("close");
+					return;
+				}
+				panel.handleInput(data);
+			},
+		};
+	});
+}
+
+/**
+ * Non-TUI (`ctx.mode !== "tui"`) mode has no interactive dialog to show, matching every other
+ * jittor confirmation's own non-TUI fallback -- it stays a plain notify and the suggestion is
+ * treated as dismissed (advisory-only; the user reads it, no automatic action follows).
+ */
+export async function showAutoModeSuggestion(
+	ctx: ExtensionContext,
+	candidate: ModelCandidate,
+	effort: ModelTaskEffort,
+	utilityDelta: number,
+	confidence: number,
+	ranking: ModelRankingResult,
+	currentIdentity: string,
+	verboseByDefault: boolean,
+): Promise<AutoModeSuggestionChoice> {
+	const summary = summaryLine(candidate, effort, utilityDelta, confidence);
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(`${summary} Run /jittor benchmarks for details.`, "info");
+		return "dismiss";
+	}
+	let showDetails = verboseByDefault;
+	for (;;) {
+		if (showDetails) {
+			await showSuggestionDetails(ctx, ranking, currentIdentity);
+			showDetails = false;
+			continue;
+		}
+		const choice = await ctx.ui.custom<AutoModeSuggestionChoice | "details">((_tui, theme: SuggestionTheme, _keybindings, done) => {
+			const dialog = new Dialog({
+				title: "Jittor suggestion",
+				body: summary,
+				actions: [
+					{ label: "Switch", key: "s", action: () => done("switch") },
+					{ label: "Details", key: "d", action: () => done("details") },
+					{ label: "Not now", key: "n", action: () => done("dismiss") },
+				],
+				theme: {
+					border: (text) => theme.fg("borderMuted", text),
+					title: theme.bold,
+					body: (text) => text,
+					dim: (text) => theme.fg("dim", text),
+				},
+				measure: hostTextMeasure,
+			});
+			return {
+				invalidate: () => dialog.invalidate(),
+				render: (width: number) => dialog.render(width),
+				handleInput(data: string): void {
+					if (matchesKey(data, "ctrl+c")) {
+						done("dismiss");
+						return;
+					}
+					dialog.handleInput(data);
+				},
+			};
+		});
+		if (choice === "details") {
+			showDetails = true;
+			continue;
+		}
+		return choice ?? "dismiss";
+	}
+}

package/extension/src/optimization/auto-mode.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure effort-based Auto mode decision logic -- deliberately separate from the existing
+ * budget-pressure `JittorRouter`/`applyDecision` path (optimization/routing), which reacts to
+ * provider quota pressure, not task complexity. The two compose at the call site (index.ts's
+ * `turn_start` handler): budget/enforcement always takes precedence on conflict, matching the
+ * design recorded in Doc "Auto mode: effort-aware model routing -- prior art and design".
+ *
+ * This module owns only the decision (what should happen this turn, given a fresh ranking
+ * result and the anti-nag session state) -- never the side effect itself (showing a dialog,
+ * calling `pi.setModel`, persisting a setting). That stays in index.ts, so this logic is fully
+ * unit-testable without mocking any Pi/TUI surface.
+ */
+import type { ModelCandidate, ModelRankingResult, ModelTaskEffort } from "@danypops/jittor";
+
+export const AUTO_MODE_SETTINGS = ["off", "suggest", "auto-switch"] as const;
+export type AutoModeSetting = (typeof AUTO_MODE_SETTINGS)[number];
+
+export interface AutoModeSessionState {
+	lastEffort: ModelTaskEffort | null;
+	dismissedIdentity: string | null;
+}
+
+export function newAutoModeSessionState(): AutoModeSessionState {
+	return { lastEffort: null, dismissedIdentity: null };
+}
+
+export function candidateIdentityOf(candidate: ModelCandidate): string {
+	return `${candidate.provider}/${candidate.model}:${candidate.thinking}`;
+}
+
+export interface AutoModeDecisionInput {
+	mode: AutoModeSetting;
+	/** The effort level this turn was classified/declared as -- only used to decide whether to re-evaluate a previously dismissed suggestion, never re-derived here. */
+	effort: ModelTaskEffort;
+	/** A ranking result already computed with this turn's effort and current model as its own uplift-gate baseline (see rankModelCandidates). */
+	ranking: ModelRankingResult;
+	state: AutoModeSessionState;
+}
+
+export type AutoModeDecision =
+	| { kind: "none" }
+	| { kind: "suggest"; candidate: ModelCandidate; utilityDelta: number; confidence: number }
+	| { kind: "switch"; candidate: ModelCandidate };
+
+/**
+ * Anti-nag bound: a Suggest-mode dismissal for one specific candidate identity is remembered and
+ * not re-offered again until either the detected/declared effort changes, or the recommended
+ * candidate itself changes (a stronger, different upgrade is always worth surfacing). The uplift
+ * gate inside `rankModelCandidates` itself is the primary anti-spam mechanism -- this only
+ * prevents re-nagging about the exact same already-declined suggestion every single turn.
+ */
+export function decideAutoMode(input: AutoModeDecisionInput): AutoModeDecision {
+	const { mode, effort, ranking, state } = input;
+	const effortChanged = state.lastEffort !== effort;
+	state.lastEffort = effort;
+	if (mode === "off") return { kind: "none" };
+	const recommendation = ranking.recommendation;
+	if (!recommendation) {
+		state.dismissedIdentity = null;
+		return { kind: "none" };
+	}
+	const identity = candidateIdentityOf(recommendation.candidate);
+	if (!effortChanged && state.dismissedIdentity === identity) return { kind: "none" };
+	if (mode === "auto-switch") return { kind: "switch", candidate: recommendation.candidate };
+	return {
+		kind: "suggest",
+		candidate: recommendation.candidate,
+		utilityDelta: recommendation.utilityDelta,
+		confidence: recommendation.confidence,
+	};
+}
+
+export function recordAutoModeDismissal(state: AutoModeSessionState, candidate: ModelCandidate): void {
+	state.dismissedIdentity = candidateIdentityOf(candidate);
+}

package/extension/src/optimization/model-selection-panel.ts

@@ -9,11 +9,12 @@ import {
 	type ModelCandidate,
 	type ModelRankingResult,
 	type ModelTaskDomain,
+	type ModelTaskEffort,
 	type ModelTaskType,
 	type RankedModel,
 	type UtilityComponentName,
 } from "@danypops/jittor";
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { BorderedSelectPanel, Table, type TextMeasure } from "malevich-tui-components";
 import { sessionSecretField } from "../session-identity.ts";
@@ -130,22 +131,39 @@ export function renderBenchmarkView(result: ModelRankingResult, currentIdentity:
 	return createBenchmarkPanel(result, currentIdentity, theme, () => undefined).render(Math.max(1, width));
 }
 
+/**
+ * Pi's own `--models`/`enabledModels` scoping (`ctx.scopedModels`, the same set the
+ * `/scoped-models` command shows) is the exact-session authority once it is configured -- an
+ * empty list means "no scoping configured" (matching Pi's own semantics), not "scoped to
+ * nothing", and stays advisory. Mirrors the identical predicate `scopedOrAvailableModels` in
+ * `index.ts` already uses to build the candidate set itself; this call site independently
+ * hardcoded `"available-models"` after that fix landed, which kept automatic selection
+ * disabled for a reason (Pi lacking `ctx.scopedModels`) that no longer exists.
+ */
+function scopeAuthorityFor(ctx: ExtensionContext): ModelRankingResult["scopeAuthority"] {
+	return ctx.scopedModels.length > 0 ? "exact-session" : "available-models";
+}
+
 /** Shared by the standalone benchmark panel below and the unified /jittor shell, so both fetch identically. */
 export async function fetchBenchmarkRanking(
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	client: BenchmarkPanelClient,
 	candidates: ModelCandidate[],
 	domain: ModelTaskDomain,
 	type: ModelTaskType,
+	effort: ModelTaskEffort,
+	currentCandidate: ModelCandidate | null,
 ): Promise<ModelRankingResult> {
 	const session_id = ctx.sessionManager.getSessionId();
 	return (await client.call("models.rank", {
 		candidates,
 		session_id,
 		...sessionSecretField(session_id),
-		scopeAuthority: "available-models",
+		scopeAuthority: scopeAuthorityFor(ctx),
 		domain,
 		type,
+		effort,
+		currentCandidate,
 		budgetPressure: 0,
 		weights: {
 			quality: MODEL_RANKING_DEFAULT_QUALITY_WEIGHT,
@@ -165,9 +183,11 @@ export async function showBenchmarkPanel(
 	currentIdentity: string,
 	domain: ModelTaskDomain,
 	type: ModelTaskType,
+	effort: ModelTaskEffort,
+	currentCandidate: ModelCandidate | null,
 ): Promise<void> {
 	for (;;) {
-		const result = await fetchBenchmarkRanking(ctx, client, candidates, domain, type);
+		const result = await fetchBenchmarkRanking(ctx, client, candidates, domain, type, effort, currentCandidate);
 		if (ctx.mode !== "tui") {
 			ctx.ui.notify(
 				renderBenchmarkView(result, currentIdentity, 100, { fg: (_color, text) => text, bold: (text) => text }).join("\n"),

package/extension/src/settings-tui.ts

@@ -2,7 +2,8 @@ import { USAGE_PERIODS, type UsagePeriod } from "@danypops/jittor";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { BorderedSelectPanel, Menu, type MenuTheme, type TextMeasure } from "malevich-tui-components";
-import type { CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
+import { AUTO_MODE_SETTINGS, type AutoModeSetting } from "./optimization/auto-mode.ts";
+import type { AutoModeControl, CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
 import { showConfirmDialog } from "./tui-prompts.ts";
 
 export interface SettingsSnapshot {
@@ -10,6 +11,8 @@ export interface SettingsSnapshot {
 	footerEnabled: boolean;
 	codexRecoveryEnabled: boolean;
 	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+	autoMode: AutoModeSetting;
+	autoModeVerbose: boolean;
 }
 
 interface SettingsTheme {
@@ -17,26 +20,37 @@ interface SettingsTheme {
 	bold(text: string): string;
 }
 
-export type SettingsKey = "enforcement" | "footer" | "recovery" | `budget-${UsagePeriod}`;
+export type SettingsKey = "enforcement" | "auto-mode" | "auto-mode-verbose" | "footer" | "recovery" | `budget-${UsagePeriod}`;
 export type SettingsAction = { kind: "activate"; key: SettingsKey } | { kind: "close" };
 
 export interface SettingsEffects {
 	setEnforcement(enabled: boolean): void | Promise<void>;
 	setFooter(enabled: boolean): void | Promise<void>;
 	setRecovery(enabled: boolean): void | Promise<void>;
+	setAutoMode(mode: AutoModeSetting): void | Promise<void>;
+	setAutoModeVerbose(verbose: boolean): void | Promise<void>;
 }
 
-// Enforcement -> Budget -> Providers -> UI: safety posture (the global kill-switch everything
-// else is downstream of) leads, followed by spend limits, then provider-specific quirks (today,
-// only Codex recovery -- grouped under its own header instead of sitting flat next to global
-// switches, which read as "too Codex-oriented" with nothing to signal its narrower scope), then
-// display preferences last.
-const SETTINGS_KEYS: SettingsKey[] = ["enforcement", ...USAGE_PERIODS.map(({ id }) => `budget-${id}` as const), "recovery", "footer"];
+// Enforcement -> Routing -> Budget -> Providers -> UI: safety posture (the global kill-switch
+// everything else is downstream of) leads, followed by effort-based Auto mode (a routing
+// behavior, not a safety switch, but consequential enough to sit right after Enforcement), then
+// spend limits, then provider-specific quirks (today, only Codex recovery -- grouped under its
+// own header instead of sitting flat next to global switches, which read as "too Codex-oriented"
+// with nothing to signal its narrower scope), then display preferences last.
+const SETTINGS_KEYS: SettingsKey[] = [
+	"enforcement",
+	"auto-mode",
+	"auto-mode-verbose",
+	...USAGE_PERIODS.map(({ id }) => `budget-${id}` as const),
+	"recovery",
+	"footer",
+];
 
-type SettingsCategory = "Enforcement" | "Budget" | "Providers" | "UI";
+type SettingsCategory = "Enforcement" | "Routing" | "Budget" | "Providers" | "UI";
 
 function categoryOf(key: SettingsKey): SettingsCategory {
 	if (key === "enforcement") return "Enforcement";
+	if (key === "auto-mode" || key === "auto-mode-verbose") return "Routing";
 	if (key === "recovery") return "Providers";
 	if (key === "footer") return "UI";
 	return "Budget";
@@ -51,8 +65,16 @@ function budgetLabel(period: UsagePeriod, snapshot: SettingsSnapshot): string {
 	return value === undefined ? "not configured" : `${value.toLocaleString()} tokens`;
 }
 
+function autoModeLabel(mode: AutoModeSetting, theme: SettingsTheme): string {
+	if (mode === "off") return theme.fg("muted", "OFF");
+	if (mode === "auto-switch") return theme.fg("success", "AUTO-SWITCH");
+	return theme.fg("accent", "SUGGEST");
+}
+
 function rowText(key: SettingsKey, snapshot: SettingsSnapshot, theme: SettingsTheme): string {
 	if (key === "enforcement") return `Routing enforcement  ${state(snapshot.enforcementEnabled, theme)}`;
+	if (key === "auto-mode") return `Auto mode  ${autoModeLabel(snapshot.autoMode, theme)}`;
+	if (key === "auto-mode-verbose") return `Suggestion details  ${state(snapshot.autoModeVerbose, theme)}`;
 	if (key === "footer") return `Informational footer  ${state(snapshot.footerEnabled, theme)}`;
 	if (key === "recovery") return `Codex recovery  ${state(snapshot.codexRecoveryEnabled, theme)}`;
 	const period = key.slice("budget-".length) as UsagePeriod;
@@ -63,12 +85,15 @@ export function settingsSnapshot(
 	enforcement: EnforcementControl,
 	recovery: CodexRecoveryControl,
 	budgets: UsageBudgetControl,
+	autoMode: AutoModeControl,
 ): SettingsSnapshot {
 	return {
 		enforcementEnabled: enforcement.isEnabled(),
 		footerEnabled: enforcement.isFooterEnabled(),
 		codexRecoveryEnabled: recovery.isCodexRecoveryEnabled(),
 		usageTokenBudgets: Object.fromEntries(USAGE_PERIODS.map(({ id }) => [id, budgets.getUsageTokenBudget(id)])),
+		autoMode: autoMode.getAutoMode(),
+		autoModeVerbose: autoMode.isAutoModeVerbose(),
 	};
 }
 
@@ -201,8 +226,31 @@ export async function runSettingsAction(
 	recovery: CodexRecoveryControl,
 	budgets: UsageBudgetControl,
 	effects: SettingsEffects,
+	autoMode: AutoModeControl,
 ): Promise<void> {
 	if (action.kind === "close") return;
+	if (action.key === "auto-mode") {
+		const current = autoMode.getAutoMode();
+		const next = AUTO_MODE_SETTINGS[(AUTO_MODE_SETTINGS.indexOf(current) + 1) % AUTO_MODE_SETTINGS.length]!;
+		// Entering the highest-autonomy state gets the same explicit confirmation Codex recovery's
+		// own opt-in already gets; leaving it (like disabling enforcement) needs none -- becoming
+		// more conservative is never something to gate behind a confirmation.
+		if (next === "auto-switch") {
+			if (
+				await showConfirmDialog(
+					ctx,
+					"Enable Auto-switch?",
+					"Jittor may switch your active model on its own when a turn's effort clearly calls for a different one, with no confirmation prompt.",
+				)
+			)
+				await effects.setAutoMode(next);
+		} else await effects.setAutoMode(next);
+		return;
+	}
+	if (action.key === "auto-mode-verbose") {
+		await effects.setAutoModeVerbose(!autoMode.isAutoModeVerbose());
+		return;
+	}
 	if (action.key === "enforcement") {
 		if (enforcement.isEnabled()) {
 			if (
@@ -241,19 +289,22 @@ export async function showSettingsPanel(
 	enforcement: EnforcementControl,
 	recovery: CodexRecoveryControl,
 	budgets: UsageBudgetControl,
+	autoMode: AutoModeControl,
 	effects: SettingsEffects = {
 		setEnforcement: (enabled) => enforcement.setEnabled(enabled),
 		setFooter: (enabled) => enforcement.setFooterEnabled(enabled),
 		setRecovery: (enabled) => recovery.setCodexRecoveryEnabled(enabled),
+		setAutoMode: (mode) => autoMode.setAutoMode(mode),
+		setAutoModeVerbose: (verbose) => autoMode.setAutoModeVerbose(verbose),
 	},
 ): Promise<void> {
 	if (ctx.mode !== "tui") {
-		const snapshot = settingsSnapshot(enforcement, recovery, budgets);
+		const snapshot = settingsSnapshot(enforcement, recovery, budgets, autoMode);
 		ctx.ui.notify(["Jittor Settings", ...SETTINGS_KEYS.map((key) => rowText(key, snapshot, plainTheme()))].join("\n"), "info");
 		return;
 	}
 	for (;;) {
-		const snapshot = settingsSnapshot(enforcement, recovery, budgets);
+		const snapshot = settingsSnapshot(enforcement, recovery, budgets, autoMode);
 		const action = await ctx.ui.custom<SettingsAction>((tui, theme, _keybindings, done) => {
 			const panel = createSettingsPanel(snapshot, theme, done);
 			return {
@@ -266,6 +317,6 @@ export async function showSettingsPanel(
 			};
 		});
 		if (!action || action.kind === "close") return;
-		await runSettingsAction(ctx, action, enforcement, recovery, budgets, effects);
+		await runSettingsAction(ctx, action, enforcement, recovery, budgets, effects, autoMode);
 	}
 }

package/extension/src/settings.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { JITTOR_EXTENSION_SETTINGS_FILENAME, JITTOR_STATE_DIRECTORY, USAGE_PERIODS, type UsagePeriod } from "@danypops/jittor";
 import { createAtomicJsonWriter } from "@danypops/vehicle-core";
 import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
+import { AUTO_MODE_SETTINGS, type AutoModeSetting } from "./optimization/auto-mode.ts";
 
 const atomicJson = createAtomicJsonWriter({ fs: createNodeAtomicJsonFsAdapter() });
 
@@ -30,17 +31,35 @@ export interface UsageBudgetControl {
 	setUsageTokenBudget(period: UsagePeriod, tokens: number | undefined): void | Promise<void>;
 }
 
-export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl, UsageBudgetControl {}
+export interface AutoModeControl {
+	getAutoMode(): AutoModeSetting;
+	setAutoMode(mode: AutoModeSetting): void | Promise<void>;
+	/** Whether a Suggest-mode dialog opens straight to the full benchmark breakdown instead of requiring the "Details" keypress. Purely a display preference -- never changes what action is taken. */
+	isAutoModeVerbose(): boolean;
+	setAutoModeVerbose(verbose: boolean): void | Promise<void>;
+}
+
+export interface PersistentExtensionControl extends EnforcementControl, CodexRecoveryControl, UsageBudgetControl, AutoModeControl {}
 
 interface ExtensionSettings {
 	enforcementEnabled: boolean;
 	footerEnabled: boolean;
 	codexRecoveryEnabled: boolean;
 	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+	/** Suggest, not Auto-switch, is the recorded default -- Auto-switch (an active mutation) is fully available from day one but never silently pre-selected, per this project's shadow-mode-first governance for optimization interventions. */
+	autoMode: AutoModeSetting;
+	autoModeVerbose: boolean;
 }
 
 function defaultSettings(): ExtensionSettings {
-	return { enforcementEnabled: true, footerEnabled: true, codexRecoveryEnabled: false, usageTokenBudgets: {} };
+	return {
+		enforcementEnabled: true,
+		footerEnabled: true,
+		codexRecoveryEnabled: false,
+		usageTokenBudgets: {},
+		autoMode: "suggest",
+		autoModeVerbose: false,
+	};
 }
 
 function parseUsageTokenBudgets(value: unknown): Partial<Record<UsagePeriod, number>> {
@@ -69,6 +88,8 @@ function loadSettings(path: string): ExtensionSettings {
 			footerEnabled: record.footerEnabled !== false,
 			codexRecoveryEnabled: record.codexRecoveryEnabled === true,
 			usageTokenBudgets: parseUsageTokenBudgets(record.usageTokenBudgets),
+			autoMode: AUTO_MODE_SETTINGS.includes(record.autoMode as AutoModeSetting) ? (record.autoMode as AutoModeSetting) : "suggest",
+			autoModeVerbose: record.autoModeVerbose === true,
 		};
 	} catch {
 		return defaultSettings();
@@ -109,5 +130,16 @@ export function persistentEnforcementControl(env: Record<string, string | undefi
 			else settings.usageTokenBudgets[period] = tokens;
 			await persistSettings(path, settings);
 		},
+		getAutoMode: () => settings.autoMode,
+		async setAutoMode(mode): Promise<void> {
+			if (!AUTO_MODE_SETTINGS.includes(mode)) throw new Error("auto mode must be one of off, suggest, auto-switch");
+			settings.autoMode = mode;
+			await persistSettings(path, settings);
+		},
+		isAutoModeVerbose: () => settings.autoModeVerbose,
+		async setAutoModeVerbose(verbose): Promise<void> {
+			settings.autoModeVerbose = verbose;
+			await persistSettings(path, settings);
+		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-jittor",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Pi extension for Jittor token and context observability with optimization controls backed by the @danypops/jittor daemon",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,7 @@
     "@danypops/vehicle-client": "^0.10.1",
     "@danypops/vehicle-core": "^0.17.1",
     "@danypops/vehicle-server": "^0.25.1",
-    "@danypops/jittor": "^0.18.0",
+    "@danypops/jittor": "^0.20.0",
     "malevich-tui-components": "^0.28.0"
   },
   "peerDependencies": {