@danypops/jittor 0.19.3 → 0.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.19.3",
+  "version": "0.21.2",
   "description": "Just-in-Time Token Optimization Router for Pi -- token and context observability with optimization policies",
   "license": "MIT",
   "type": "module",
@@ -8,10 +8,16 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./usage": "./src/observability/usage.ts",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "keywords": ["llm-router", "token-budget"],
+  "zodiac": {
+    "integrations": [
+      { "kind": "vehicle-surface", "vehicleName": "jittor", "title": "Jittor" }
+    ]
+  },
   "bin": {
     "jittor": "src/cli.ts"
   },

package/src/cli-commands/benchmarks.ts

@@ -7,7 +7,14 @@ import {
 	MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
 	MODEL_RANKING_MAX_SOURCES,
 } from "../constants.ts";
-import { type ModelTaskDomain, type ModelTaskType, TASK_DOMAINS, TASK_TYPES } from "../observability/model-observation.ts";
+import {
+	type ModelTaskDomain,
+	type ModelTaskEffort,
+	type ModelTaskType,
+	TASK_DOMAINS,
+	TASK_EFFORTS,
+	TASK_TYPES,
+} from "../observability/model-observation.ts";
 import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "../optimization/model-selection/benchmark.ts";
 import type { ModelRecommendationInput } from "../optimization/model-selection/ranker.ts";
 import type { ModelCandidate, ModelRankingResult, ScopeAuthority, UtilityWeights } from "../optimization/model-selection/ranking.ts";
@@ -34,6 +41,8 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 	let scopeAuthority: ScopeAuthority = "available-models";
 	let domain: ModelTaskDomain = "general";
 	let type: ModelTaskType = "general";
+	let effort: ModelTaskEffort = "medium";
+	let currentCandidate: ModelCandidate | null = null;
 	let budgetPressure = 0;
 	let sessionId: string | undefined;
 	let sessionSecret: string | undefined;
@@ -63,6 +72,8 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 							"--source",
 							"--domain",
 							"--type",
+							"--effort",
+							"--current",
 							"--scope",
 							"--budget",
 							"--weight-quality",
