@selesai/code 0.13.33 → 0.13.34

package/dist/extensions/capability-gateway/integration.test.ts

@@ -208,6 +208,7 @@ describe("capability gateway integration", () => {
 		const prompt = h.session.systemPrompt;
 		expect(prompt).toContain("capability_catalog");
 		expect(prompt).toContain("Never invent optional tool names");
+		expect(prompt).toContain("Never tell the user a tool is unavailable");
 		// The full skill list is gone from the default prompt: the research
 		// skill name and body are absent, only the compact instruction remains.
 		expect(prompt).not.toContain("Research instructions body.");
@@ -604,6 +605,40 @@ describe("capability gateway Jev routing", () => {
 		);
 	});
 
+	it("leaves the job route out of the skill index while Jev has no credential", async () => {
+		const h = await createGatewaySession({ enabled: true, extensions: [GATEWAY_DIR, GREP_APP_DIR] });
+		harnesses.push(h);
+
+		await route(h, NO_SIGNAL_PROMPT);
+
+		expect(h.session.systemPrompt).not.toContain("capability_discover with `job`");
+		expect(h.session.systemPrompt).toContain("then call capability_discover with the exact `name`");
+	});
+
+	it("offers the job route in the skill index while Jev is reachable", async () => {
+		allowNetwork();
+		stubJev("grep_app_search");
+		const h = await createGatewaySession({ enabled: true, extensions: [GATEWAY_DIR, GREP_APP_DIR], jev: jevSettings() });
+		harnesses.push(h);
+
+		await route(h, NO_SIGNAL_PROMPT);
+
+		expect(h.session.systemPrompt).toContain("capability_discover with `job`");
+	});
+
+	it("reports an already-active tool instead of activating it again", async () => {
+		const h = await createGatewaySession({ enabled: true, extensions: [GATEWAY_DIR, GREP_APP_DIR] });
+		harnesses.push(h);
+		await route(h, "search github code with grep_app_search");
+		expect(h.session.getActiveToolNames()).toContain("grep_app_search");
+
+		const discover = h.session.getToolDefinition("capability_discover");
+		const result = await discover!.execute("call-again", { name: "grep_app_search" }, undefined, undefined, {} as never);
+		expect(String(result.content[0]!.text)).toContain("already active");
+		expect(String(result.content[0]!.text)).not.toContain("Activated");
+		expect(result.details).toMatchObject({ alreadyActive: true });
+	});
+
 	it("does not attempt Jev when explicitly disabled", async () => {
 		const disabled = stubJev("grep_app_search");
 		const h = await createGatewaySession({

package/dist/extensions/capability-gateway/routing.test.ts

@@ -8,14 +8,21 @@ import type { CatalogEntry } from "./catalog.ts";
 import {
 	candidateCriteria,
 	DEFAULT_GATEWAY_JEV_CONFIG,
+	DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS,
 	DEFAULT_GATEWAY_JEV_TIMEOUT_MS,
+	GATEWAY_JEV_DISCOVER_MAX_TIMEOUT_MS,
 	GATEWAY_JEV_MAX_TIMEOUT_MS,
 	GATEWAY_JEV_PROMPT_CHARS,
 	gatewayJevConnection,
 	hintedToolCandidates,
+	fitCatalogCandidates,
 	JEV_CAPABILITY_QUESTION,
+	JEV_SKILL_QUESTION,
+	JEV_TOOL_QUESTION,
+	MAX_CANDIDATE_CRITERION_CHARS,
 	MAX_GATEWAY_JEV_CANDIDATES,
 	readGatewayJevConfig,
+	routeJobToJev,
 	routeToJevTool,
 	type GatewayJevConfig,
 	type JevAsk,
@@ -122,8 +129,9 @@ describe("gateway Jev configuration", () => {
 			provider: "tokenin",
 			model: "jev-1.13",
 			timeoutMs: DEFAULT_GATEWAY_JEV_TIMEOUT_MS,
+			discoverTimeoutMs: DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS,
 			minConfidence: 0.6,
-			payloadBytes: 8_192,
+			payloadBytes: 32 * 1024,
 		});
 		expect(DEFAULT_GATEWAY_JEV_TIMEOUT_MS).toBeLessThan(8_000);
 
@@ -153,6 +161,7 @@ describe("gateway Jev configuration", () => {
 			model: "jev-1.13",
 			baseUrl: "https://jev.example/v1",
 			timeoutMs: 500,
+			discoverTimeoutMs: DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS,
 			minConfidence: 0.8,
 			payloadBytes: 4096,
 		});
@@ -209,6 +218,17 @@ describe("gateway Jev configuration", () => {
 		});
 		expect(gatewayJevConnection({ ...config, timeoutMs: 60_000 }).timeoutMs).toBe(GATEWAY_JEV_MAX_TIMEOUT_MS);
 	});
+
+	it("gives the agent's on-demand route its own longer deadline, not the pre-turn cap", () => {
+		expect(gatewayJevConnection(config, true).timeoutMs).toBe(DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS);
+		expect(DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS).toBeGreaterThan(GATEWAY_JEV_MAX_TIMEOUT_MS);
+		expect(gatewayJevConnection({ ...config, discoverTimeoutMs: 8_000 }, true).timeoutMs).toBe(8_000);
+		expect(gatewayJevConnection({ ...config, discoverTimeoutMs: 60_000 }, true).timeoutMs).toBe(
+			GATEWAY_JEV_DISCOVER_MAX_TIMEOUT_MS,
+		);
+		// The pre-turn tie-break is untouched by the on-demand setting.
+		expect(gatewayJevConnection({ ...config, discoverTimeoutMs: 8_000 }).timeoutMs).toBe(DEFAULT_GATEWAY_JEV_TIMEOUT_MS);
+	});
 });
 
 describe("gateway Jev candidates", () => {
@@ -419,3 +439,136 @@ describe("routeToJevTool through the shared Jev client", () => {
 		expect(Object.keys(body.questions[JEV_CAPABILITY_QUESTION].criteria)).toEqual(["none", "grep_app_search"]);
 	});
 });
+
+describe("catalog fitting for the on-demand route", () => {
+	const entry = (name: string, summary = "Do a thing"): CatalogEntry => ({
+		name,
+		kind: "tool",
+		summary,
+		aliases: [],
+		eligible: true,
+	});
+
+	it("offers every eligible entry that fits and reports the ones it dropped", () => {
+		const entries = Array.from({ length: 20 }, (_, index) => entry(`tool_${index}`));
+		const { candidates, dropped } = fitCatalogCandidates(entries, 400);
+		expect(candidates.length).toBeGreaterThan(0);
+		expect(candidates.length + dropped).toBe(20);
+		expect(candidates.map((c) => c.name)).toEqual(entries.slice(0, candidates.length).map((c) => c.name));
+	});
+
+	it("never offers an ineligible entry", () => {
+		const { candidates, dropped } = fitCatalogCandidates([{ ...entry("hidden"), eligible: false }, entry("shown")], 10_000);
+		expect(candidates.map((c) => c.name)).toEqual(["shown"]);
+		expect(dropped).toBe(0);
+	});
+
+	it("clips a long criterion to its character ceiling", () => {
+		const { candidates } = fitCatalogCandidates([entry("verbose", "x".repeat(1_000))], 10_000);
+		const criterion = candidateCriteria(candidates)["verbose"]!;
+		expect(criterion).toHaveLength(MAX_CANDIDATE_CRITERION_CHARS + 1);
+		expect(criterion.endsWith("…")).toBe(true);
+	});
+});
+
+describe("routeJobToJev through an injected decision call", () => {
+	const ask = (decision: JevDecision): JevAsk => vi.fn(async () => decision) as unknown as JevAsk;
+	const sentPayload = (injected: JevAsk) => (injected as unknown as ReturnType<typeof vi.fn>).mock.calls[0]![2] as any;
+
+	it("asks the tool and skill questions separately in one request, without any schema", async () => {
+		const injected = ask({
+			choices: {
+				[JEV_TOOL_QUESTION]: { choice: "grep_app_search", confidence: 0.9 },
+				[JEV_SKILL_QUESTION]: { choice: "research", confidence: 0.8 },
+			},
+			rejected: {},
+			elapsedMs: 5,
+		});
+		const route = await routeJobToJev(
+			[searchTool, fetchTool, otherTool, fourthTool],
+			[skillEntry],
+			"research how others use this API",
+			ctxWith(),
+			config,
+			injected,
+		);
+		expect(route).toEqual({
+			tool: { pick: { selected: true, name: "grep_app_search", confidence: 0.9 }, offered: 4, dropped: 0 },
+			skill: { pick: { selected: true, name: "research", confidence: 0.8 }, offered: 1, dropped: 0 },
+			elapsedMs: 5,
+		});
+
+		const request = sentPayload(injected);
+		expect(Object.keys(request.payload.questions[JEV_TOOL_QUESTION].criteria)).toEqual([
+			"none",
+			"grep_app_search",
+			"grep_app_fetch",
+			"other_tool",
+			"fourth_tool",
+		]);
+		expect(Object.keys(request.payload.questions[JEV_SKILL_QUESTION].criteria)).toEqual(["none", "research"]);
+		expect(request.allowed[JEV_SKILL_QUESTION]).not.toContain("grep_app_search");
+		expect(request.payload.state.conversation).toEqual([{ role: "user", text: "research how others use this API" }]);
+		expect(JSON.stringify(request.payload)).not.toContain("parameters");
+		expect((injected as unknown as ReturnType<typeof vi.fn>).mock.calls[0]![1].timeoutMs).toBe(
+			DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS,
+		);
+	});
+
+	it("answers each kind on its own: `none` for one does not hide the other", async () => {
+		const injected = ask({
+			choices: {
+				[JEV_TOOL_QUESTION]: { choice: "none", confidence: 0.95 },
+				[JEV_SKILL_QUESTION]: { choice: "research", confidence: 0.7 },
+			},
+			rejected: {},
+			elapsedMs: 3,
+		});
+		const route = await routeJobToJev([searchTool], [skillEntry], "write up findings", ctxWith(), config, injected);
+		expect(route.tool.pick).toEqual({ selected: false, reason: "none" });
+		expect(route.skill.pick).toEqual({ selected: true, name: "research", confidence: 0.7 });
+	});
+
+	it("fits tools first, so a long skill tail can only drop skills", async () => {
+		const skills = Array.from({ length: 200 }, (_, index) => ({
+			...skillEntry,
+			name: `skill_${index}`,
+			summary: "A long procedure description ".repeat(5),
+		}));
+		const injected = ask({ choices: {}, rejected: {}, failure: "missing", elapsedMs: 1 });
+		const route = await routeJobToJev([searchTool, fetchTool], skills, "anything", ctxWith(), { ...config, payloadBytes: 8_192 }, injected);
+		expect(route.tool).toMatchObject({ offered: 2, dropped: 0 });
+		expect(route.skill.offered).toBeGreaterThan(0);
+		expect(route.skill.dropped).toBeGreaterThan(0);
+		expect(route.skill.offered + route.skill.dropped).toBe(200);
+	});
+
+	it("leaves an empty kind out of the request, and skips Jev when both are empty", async () => {
+		const injected = ask({ choices: { [JEV_TOOL_QUESTION]: { choice: "none", confidence: 0.9 } }, rejected: {}, elapsedMs: 2 });
+		const route = await routeJobToJev([searchTool], [], "search code", ctxWith(), config, injected);
+		expect(Object.keys(sentPayload(injected).payload.questions)).toEqual([JEV_TOOL_QUESTION]);
+		expect(route.skill.pick).toEqual({ selected: false, reason: "no-candidates" });
+
+		const unused = ask({ choices: {}, rejected: {}, elapsedMs: 1 });
+		expect(await routeJobToJev([], [], "anything", ctxWith(), config, unused)).toMatchObject({ elapsedMs: 0 });
+		expect(unused).not.toHaveBeenCalled();
+	});
+
+	it("reports an unavailable Jev on every asked question, and unquantified answers as abstentions", async () => {
+		const timeout = ask({
+			choices: {},
+			rejected: { [JEV_TOOL_QUESTION]: "timeout", [JEV_SKILL_QUESTION]: "timeout" },
+			failure: "timeout",
+			elapsedMs: 5_000,
+		});
+		const route = await routeJobToJev([searchTool], [skillEntry], "x", ctxWith(), config, timeout);
+		expect(route.tool.pick).toEqual({ selected: false, reason: "timeout" });
+		expect(route.skill.pick).toEqual({ selected: false, reason: "timeout" });
+
+		const unquantified = ask({ choices: { [JEV_TOOL_QUESTION]: { choice: "grep_app_search" } }, rejected: {}, elapsedMs: 3 });
+		expect((await routeJobToJev([searchTool], [], "find code", ctxWith(), config, unquantified)).tool.pick).toEqual({
+			selected: false,
+			reason: "unquantified",
+		});
+	});
+});

package/dist/extensions/capability-gateway/routing.ts

@@ -1,23 +1,31 @@
 /**
- * Capability-gateway Jev-assisted tool tie-breaking.
+ * Capability-gateway Jev-assisted tool routing.
  *
- * The deterministic catalog router stays the first and only Jev trigger: when it returns an
- * ambiguous lexical hint among optional tools, the gateway offers just those hinted tools to Jev
- * as one bounded choice question. Jev may answer `none` or one hinted canonical tool name; the
- * host revalidates eligibility against the live catalog before activating anything for this run.
+ * Two callers, one decision body:
  *
- * Jev never sees a tool schema, prior conversation, or the full eligible catalog: the request
- * carries the bounded current prompt and two or three hinted discovery lines. It is never consulted for a unique deterministic activation, a skill-only match, or a
- * prompt with no lexical tool signal; every failure, timeout, low-confidence answer, or `none` is
- * an abstention that leaves the deterministic behavior in place. The transport and validation half
- * lives in the shared `../jev/decisions.ts` client.
+ * - The **pre-turn tie-break** (host-driven): when the deterministic router returns an ambiguous
+ *   lexical hint among optional tools, the gateway offers just those hinted tools to Jev as one
+ *   bounded choice question. Jev may answer `none` or one hinted canonical tool name; the host
+ *   revalidates eligibility against the live catalog before activating anything for this run.
+ * - The **on-demand route** (agent-driven): the agent calls `capability_discover` with a job
+ *   description instead of a name. Tools and skills are different decisions — a tool is code the
+ *   agent may call many times, a skill is a procedure it reads once — so one request asks two
+ *   choice questions, each over its own catalog slice with its own `none`. Tools are fitted into
+ *   the budget first, so skills can never crowd a tool out.
+ *
+ * Either way Jev never sees a tool schema, prior conversation, or system prompt: the request carries
+ * a bounded material text and compact discovery lines (name, kind, category, one-line purpose). It
+ * is never consulted for a unique deterministic activation, a skill-only match, or a prompt with no
+ * lexical tool signal; every failure, timeout, low-confidence answer, or `none` is an abstention.
+ * The transport and validation half lives in the shared `../jev/decisions.ts` client.
  *
  * Configuration (enabled by default, but requires Token-In credentials). The gateway reads its
  * own settings area — it does not inherit `jevAdvisory` route policy; only the Jev provider/model
  * identity is shared so every Jev consumer defaults to the same deployment:
  *
  *   "capabilityGateway": {
- *     "routing": { "jev": { "enabled": true, "timeoutMs": 1000, "minConfidence": 0.6 } }
+ *     "routing": { "jev": { "enabled": true, "timeoutMs": 1000, "discoverTimeoutMs": 5000,
+ *                          "minConfidence": 0.6, "payloadBytes": 32768 } }
  *   }
  */
 import { readFileSync } from "node:fs";
@@ -55,6 +63,13 @@ export const GATEWAY_JEV_PROMPT_CHARS = 2_000;
 export const DEFAULT_GATEWAY_JEV_TIMEOUT_MS = 1_000;
 export const GATEWAY_JEV_MAX_TIMEOUT_MS = 2_000;
 
+/**
+ * The agent's on-demand route asks over the whole catalog and the agent chose to wait for it, so it
+ * gets its own, longer deadline — capped like the `ask_jev` route rather than like a pre-turn hop.
+ */
+export const DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS = 5_000;
+export const GATEWAY_JEV_DISCOVER_MAX_TIMEOUT_MS = 15_000;
+
 /** One gateway route's Jev settings: the shared Jev endpoint plus this route's timing. */
 export interface GatewayJevConfig {
 	enabled: boolean;
@@ -62,6 +77,8 @@ export interface GatewayJevConfig {
 	model: string;
 	baseUrl?: string;
 	timeoutMs: number;
+	/** Deadline for the agent's `capability_discover({ job })` decision. */
+	discoverTimeoutMs: number;
 	minConfidence: number;
 	/** Hard cap on the serialized decision request; oversized requests abstain. */
 	payloadBytes: number;
@@ -73,8 +90,10 @@ export const DEFAULT_GATEWAY_JEV_CONFIG: GatewayJevConfig = {
 	provider: DEFAULT_JEV_ADVISORY_CONFIG.provider,
 	model: DEFAULT_JEV_ADVISORY_CONFIG.model,
 	timeoutMs: DEFAULT_GATEWAY_JEV_TIMEOUT_MS,
+	discoverTimeoutMs: DEFAULT_GATEWAY_JEV_DISCOVER_TIMEOUT_MS,
 	minConfidence: 0.6,
-	payloadBytes: 8_192,
+	// Room for a whole catalog on the on-demand route; the tie-break sends a few hundred bytes.
+	payloadBytes: 32 * 1024,
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -110,18 +129,21 @@ export function readGatewayJevConfig(settingsPath: string = getSettingsPath()):
 		model: stringOr(raw.model, DEFAULT_GATEWAY_JEV_CONFIG.model),
 		baseUrl: typeof baseUrl === "string" && baseUrl.trim() !== "" ? baseUrl : undefined,
 		timeoutMs: numberOr(raw.timeoutMs, DEFAULT_GATEWAY_JEV_CONFIG.timeoutMs),
+		discoverTimeoutMs: numberOr(raw.discoverTimeoutMs, DEFAULT_GATEWAY_JEV_CONFIG.discoverTimeoutMs),
 		minConfidence: numberOr(raw.minConfidence, DEFAULT_GATEWAY_JEV_CONFIG.minConfidence),
 		payloadBytes: numberOr(raw.payloadBytes, DEFAULT_GATEWAY_JEV_CONFIG.payloadBytes),
 	};
 }
 
-/** The transport settings this route uses, with the pre-turn timeout hard-capped. */
-export function gatewayJevConnection(config: GatewayJevConfig): JevConnection {
+/** The transport settings one gateway route uses, each with its own hard-capped deadline. */
+export function gatewayJevConnection(config: GatewayJevConfig, onDemand = false): JevConnection {
 	return {
 		provider: config.provider,
 		model: config.model,
 		baseUrl: config.baseUrl,
-		timeoutMs: Math.min(config.timeoutMs, GATEWAY_JEV_MAX_TIMEOUT_MS),
+		timeoutMs: onDemand
+			? Math.min(config.discoverTimeoutMs, GATEWAY_JEV_DISCOVER_MAX_TIMEOUT_MS)
+			: Math.min(config.timeoutMs, GATEWAY_JEV_MAX_TIMEOUT_MS),
 		minConfidence: config.minConfidence,
 	};
 }
@@ -135,19 +157,56 @@ export function hintedToolCandidates(hints: readonly CatalogEntry[] = []): Catal
 	return hints.filter((entry) => entry.kind === "tool" && entry.eligible).slice(0, MAX_GATEWAY_JEV_CANDIDATES);
 }
 
+/** Longest candidate summary sent as a criterion; a whole catalog has to fit one request. */
+export const MAX_CANDIDATE_CRITERION_CHARS = 160;
+
+/** JSON scaffolding one candidate costs in the decision request: key, quoting, separator. */
+const CANDIDATE_ENVELOPE_BYTES = 32;
+
+function clipText(text: string, maxChars: number): string {
+	return text.length > maxChars ? `${text.slice(0, maxChars)}…` : text;
+}
+
 /** Allowlisted choices: `none` plus one compact discovery-metadata line per candidate. */
 export function candidateCriteria(candidates: CatalogEntry[]): Record<string, string> {
 	const criteria: Record<string, string> = {
-		[NO_TOOL]: "No optional tool is needed for the latest request.",
+		[NO_TOOL]: "No optional capability is needed for the job.",
 	};
 	for (const candidate of candidates) {
 		const category = candidate.category ? ` Category: ${candidate.category}.` : "";
 		const aliases = candidate.aliases.length > 0 ? ` Aliases: ${candidate.aliases.join(", ")}.` : "";
-		criteria[candidate.name] = `${candidate.summary}${category}${aliases}`;
+		criteria[candidate.name] = clipText(`${candidate.summary}${category}${aliases}`, MAX_CANDIDATE_CRITERION_CHARS);
 	}
 	return criteria;
 }
 
+/**
+ * The offered entries that fit one bounded decision request, in catalog order.
+ *
+ * An entry that does not fit is skipped rather than truncated: a candidate offered without a usable
+ * criterion would be judged on its name alone. `dropped` is reported so the caller can tell the
+ * agent the search was not exhaustive.
+ *
+ * ponytail: greedy order-independent fit; rank by relevance first if a real install drops enough
+ * candidates to misroute.
+ */
+export function fitCatalogCandidates(
+	entries: readonly CatalogEntry[],
+	budgetBytes: number,
+): { candidates: CatalogEntry[]; dropped: number } {
+	const offered = entries.filter((entry) => entry.eligible);
+	const candidates: CatalogEntry[] = [];
+	let used = 0;
+	for (const entry of offered) {
+		const criterion = candidateCriteria([entry])[entry.name] ?? "";
+		const cost = CANDIDATE_ENVELOPE_BYTES + Buffer.byteLength(`${entry.name}${criterion}`, "utf-8");
+		if (used + cost > budgetBytes) continue;
+		candidates.push(entry);
+		used += cost;
+	}
+	return { candidates, dropped: offered.length - candidates.length };
+}
+
 /** Why no tool was routed: a clean `none`, an empty candidate set, or an absent Jev decision. */
 export type JevToolAbstainReason = "none" | "no-candidates" | "unquantified" | JevClientAbstainReason;
 
@@ -166,30 +225,66 @@ export const JEV_UNAVAILABLE_REASONS: ReadonlySet<JevToolAbstainReason> = new Se
 /** The decision call, injectable so catalog routing is testable without a live transport. */
 export type JevAsk = typeof askJev;
 
+/** One route's question wording; the criteria and allowlist are built from the candidates. */
+export interface CapabilityQuestion {
+	question: string;
+	focus: string;
+}
+
+/** The host's pre-turn tie-break: only the hinted tools, and only a weak lexical signal. */
+export const TIE_BREAK_QUESTION: CapabilityQuestion = {
+	question:
+		"Which single hinted optional tool should be activated for the latest request in `conversation`, " +
+		"or `none` when none of them is clearly needed?",
+	focus: "Choose `none` unless exactly one listed tool is clearly needed; the prompt only weakly suggests these tools.",
+};
+
+/** Question keys of the on-demand route: one decision per capability kind. */
+export const JEV_TOOL_QUESTION = "tool";
+export const JEV_SKILL_QUESTION = "skill";
+
+/** On demand, tools: callable code the agent may use many times during the job. */
+export const JOB_TOOL_QUESTION: CapabilityQuestion = {
+	question:
+		"Which single listed tool should the agent activate for the job in `conversation`, or `none` when the " +
+		"built-in tools (read, bash, edit, write, grep, find, ls) or a direct answer are enough?",
+	focus:
+		"A tool is callable code the agent may call many times during the job. Most jobs need no optional tool: " +
+		"choose one name only when it clearly fits the job.",
+};
+
+/** On demand, skills: a written procedure the agent reads once before doing the job. */
+export const JOB_SKILL_QUESTION: CapabilityQuestion = {
+	question:
+		"Which single listed skill's instructions should the agent load for the job in `conversation`, or `none` " +
+		"when no written procedure is needed?",
+	focus:
+		"A skill is a written procedure the agent reads once before doing the job. Choose one name only when the " +
+		"job clearly matches what that skill describes.",
+};
+
 /**
- * Offer the hinted tools to Jev and return the tool it selected for this run. Anything outside one
+ * Offer one candidate set to Jev and return the capability it selected. Anything outside one
  * confident, canonical, allowlisted choice is an abstention.
  */
-export async function routeToJevTool(
-	hints: readonly CatalogEntry[],
-	prompt: string,
+async function offerCandidates(
+	candidates: readonly CatalogEntry[],
+	material: string,
+	prompt: CapabilityQuestion,
 	ctx: Pick<ExtensionContext, "modelRegistry">,
 	config: GatewayJevConfig,
-	ask: JevAsk = askJev,
+	ask: JevAsk,
 ): Promise<JevToolRoute> {
-	const candidates = hintedToolCandidates(hints);
 	if (candidates.length === 0) return { selected: false, reason: "no-candidates", candidates: 0, elapsedMs: 0 };
 
 	const question: JevQuestion = {
-		question:
-			"Which single hinted optional tool should be activated for the latest request in `conversation`, " +
-			"or `none` when none of them is clearly needed?",
-		focus: "Choose `none` unless exactly one listed tool is clearly needed; the prompt only weakly suggests these tools.",
-		criteria: candidateCriteria(candidates),
+		question: prompt.question,
+		focus: prompt.focus,
+		criteria: candidateCriteria([...candidates]),
 	};
-	// Only the current prompt, bounded: no prior conversation, no tool schema, no history.
+	// Only the current material, bounded: no prior conversation, no tool schema, no history.
 	const payload = buildJevPayload(
-		buildConversation(prompt, [], { contextTurns: 1, contextChars: GATEWAY_JEV_PROMPT_CHARS }),
+		buildConversation(material, [], { contextTurns: 1, contextChars: GATEWAY_JEV_PROMPT_CHARS }),
 		{ [JEV_CAPABILITY_QUESTION]: question },
 	);
 	const decision = await ask(ctx, gatewayJevConnection(config), {
@@ -198,24 +293,111 @@ export async function routeToJevTool(
 		allowed: { [JEV_CAPABILITY_QUESTION]: [NO_TOOL, ...candidates.map((candidate) => candidate.name)] },
 	});
 
-	const abstained = (reason: JevToolAbstainReason): JevToolRoute => ({
-		selected: false,
-		reason,
-		candidates: candidates.length,
-		elapsedMs: decision.elapsedMs,
+	const picked = pickFrom(decision, JEV_CAPABILITY_QUESTION);
+	return picked.selected
+		? { selected: true, tool: picked.name, confidence: picked.confidence, candidates: candidates.length, elapsedMs: decision.elapsedMs }
+		: { selected: false, reason: picked.reason, candidates: candidates.length, elapsedMs: decision.elapsedMs };
+}
+
+/** One question's outcome: a confident allowlisted name, or why there is none. */
+export type JevPick =
+	| { selected: true; name: string; confidence: number }
+	| { selected: false; reason: JevToolAbstainReason };
+
+/** Read one question out of a decision. Anything outside one confident, canonical, non-`none` choice abstains. */
+function pickFrom(decision: JevDecision, question: string): JevPick {
+	const answer = decision.choices[question];
+	if (!answer) return { selected: false, reason: decision.rejected[question] ?? decision.failure ?? "missing" };
+	if (answer.choice === NO_TOOL) return { selected: false, reason: "none" };
+	// A choice without a numeric confidence is not a confident enough answer to act on.
+	if (answer.confidence === undefined) return { selected: false, reason: "unquantified" };
+	return { selected: true, name: answer.choice, confidence: answer.confidence };
+}
+
+/**
+ * Offer the hinted tools to Jev and return the tool it selected for this run.
+ */
+export async function routeToJevTool(
+	hints: readonly CatalogEntry[],
+	prompt: string,
+	ctx: Pick<ExtensionContext, "modelRegistry">,
+	config: GatewayJevConfig,
+	ask: JevAsk = askJev,
+): Promise<JevToolRoute> {
+	return offerCandidates(hintedToolCandidates(hints), prompt, TIE_BREAK_QUESTION, ctx, config, ask);
+}
+
+/** Room kept per question for its wording and scaffolding around the candidate criteria. */
+const QUESTION_SCAFFOLDING_BYTES = 512;
+
+/** One capability kind's side of an on-demand decision. */
+export interface JevJobPick {
+	pick: JevPick;
+	/** Candidates Jev was shown. */
+	offered: number;
+	/** Eligible candidates left out to fit the request budget. */
+	dropped: number;
+}
+
+/** The on-demand decision: a tool and a skill, each chosen or not on its own. */
+export interface JevJobRoute {
+	tool: JevJobPick;
+	skill: JevJobPick;
+	elapsedMs: number;
+}
+
+/**
+ * The agent's on-demand route: ask which tool and which skill fit the job, as two choice questions
+ * in one request. Pass an empty list to leave a kind out; it is then not asked at all.
+ *
+ * The budget goes to tools first. Skills are the long tail users, agents, and teammates keep adding,
+ * so if anything is dropped it is a skill, and the caller reports it.
+ */
+export async function routeJobToJev(
+	tools: readonly CatalogEntry[],
+	skills: readonly CatalogEntry[],
+	job: string,
+	ctx: Pick<ExtensionContext, "modelRegistry">,
+	config: GatewayJevConfig,
+	ask: JevAsk = askJev,
+): Promise<JevJobRoute> {
+	const maxBytes = Math.min(config.payloadBytes, JEV_REQUEST_MAX_BYTES);
+	const material = job.slice(0, GATEWAY_JEV_PROMPT_CHARS);
+	let budget = maxBytes - Buffer.byteLength(material, "utf-8") - 2 * QUESTION_SCAFFOLDING_BYTES;
+	const fittedTools = fitCatalogCandidates(tools, Math.max(0, budget));
+	budget -= Buffer.byteLength(JSON.stringify(candidateCriteria(fittedTools.candidates)), "utf-8");
+	const fittedSkills = fitCatalogCandidates(skills, Math.max(0, budget));
+
+	const side = (fitted: { candidates: CatalogEntry[]; dropped: number }, pick: JevPick): JevJobPick => ({
+		pick,
+		offered: fitted.candidates.length,
+		dropped: fitted.dropped,
 	});
-	const answer = decision.choices[JEV_CAPABILITY_QUESTION];
-	if (!answer) {
-		return abstained(decision.rejected[JEV_CAPABILITY_QUESTION] ?? decision.failure ?? "missing");
+	const notAsked: JevPick = { selected: false, reason: "no-candidates" };
+
+	const questions: Record<string, JevQuestion> = {};
+	const allowed: Record<string, string[]> = {};
+	for (const [key, fitted, wording] of [
+		[JEV_TOOL_QUESTION, fittedTools, JOB_TOOL_QUESTION],
+		[JEV_SKILL_QUESTION, fittedSkills, JOB_SKILL_QUESTION],
+	] as const) {
+		if (fitted.candidates.length === 0) continue;
+		questions[key] = { ...wording, criteria: candidateCriteria(fitted.candidates) };
+		allowed[key] = [NO_TOOL, ...fitted.candidates.map((candidate) => candidate.name)];
+	}
+	if (Object.keys(questions).length === 0) {
+		return { tool: side(fittedTools, notAsked), skill: side(fittedSkills, notAsked), elapsedMs: 0 };
 	}
-	if (answer.choice === NO_TOOL) return abstained("none");
-	// A choice without a numeric confidence is not a confident enough answer to activate a tool.
-	if (answer.confidence === undefined) return abstained("unquantified");
+
+	// Only the job, bounded: no prior conversation, no tool schema, no skill body.
+	const payload = buildJevPayload(
+		buildConversation(material, [], { contextTurns: 1, contextChars: GATEWAY_JEV_PROMPT_CHARS }),
+		questions,
+	);
+	const decision = await ask(ctx, gatewayJevConnection(config, true), { payload, maxBytes, allowed });
 	return {
-		selected: true,
-		tool: answer.choice,
-		confidence: answer.confidence,
-		candidates: candidates.length,
+		tool: side(fittedTools, allowed[JEV_TOOL_QUESTION] ? pickFrom(decision, JEV_TOOL_QUESTION) : notAsked),
+		skill: side(fittedSkills, allowed[JEV_SKILL_QUESTION] ? pickFrom(decision, JEV_SKILL_QUESTION) : notAsked),
 		elapsedMs: decision.elapsedMs,
 	};
 }

package/dist/extensions/jev/decisions.test.ts

@@ -25,9 +25,11 @@ import {
 	JEV_ROUTING_EVENT,
 	jevConnection,
 	jevModel,
+	jevUnavailable,
 	readJevAdvisoryConfig,
 	readJevChoice,
 	serializeJevRequest,
+	warnJevUnavailableOnce,
 	type JevConnection,
 } from "./decisions.ts";
 import { jevAnswers, jevResponse, providerTemplate } from "./test-support.ts";
@@ -81,6 +83,19 @@ describe("readJevAdvisoryConfig", () => {
 		expect(readJevAdvisoryConfig(state.settingsPath).routes.memory.enabled).toBe(false);
 	});
 
+	it("keeps the agent's ask route on unless it is explicitly turned off", () => {
+		state.settingsPath = join(tmpdir(), "missing-settings.json");
+		expect(readJevAdvisoryConfig(state.settingsPath).routes.ask.enabled).toBe(true);
+
+		write({ jevAdvisory: { routes: { ask: { timeoutMs: 2_000 }, memory: { timeoutMs: 2_000 } } } });
+		const config = readJevAdvisoryConfig(state.settingsPath);
+		expect(config.routes.ask).toMatchObject({ enabled: true, timeoutMs: 2_000, payloadBytes: 32 * 1024 });
+		expect(config.routes.memory.enabled).toBe(false);
+
+		write({ jevAdvisory: { routes: { ask: { enabled: false } } } });
+		expect(readJevAdvisoryConfig(state.settingsPath).routes.ask.enabled).toBe(false);
+	});
+
 	it("merges per-route settings over the shared endpoint defaults", () => {
 		write({
 			jevAdvisory: {
@@ -314,3 +329,25 @@ describe("telemetry helpers", () => {
 		expect(seen).toEqual([{ channel: JEV_ROUTING_EVENT, data: { event: "decision", route: "memory" } }]);
 	});
 });
+
+describe("reachability before any work", () => {
+	it("names why Jev is out of reach without sending anything", async () => {
+		expect(await jevUnavailable(runtime([]) as never, CONNECTION)).toBe("no-template");
+		expect(await jevUnavailable(runtime([providerTemplate()], false) as never, CONNECTION)).toBe("no-credential");
+		expect(await jevUnavailable(runtime() as never, CONNECTION)).toBeUndefined();
+		expect(completeMock).not.toHaveBeenCalled();
+	});
+
+	it("warns each session once, whichever feature notices first", () => {
+		const notices: string[] = [];
+		const ui = { notify: (message: string) => notices.push(message) };
+		warnJevUnavailableOnce(ui, "tokenin");
+		warnJevUnavailableOnce(ui, "tokenin");
+		expect(notices).toHaveLength(1);
+		expect(notices[0]).toContain("/tokenin add");
+
+		const other: string[] = [];
+		warnJevUnavailableOnce({ notify: (message: string) => other.push(message) }, "custom");
+		expect(other[0]).toContain('"custom" provider');
+	});
+});