@@ -98,6 +109,13 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 		} else if (argument === "--type") {
 			if (!TASK_TYPES.includes(raw as ModelTaskType)) return null;
 			type = raw as ModelTaskType;
+		} else if (argument === "--effort") {
+			if (!TASK_EFFORTS.includes(raw as ModelTaskEffort)) return null;
+			effort = raw as ModelTaskEffort;
+		} else if (argument === "--current") {
+			const candidate = parseCandidate(raw);
+			if (!candidate) return null;
+			currentCandidate = candidate;
 		} else if (argument === "--scope") {
 			if (raw !== "exact-session" && raw !== "available-models") return null;
 			scopeAuthority = raw;
@@ -133,6 +151,8 @@ function parseBenchmarkArgs(action: string | undefined, args: string[]): Benchma
 						scopeAuthority,
 						domain,
 						type,
+						effort,
+						currentCandidate,
 						budgetPressure,
 						weights,
 						...(sessionId ? { session_id: sessionId } : {}),

package/src/constants.ts

@@ -40,7 +40,36 @@ export const MODEL_RANKING_DEFAULT_COST_WEIGHT = 2;
 export const MODEL_RANKING_DEFAULT_LATENCY_WEIGHT = 1;
 export const MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT = 1;
 export const MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT = 2;
+/** A low-effort turn tolerates a cheaper model, so its cost weight is amplified; a high-effort turn tolerates spending more for quality, so its cost weight is dampened. Medium is neutral (matches pre-effort-axis behavior exactly). */
+export const MODEL_RANKING_EFFORT_COST_MULTIPLIER_LOW = 1.5;
+export const MODEL_RANKING_EFFORT_COST_MULTIPLIER_MEDIUM = 1;
+export const MODEL_RANKING_EFFORT_COST_MULTIPLIER_HIGH = 0.5;
+/** Cursor-style uplift gate: a recommendation requires the top candidate to clear a real utility margin over the current model, never just "ranked #1". */
+export const MODEL_RANKING_UPLIFT_MIN_UTILITY_DELTA = 0.05;
+export const MODEL_RANKING_UPLIFT_MIN_CONFIDENCE = 0.5;
 export const MODEL_OBSERVATION_FRESH_MS = 7 * 24 * 60 * 60 * 1_000;
+export const EFFORT_DIMENSION_WEIGHT_TOKEN_COUNT = 0.1;
+export const EFFORT_DIMENSION_WEIGHT_CODE_PRESENCE = 0.2;
+export const EFFORT_DIMENSION_WEIGHT_REASONING_MARKERS = 0.2;
+export const EFFORT_DIMENSION_WEIGHT_TECHNICAL_TERMS = 0.15;
+export const EFFORT_DIMENSION_WEIGHT_SIMPLE_INDICATORS = 0.1;
+export const EFFORT_DIMENSION_WEIGHT_MULTI_STEP_PATTERNS = 0.05;
+export const EFFORT_DIMENSION_WEIGHT_QUESTION_COMPLEXITY = 0.05;
+export const EFFORT_DIMENSION_WEIGHT_TOOL_CALL_MIX = 0.15;
+/** Below this many estimated tokens, a short user message is itself simple-indicator evidence. */
+export const EFFORT_TOKEN_SIMPLE_THRESHOLD = 15;
+/** Above this many estimated tokens, a long user message is itself complexity evidence. */
+export const EFFORT_TOKEN_COMPLEX_THRESHOLD = 400;
+export const EFFORT_LOW_MEDIUM_BOUNDARY = 0.2;
+export const EFFORT_MEDIUM_HIGH_BOUNDARY = 0.45;
+/** 2+ reasoning-marker phrases in the user's own message force "high" regardless of the weighted score -- mirrors LiteLLM's complexity_router reasoning override. */
+export const EFFORT_REASONING_MARKER_OVERRIDE_COUNT = 2;
+/** Prior-turn tool-call counts at or below this are simple-indicator evidence (e.g. a single read, or no tools at all). */
+export const EFFORT_TOOL_CALL_LOW_THRESHOLD = 1;
+/** Prior-turn tool-call counts at or above this are complexity evidence (sustained multi-tool engineering work). */
+export const EFFORT_TOOL_CALL_HIGH_THRESHOLD = 4;
+export const EFFORT_CLASSIFICATION_MAX_TEXT_CHARACTERS = 20_000;
+export const EFFORT_CLASSIFICATION_MAX_TOOL_NAMES = 200;
 export const MAINTENANCE_INTERVAL_MS = 15 * 60 * 1_000;
 export const TELEMETRY_POLL_INTERVAL_MS = 60_000;
 export const TELEMETRY_STALE_AFTER_MS = 120_000;

package/src/daemon.ts

@@ -137,6 +137,22 @@ export async function startDaemon(
 		handlePath: paths.handle,
 		logger,
 		buildApp: () => createApp({ service, token }),
+		// Publishes into the shared, cross-package Vehicle Handle Directory
+		// (see @danypops/vehicle-server/paths's resolveSharedVehicleHandlePath)
+		// -- without this, a discovering caller with no prior knowledge of
+		// jittor's own private handlePath (e.g. Zodiac's VehicleSurfaceGateway,
+		// resolving purely by vehicleName) can never find a real, running
+		// jittor daemon. Papyrus's own hand-rolled daemon.ts already does this
+		// explicitly; jittor uses this shared startDaemonKit but was never
+		// passing the option that turns the exact same behavior on.
+		vehicleName: "jittor",
+		tokenPath: paths.token,
+		// startDaemon()'s own `env` param was already used for telemetry/
+		// benchmark/catalog source detection above, but never forwarded to
+		// startDaemonKit itself -- meaning the shared-handle write above would
+		// silently always resolve against real process.env regardless of what
+		// env a caller (e.g. a test, or a future multi-instance setup) supplied.
+		env,
 		maintenanceTasks: [
 			{
 				name: "checkpoint",

package/src/index.ts

@@ -59,6 +59,23 @@ export {
 	CONTEXT_TREE_MAX_NODES,
 	DATABASE_FILENAME,
 	DEFAULT_QUERY_LIMIT,
+	EFFORT_CLASSIFICATION_MAX_TEXT_CHARACTERS,
+	EFFORT_CLASSIFICATION_MAX_TOOL_NAMES,
+	EFFORT_DIMENSION_WEIGHT_CODE_PRESENCE,
+	EFFORT_DIMENSION_WEIGHT_MULTI_STEP_PATTERNS,
+	EFFORT_DIMENSION_WEIGHT_QUESTION_COMPLEXITY,
+	EFFORT_DIMENSION_WEIGHT_REASONING_MARKERS,
+	EFFORT_DIMENSION_WEIGHT_SIMPLE_INDICATORS,
+	EFFORT_DIMENSION_WEIGHT_TECHNICAL_TERMS,
+	EFFORT_DIMENSION_WEIGHT_TOKEN_COUNT,
+	EFFORT_DIMENSION_WEIGHT_TOOL_CALL_MIX,
+	EFFORT_LOW_MEDIUM_BOUNDARY,
+	EFFORT_MEDIUM_HIGH_BOUNDARY,
+	EFFORT_REASONING_MARKER_OVERRIDE_COUNT,
+	EFFORT_TOKEN_COMPLEX_THRESHOLD,
+	EFFORT_TOKEN_SIMPLE_THRESHOLD,
+	EFFORT_TOOL_CALL_HIGH_THRESHOLD,
+	EFFORT_TOOL_CALL_LOW_THRESHOLD,
 	FOOTER_BAR_MAX_WIDTH,
 	FOOTER_BAR_MIN_WIDTH,
 	FOOTER_COMPACTION_BLINK_HALF_PERIOD_MS,
@@ -227,15 +244,18 @@ export {
 	type ModelRunObservation,
 	type ModelTaskClassification,
 	type ModelTaskDomain,
+	type ModelTaskEffort,
 	type ModelTaskType,
 	modelRunMetrics,
 	TASK_DOMAINS,
+	TASK_EFFORTS,
 	TASK_TYPES,
 	validateModelRunObservation,
 } from "./observability/model-observation.ts";
 export type { DistinctScopesFilter, MetricStore, UsageAggregateFilter } from "./observability/store.ts";
 export {
 	applyTaskFocusEvent,
+	declaredEffortFromTaskFocusEvent,
 	type TaskFocusEvent,
 	type TaskFocusStatus,
 	validateTaskFocusEvent,
@@ -302,6 +322,12 @@ export {
 	ModelsDevCatalogSource,
 	translateModelsDevCatalog,
 } from "./optimization/model-selection/catalog.ts";
+export {
+	classifyEffort,
+	type EffortClassification,
+	type EffortClassificationInput,
+	type EffortClassifierOptions,
+} from "./optimization/model-selection/effort.ts";
 export {
 	type ModelCandidate,
 	type ModelRankingInput,

package/src/observability/model-observation.ts

@@ -21,6 +21,15 @@ export const TASK_DOMAINS = ["coding", "design", "math", "general"] as const;
 export type ModelTaskDomain = (typeof TASK_DOMAINS)[number];
 export const TASK_TYPES = ["research", "planning", "general"] as const;
 export type ModelTaskType = (typeof TASK_TYPES)[number];
+/**
+ * A third, independent axis from domain/type: how much reasoning/engineering effort a turn
+ * needs, which drives model-tier selection (a cheap fast model for "low", a frontier model for
+ * "high") the way domain/type drive quality-evidence matching. See
+ * `optimization/model-selection/effort.ts` for the classifier that derives this from structural
+ * signals -- this file only owns the type, not the classification logic.
+ */
+export const TASK_EFFORTS = ["low", "medium", "high"] as const;
+export type ModelTaskEffort = (typeof TASK_EFFORTS)[number];
 export type ExplicitOutcome = "accepted" | "rejected" | "unknown";
 
 export interface ModelRunObservation {

package/src/observability/task-focus.ts

@@ -1,4 +1,5 @@
 import { PAPYRUS_TASK_FOCUS_SCHEMA, TASK_FOCUS_EVENT_MAX_AGE_MS, TASK_FOCUS_ID_MAX_LENGTH } from "../constants.ts";
+import { type ModelTaskEffort, TASK_EFFORTS } from "./model-observation.ts";
 
 export type TaskFocusStatus = "focused" | "paused" | "unpaused" | "cleared";
 
@@ -8,9 +9,16 @@ export interface TaskFocusEvent {
 	sessionId?: string;
 	status: TaskFocusStatus;
 	observedAt: number;
+	/**
+	 * Additive to the papyrus.task-focus/v1 schema: an older Jittor build predates this field, but
+	 * since it's optional here (never required) and this validator only rejects a field it has
+	 * never heard of, a coordinated same-session rollout across both packages is what keeps that
+	 * safe -- see the recorded compatibility decision in the effort-aware Auto mode design Doc.
+	 */
+	effort?: ModelTaskEffort;
 }
 
-const TOP_LEVEL_FIELDS = new Set(["schema", "taskId", "sessionId", "status", "observedAt"]);
+const TOP_LEVEL_FIELDS = new Set(["schema", "taskId", "sessionId", "status", "observedAt", "effort"]);
 const STATUSES = new Set<string>(["focused", "paused", "unpaused", "cleared"]);
 
 function record(value: unknown): Record<string, unknown> {
@@ -48,12 +56,16 @@ export function validateTaskFocusEvent(value: unknown, now = Date.now()): TaskFo
 	if (taskId === null && status !== "cleared") throw new Error(`task-focus event of status "${status}" requires a taskId`);
 	const rawSessionId = input.sessionId;
 	const sessionId = rawSessionId === undefined ? undefined : boundedId(rawSessionId, "sessionId");
+	const rawEffort = input.effort;
+	if (rawEffort !== undefined && !TASK_EFFORTS.includes(rawEffort as ModelTaskEffort))
+		throw new Error("task-focus event effort is invalid");
 	return {
 		schema: PAPYRUS_TASK_FOCUS_SCHEMA,
 		taskId,
 		status: status as TaskFocusStatus,
 		observedAt,
 		...(sessionId === undefined ? {} : { sessionId }),
+		...(rawEffort === undefined ? {} : { effort: rawEffort as ModelTaskEffort }),
 	};
 }
 
@@ -66,3 +78,13 @@ export function validateTaskFocusEvent(value: unknown, now = Date.now()): TaskFo
 export function applyTaskFocusEvent(event: TaskFocusEvent): string | null {
 	return event.status === "focused" || event.status === "unpaused" ? event.taskId : null;
 }
+
+/**
+ * The task-effort analogue of applyTaskFocusEvent: a declared effort is a live "bind-beforehand"
+ * routing prior only while its task is actually focused, using the identical focused/unpaused
+ * vs. paused/cleared semantics -- a task that declared "high" while paused must not keep pinning
+ * routing to "high" once it's no longer the thing being worked on.
+ */
+export function declaredEffortFromTaskFocusEvent(event: TaskFocusEvent): ModelTaskEffort | null {
+	return (event.status === "focused" || event.status === "unpaused") && event.effort !== undefined ? event.effort : null;
+}

package/src/observability/usage.ts

@@ -1,3 +1,15 @@
+/**
+ * Exposed as its own package.json subpath export ("@danypops/jittor/usage")
+ * alongside the main barrel: this module and its own single dependency
+ * (constants.ts) are the only fully browser/Node-tsc-safe slice of jittor's
+ * source tree (pure functions and types, no bun:sqlite, no Bun-only
+ * globals) -- importing the whole barrel instead drags in every other
+ * module's own raw `.ts` import specifiers, which a consumer's tsc rejects
+ * outright (TS5097) unless it enables allowImportingTsExtensions project-
+ * wide. A consumer that only needs buildUsageGraph/buildCostGraph/
+ * resolveUsageWindow (e.g. Zodiac's own React usage meter) should import
+ * this subpath directly, not the main entry.
+ */
 import { MAX_USAGE_BUCKETS, MILLISECONDS_PER_DAY, MILLISECONDS_PER_HOUR } from "../constants.ts";
 
 export const USAGE_PERIODS = [

package/src/optimization/model-selection/effort.ts

@@ -0,0 +1,303 @@
+import {
+	EFFORT_CLASSIFICATION_MAX_TEXT_CHARACTERS,
+	EFFORT_CLASSIFICATION_MAX_TOOL_NAMES,
+	EFFORT_DIMENSION_WEIGHT_CODE_PRESENCE,
+	EFFORT_DIMENSION_WEIGHT_MULTI_STEP_PATTERNS,
+	EFFORT_DIMENSION_WEIGHT_QUESTION_COMPLEXITY,
+	EFFORT_DIMENSION_WEIGHT_REASONING_MARKERS,
+	EFFORT_DIMENSION_WEIGHT_SIMPLE_INDICATORS,
+	EFFORT_DIMENSION_WEIGHT_TECHNICAL_TERMS,
+	EFFORT_DIMENSION_WEIGHT_TOKEN_COUNT,
+	EFFORT_DIMENSION_WEIGHT_TOOL_CALL_MIX,
+	EFFORT_LOW_MEDIUM_BOUNDARY,
+	EFFORT_MEDIUM_HIGH_BOUNDARY,
+	EFFORT_REASONING_MARKER_OVERRIDE_COUNT,
+	EFFORT_TOKEN_COMPLEX_THRESHOLD,
+	EFFORT_TOKEN_SIMPLE_THRESHOLD,
+	EFFORT_TOOL_CALL_HIGH_THRESHOLD,
+	EFFORT_TOOL_CALL_LOW_THRESHOLD,
+} from "../../constants.ts";
+import type { ModelTaskEffort } from "../../observability/model-observation.ts";
+
+/**
+ * Structural/lexical effort classifier -- zero network calls, no persisted prompt content,
+ * deterministic, bounded, sub-millisecond. Modeled on LiteLLM's real merged `complexity_router`
+ * (word-boundary keyword matching, non-greedy ReDoS-safe multi-step regex, a reasoning-marker
+ * override), with two deliberate departures recorded here rather than silently made:
+ *
+ * 1. Only the user's own current-turn message and the prior turn's tool-call mix are scored --
+ *    never Pi's own system prompt. LiteLLM's design assumes a short, custom system prompt; Pi's
+ *    real system prompt is a large, fixed agent-harness prompt full of tool descriptions that
+ *    would permanently saturate the code/technical dimensions if scanned. Scoring only the
+ *    user's own fresh text avoids that false-signal-forever failure mode.
+ * 2. Token count uses a plain char/4 structural estimate by default (matching
+ *    CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN elsewhere in this codebase), not a real tokenizer --
+ *    a real per-provider tokenizer is a replaceable integration per this project's own
+ *    architecture, not something a turn-boundary classifier should hard-depend on. Pass
+ *    `estimateTokens` to plug in a better one without changing this module's contract.
+ */
+
+export interface EffortClassificationInput {
+	/** The current turn's own user message. Never retained beyond this call. */
+	userText: string;
+	/** Tool names actually called during the immediately preceding turn, if any. */
+	priorTurnToolNames?: string[];
+}
+
+export interface EffortClassifierOptions {
+	/** Overrides the default char/4 structural estimate, e.g. with a real per-provider tokenizer. */
+	estimateTokens?: (text: string) => number;
+}
+
+export interface EffortClassification {
+	effort: ModelTaskEffort;
+	/** The raw weighted score before tier-boundary mapping; not itself bounded to 0..1 (an override can exceed it). */
+	score: number;
+	/** Human-readable evidence, one entry per dimension that actually contributed -- never a bare label with no reasoning. Never contains the raw input text. */
+	signals: string[];
+	/** True when the reasoning-marker override forced "high" regardless of the weighted score. */
+	override: boolean;
+}
+
+interface DimensionScore {
+	name: string;
+	score: number;
+	weight: number;
+	evidence: string | null;
+}
+
+// Single-word keywords use word-boundary matching (avoids "api" matching "capital", "class"
+// matching "classical"); multi-word phrases use substring matching. Mirrors LiteLLM's own
+// complexity_router keyword-matching technique, verified against its real merged source.
+const CODE_KEYWORDS = [
+	"function",
+	"class",
+	"async",
+	"await",
+	"import",
+	"export",
+	"api",
+	"endpoint",
+	"database",
+	"query",
+	"schema",
+	"algorithm",
+	"refactor",
+	"debug",
+	"python",
+	"typescript",
+	"javascript",
+	"docker",
+	"kubernetes",
+	"git",
+	"regex",
+];
+const REASONING_KEYWORDS = [
+	"step by step",
+	"think through",
+	"reason through",
+	"analyze this",
+	"break down",
+	"break it down",
+	"explain your reasoning",
+	"show your work",
+	"chain of thought",
+	"think carefully",
+	"weigh the options",
+	"root cause",
+];
+const TECHNICAL_KEYWORDS = [
+	"architecture",
+	"distributed",
+	"scalable",
+	"microservice",
+	"encryption",
+	"authentication",
+	"authorization",
+	"performance",
+	"latency",
+	"throughput",
+	"concurrency",
+	"orchestration",
+	"protocol",
+];
+const SIMPLE_KEYWORDS = [
+	"what is",
+	"what's",
+	"define",
+	"who is",
+	"who was",
+	"when did",
+	"when was",
+	"how many",
+	"hello",
+	"hi",
+	"thanks",
+	"thank you",
+];
+
+const MULTI_STEP_PATTERNS = [/first.*?then/i, /step\s*\d/i, /\d+\.\s/, /[a-z]\)\s/i];
+
+function boundedText(value: string): string {
+	return value.slice(0, EFFORT_CLASSIFICATION_MAX_TEXT_CHARACTERS);
+}
+
+function wordBoundaryOrSubstringMatches(text: string, keyword: string): boolean {
+	if (!keyword.includes(" ")) return new RegExp(`\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(text);
+	return text.includes(keyword);
+}
+
+function countMatches(text: string, keywords: string[]): { count: number; matched: string[] } {
+	const matched = keywords.filter((keyword) => wordBoundaryOrSubstringMatches(text, keyword));
+	return { count: matched.length, matched };
+}
+
+function estimateTokensStructural(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+function scoreTokenCount(tokens: number): DimensionScore {
+	if (tokens < EFFORT_TOKEN_SIMPLE_THRESHOLD)
+		return {
+			name: "tokenCount",
+			score: -1,
+			weight: EFFORT_DIMENSION_WEIGHT_TOKEN_COUNT,
+			evidence: `short user message (${tokens} est. tokens)`,
+		};
+	if (tokens > EFFORT_TOKEN_COMPLEX_THRESHOLD)
+		return {
+			name: "tokenCount",
+			score: 1,
+			weight: EFFORT_DIMENSION_WEIGHT_TOKEN_COUNT,
+			evidence: `long user message (${tokens} est. tokens)`,
+		};
+	return { name: "tokenCount", score: 0, weight: EFFORT_DIMENSION_WEIGHT_TOKEN_COUNT, evidence: null };
+}
+
+function scoreKeywordDimension(
+	text: string,
+	keywords: string[],
+	name: string,
+	weight: number,
+	direction: 1 | -1,
+	label: string,
+): { dimension: DimensionScore; count: number } {
+	const { count, matched } = countMatches(text, keywords);
+	const score = count === 0 ? 0 : count === 1 ? 0.5 * direction : 1 * direction;
+	return {
+		dimension: { name, score, weight, evidence: count === 0 ? null : `${label} (${matched.slice(0, 3).join(", ")})` },
+		count,
+	};
+}
+
+function scoreMultiStep(text: string): DimensionScore {
+	const hit = MULTI_STEP_PATTERNS.some((pattern) => pattern.test(text));
+	return {
+		name: "multiStepPatterns",
+		score: hit ? 1 : 0,
+		weight: EFFORT_DIMENSION_WEIGHT_MULTI_STEP_PATTERNS,
+		evidence: hit ? "multi-step structure detected" : null,
+	};
+}
+
+function scoreQuestionComplexity(text: string): DimensionScore {
+	const count = (text.match(/\?/g) ?? []).length;
+	return {
+		name: "questionComplexity",
+		score: count > 3 ? 1 : 0,
+		weight: EFFORT_DIMENSION_WEIGHT_QUESTION_COMPLEXITY,
+		evidence: count > 3 ? `${count} questions in one message` : null,
+	};
+}
+
+/**
+ * Prior-turn tool-call volume as an effort signal: sustained multi-tool engineering work (several
+ * distinct tool calls last turn) is real evidence of an in-progress complex task; zero or one
+ * tool call is evidence of a light, simple exchange. Bounded, structural, content-free --
+ * tool names only, never their arguments or results.
+ */
+function scoreToolCallMix(toolNames: string[]): DimensionScore {
+	const distinct = new Set(toolNames.slice(0, EFFORT_CLASSIFICATION_MAX_TOOL_NAMES).map((name) => name.toLowerCase()));
+	if (distinct.size <= EFFORT_TOOL_CALL_LOW_THRESHOLD)
+		return {
+			name: "toolCallMix",
+			score: -1,
+			weight: EFFORT_DIMENSION_WEIGHT_TOOL_CALL_MIX,
+			evidence: distinct.size === 0 ? "no prior tool activity" : "single prior tool call",
+		};
+	if (distinct.size >= EFFORT_TOOL_CALL_HIGH_THRESHOLD)
+		return {
+			name: "toolCallMix",
+			score: 1,
+			weight: EFFORT_DIMENSION_WEIGHT_TOOL_CALL_MIX,
+			evidence: `${distinct.size} distinct tools used last turn`,
+		};
+	return { name: "toolCallMix", score: 0, weight: EFFORT_DIMENSION_WEIGHT_TOOL_CALL_MIX, evidence: null };
+}
+
+function tierFor(score: number): ModelTaskEffort {
+	if (score < EFFORT_LOW_MEDIUM_BOUNDARY) return "low";
+	if (score < EFFORT_MEDIUM_HIGH_BOUNDARY) return "medium";
+	return "high";
+}
+
+export function classifyEffort(input: EffortClassificationInput, options: EffortClassifierOptions = {}): EffortClassification {
+	const userText = boundedText(typeof input.userText === "string" ? input.userText : "");
+	const toolNames = Array.isArray(input.priorTurnToolNames) ? input.priorTurnToolNames : [];
+	const estimateTokens = options.estimateTokens ?? estimateTokensStructural;
+
+	const code = scoreKeywordDimension(
+		userText,
+		CODE_KEYWORDS,
+		"codePresence",
+		EFFORT_DIMENSION_WEIGHT_CODE_PRESENCE,
+		1,
+		"code-related terms",
+	);
+	const reasoning = scoreKeywordDimension(
+		userText,
+		REASONING_KEYWORDS,
+		"reasoningMarkers",
+		EFFORT_DIMENSION_WEIGHT_REASONING_MARKERS,
+		1,
+		"reasoning markers",
+	);
+	const technical = scoreKeywordDimension(
+		userText,
+		TECHNICAL_KEYWORDS,
+		"technicalTerms",
+		EFFORT_DIMENSION_WEIGHT_TECHNICAL_TERMS,
+		1,
+		"technical terms",
+	);
+	const simple = scoreKeywordDimension(
+		userText,
+		SIMPLE_KEYWORDS,
+		"simpleIndicators",
+		EFFORT_DIMENSION_WEIGHT_SIMPLE_INDICATORS,
+		-1,
+		"simple-query phrasing",
+	);
+
+	const dimensions: DimensionScore[] = [
+		scoreTokenCount(estimateTokens(userText)),
+		code.dimension,
+		reasoning.dimension,
+		technical.dimension,
+		simple.dimension,
+		scoreMultiStep(userText),
+		scoreQuestionComplexity(userText),
+		scoreToolCallMix(toolNames),
+	];
+
+	const score = dimensions.reduce((sum, dimension) => sum + dimension.score * dimension.weight, 0);
+	const signals = dimensions.filter((dimension) => dimension.evidence !== null).map((dimension) => dimension.evidence as string);
+	const override = reasoning.count >= EFFORT_REASONING_MARKER_OVERRIDE_COUNT;
+
+	return {
+		effort: override ? "high" : tierFor(score),
+		score,
+		signals,
+		override,
+	};
+}

package/src/optimization/model-selection/ranker.ts

@@ -1,5 +1,5 @@
 import { MODEL_AGGREGATE_MAX_ROWS, MODEL_OBSERVATION_FRESH_MS, MODEL_RANKING_MAX_SOURCES } from "../../constants.ts";
-import type { ModelTaskDomain, ModelTaskType } from "../../observability/model-observation.ts";
+import type { ModelTaskDomain, ModelTaskEffort, ModelTaskType } from "../../observability/model-observation.ts";
 import { aggregateModelMetrics } from "../../observability/model-observation.ts";
 import type { MetricStore } from "../../observability/store.ts";
 import { type ModelCandidate, type ModelRankingResult, rankModelCandidates, type ScopeAuthority, type UtilityWeights } from "./ranking.ts";
@@ -10,6 +10,8 @@ export interface ModelRecommendationInput {
 	scopeAuthority: ScopeAuthority;
 	domain: ModelTaskDomain;
 	type: ModelTaskType;
+	effort: ModelTaskEffort;
+	currentCandidate: ModelCandidate | null;
 	budgetPressure: number;
 	weights: UtilityWeights;
 	sourceIds: string[];

package/src/optimization/model-selection/ranking.ts

@@ -1,9 +1,20 @@
-import { BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT, MAX_DYNAMIC_ROUTES, MODEL_AGGREGATE_MAX_ROWS } from "../../constants.ts";
+import {
+	BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT,
+	MAX_DYNAMIC_ROUTES,
+	MODEL_AGGREGATE_MAX_ROWS,
+	MODEL_RANKING_EFFORT_COST_MULTIPLIER_HIGH,
+	MODEL_RANKING_EFFORT_COST_MULTIPLIER_LOW,
+	MODEL_RANKING_EFFORT_COST_MULTIPLIER_MEDIUM,
+	MODEL_RANKING_UPLIFT_MIN_CONFIDENCE,
+	MODEL_RANKING_UPLIFT_MIN_UTILITY_DELTA,
+} from "../../constants.ts";
 import {
 	type ModelMetricAggregate,
 	type ModelTaskDomain,
+	type ModelTaskEffort,
 	type ModelTaskType,
 	TASK_DOMAINS,
+	TASK_EFFORTS,
 	TASK_TYPES,
 } from "../../observability/model-observation.ts";
 import { type BenchmarkObservation, normalizeModelIdentity } from "./benchmark.ts";
@@ -30,6 +41,10 @@ export interface ModelRankingInput {
 	scopeAuthority: ScopeAuthority;
 	domain: ModelTaskDomain;
 	type: ModelTaskType;
+	/** Predicts how much reasoning/engineering effort this turn needs; shifts the effective cost weight (see MODEL_RANKING_EFFORT_COST_MULTIPLIER_*) the same way budgetPressure already does. */
+	effort: ModelTaskEffort;
+	/** The model actually in use right now -- the uplift gate's baseline. A recommendation requires a real, evidence-backed improvement over this, never just "ranked #1". Null when there is no active model to compare against (pure ranking still proceeds; there is simply nothing to gate an uplift over, so recommendation stays null). */
+	currentCandidate: ModelCandidate | null;
 	budgetPressure: number;
 	weights: UtilityWeights;
 	externalEvidence: BenchmarkObservation[];
@@ -37,6 +52,12 @@ export interface ModelRankingInput {
 	now: number;
 }
 
+export interface ModelRankingRecommendation {
+	candidate: ModelCandidate;
+	utilityDelta: number;
+	confidence: number;
+}
+
 export interface UtilityComponent {
 	name: UtilityComponentName;
 	score: number | null;
@@ -71,6 +92,9 @@ export interface ModelRankingResult {
 	type: ModelTaskType;
 	completeness: "complete" | "partial" | "insufficient-evidence";
 	ranked: RankedModel[];
+	/** A candidate that cleared the uplift gate (real utility margin + confidence over currentCandidate), regardless of scope authority -- the evidence question, independent of whether automation is currently allowed. Null when the current model is already the best choice, or no candidate clears the gate. */
+	recommendation: ModelRankingRecommendation | null;
+	/** recommendation's candidate, but only once scopeAuthority is "exact-session" -- the governance question layered on top of the evidence question. */
 	automaticSelection: ModelCandidate | null;
 }
 
@@ -226,11 +250,19 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 		throw new Error("scope authority is invalid");
 	if (!TASK_DOMAINS.includes(value.domain)) throw new Error("task domain is invalid");
 	if (!TASK_TYPES.includes(value.type)) throw new Error("task type is invalid");
+	if (!TASK_EFFORTS.includes(value.effort)) throw new Error("task effort is invalid");
+	const currentIdentity = value.currentCandidate === null ? null : candidateIdentity(value.currentCandidate);
 	if (!Number.isSafeInteger(value.now) || value.now <= 0) throw new Error("ranking time is invalid");
 	const budgetPressure = finiteBound(value.budgetPressure, "budget pressure", 0, 2);
 	const weights = Object.fromEntries(
 		COMPONENTS.map((name) => [name, finiteBound(value.weights[name], `${name} weight`, 0, 10)]),
 	) as unknown as UtilityWeights;
+	const effortCostMultiplier =
+		value.effort === "low"
+			? MODEL_RANKING_EFFORT_COST_MULTIPLIER_LOW
+			: value.effort === "high"
+				? MODEL_RANKING_EFFORT_COST_MULTIPLIER_HIGH
+				: MODEL_RANKING_EFFORT_COST_MULTIPLIER_MEDIUM;
 	const seen = new Set<string>();
 	const candidates = value.candidates
 		.map((candidate) => ({ ...candidate }))
@@ -241,7 +273,7 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 			return true;
 		});
 	const raw = candidates.map((candidate) => rawComponents(candidate, value));
-	const effectiveWeights: UtilityWeights = { ...weights, cost: weights.cost * (1 + budgetPressure) };
+	const effectiveWeights: UtilityWeights = { ...weights, cost: weights.cost * (1 + budgetPressure) * effortCostMultiplier };
 	const ranked = candidates
 		.map((candidate, index): RankedModel => {
 			const source = raw[index]!;
@@ -277,8 +309,8 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 				components,
 				provenance,
 				trace: [
-					`domain ${value.domain}, type ${value.type}`,
-					`budget pressure ${budgetPressure.toFixed(3)} makes cost weight ${effectiveWeights.cost.toFixed(3)}`,
+					`domain ${value.domain}, type ${value.type}, effort ${value.effort}`,
+					`budget pressure ${budgetPressure.toFixed(3)} and effort ${value.effort} make cost weight ${effectiveWeights.cost.toFixed(3)}`,
 					`${known.length}/${components.length} utility components have evidence`,
 					`scope authority ${value.scopeAuthority}`,
 				],
@@ -292,6 +324,20 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 	const possibleComponents = ranked.length * COMPONENTS.length;
 	const completeness = knownComponents === 0 ? "insufficient-evidence" : knownComponents === possibleComponents ? "complete" : "partial";
 	const exact = value.scopeAuthority === "exact-session";
+	const top = ranked[0];
+	const current = currentIdentity === null ? undefined : ranked.find((item) => item.identity === currentIdentity);
+	// Uplift gate (Cursor-style): a recommendation requires a real, evidence-backed improvement
+	// over the current model -- never just "ranked #1". Without a located current baseline (it
+	// wasn't among the input candidates) there is nothing to uplift over, so no recommendation.
+	const recommendation: ModelRankingRecommendation | null =
+		top && current && top.identity !== current.identity && top.utility !== null && current.utility !== null
+			? (() => {
+					const utilityDelta = top.utility! - current.utility!;
+					return utilityDelta >= MODEL_RANKING_UPLIFT_MIN_UTILITY_DELTA && top.confidence >= MODEL_RANKING_UPLIFT_MIN_CONFIDENCE
+						? { candidate: top.candidate, utilityDelta, confidence: top.confidence }
+						: null;
+				})()
+			: null;
 	return {
 		scopeAuthority: value.scopeAuthority,
 		scopeWarning: exact ? null : "Pi available models are not the exact session scope; automatic selection is disabled",
@@ -299,6 +345,7 @@ export function rankModelCandidates(value: ModelRankingInput): ModelRankingResul
 		type: value.type,
 		completeness,
 		ranked,
-		automaticSelection: exact && ranked[0]?.utility !== null ? ranked[0]!.candidate : null,
+		recommendation,
+		automaticSelection: exact && recommendation ? recommendation.candidate : null,
 	};
 }