pi-codemcp 1.4.0 → 1.5.0

package/README.md

@@ -5,6 +5,7 @@ Fast, typed, sandboxed **Code Mode for every MCP server configured in Pi**.
 Instead of putting every upstream MCP tool definition into the model context, pi-codemcp gives the agent a small interface for discovery, execution, and reuse:
 
 - `codemcp_search` ranks capabilities or pages through a compact inventory without loading full schemas.
+- Optional Jev discovery lets the agent route complete MCP tasks on demand, returning relevant calls, composition guidance, and exact contracts through bounded parallel TypeSafe requests.
 - `codemcp_inspect` returns exact typed SDK stubs only for selected calls.
 - `codemcp_execute` runs one sandboxed Python call graph across one or many MCP servers.
 - `codemcp_edit` applies one exact replacement to the previous execution and reruns it without resending the full code.
@@ -133,6 +134,7 @@ Settings live at `<agent-dir>/pi-codemcp/settings.json` and can also be edited i
 ```json
 {
   "version": 2,
+  "jevEnabled": false,
   "backgroundWarmup": true,
   "cacheTtlHours": 24,
   "executionTimeoutSeconds": 30,
@@ -148,6 +150,12 @@ Settings live at `<agent-dir>/pi-codemcp/settings.json` and can also be edited i
 
 The Python sidecar enforces catalog cache TTL, execution timeout, per-tool timeout, max MCP calls, result size, and disabled-tool policy. The TypeScript Pi layer uses `backgroundWarmup` and `outputLimitKiB` for session warmup and rendered-output truncation; the sidecar still validates those fields so the settings file has one strict shared schema. Version-one files are migrated when loaded, and the removed `outputLineLimit` field is omitted on the next save.
 
+### Jev discovery mode
+
+Enable Jev in `/codemcp` and provide `TYPESAFE_API_KEY`. This replaces `codemcp_search` with the on-demand `codemcp_route` tool, so ordinary messages have no routing delay. When a task may need MCP, the agent sends the complete task plus every enabled MCP call's name and description to TypeSafe in bounded parallel chunks. Jev scores every call, classifies its workflow role, and checks whether an intermediate model/user checkpoint is required; pi-codemcp merges those raw answers into parallel or dependent composition guidance. The result includes exact typed contracts and directs the agent into the appropriate `codemcp_execute` program.
+
+Jev mode is opt-in because routed task text and enabled tool descriptions leave the machine. If the API key is missing, pi-codemcp keeps local `codemcp_search` active. If a Jev route fails, search is activated as an in-session fallback. `TYPESAFE_BASE_URL` and `TYPESAFE_DEFAULT_MODEL` are honored by the official TypeSafe SDK.
+
 ## Search and execute flow
 
 The agent searches for a capability, inspects the selected exact stub when needed, and executes a compact plan. Unscoped searches discover stale or missing server catalogs independently: available servers still return results, while `discovery_failures` explicitly reports unavailable servers. Server-scoped searches remain fail-fast.

package/extensions/index.ts

@@ -1,12 +1,16 @@
-import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import {
   CONFIG_DIR_NAME,
   type ExtensionAPI,
   type ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
+import { TypeSafeClient } from "@typesafe-ai/sdk";
 import { newCodeMcpTraceId, SavedChainManager } from "../src/chains.js";
 import { setMcpServerEnabled } from "../src/config.js";
 import { summarizeError } from "../src/errors.js";
+import { JevRouter } from "../src/jev-router.js";
+import { readJsonObject, writeJsonObjectAtomically } from "../src/json-file.js";
 import { CodeMcpLifecycle } from "../src/lifecycle.js";
 import type { SidecarClientOptions } from "../src/mcp-client.js";
 import {
@@ -22,13 +26,21 @@ import {
   setEditableSetting,
   setToolEnabled,
 } from "../src/settings.js";
-import { registerCodeMcpTools } from "../src/tools.js";
+import { registerCodeMcpTools, registerJevRouteTool } from "../src/tools.js";
 
-export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
+export interface CodeMcpExtensionOptions extends SidecarClientOptions {
+  jevClient?: TypeSafeClient;
+}
+
+export function createCodeMcpExtension(options: CodeMcpExtensionOptions = {}) {
   return function codeMcpExtension(pi: ExtensionAPI): void {
-    const lifecycle = new CodeMcpLifecycle(options);
+    const { jevClient, ...sidecarOptions } = options;
+    const lifecycle = new CodeMcpLifecycle(sidecarOptions);
     const chains = new SavedChainManager(pi, lifecycle);
+    const routerClient = jevClient ?? createJevClient();
+    const jevRouter = routerClient ? new JevRouter(lifecycle, routerClient) : undefined;
     registerCodeMcpTools(pi, lifecycle, chains);
+    registerJevRouteTool(pi, () => jevRouter);
 
     pi.registerCommand("codemcp", {
       description: "Manage CodeMCP servers, saved chains, tools, and settings",
@@ -71,7 +83,11 @@ export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
             onSetSetting: async (key, value) => {
               const updated = setEditableSetting(lifecycle.loadSettings(), key, value);
               saveCodeMcpSettings(lifecycle.settingsPath, updated);
-              await lifecycle.request("reload_settings", {});
+              if (key !== "jevEnabled") await lifecycle.request("reload_settings", {});
+              setDiscoveryTools(pi, updated.jevEnabled && jevRouter !== undefined);
+              if (updated.jevEnabled && !jevRouter) {
+                ctx.ui.notify("Jev mode requires TYPESAFE_API_KEY; using local search", "warning");
+              }
               return updated;
             },
             onSetChainEnabled: async (chain, enabled) => {
@@ -97,6 +113,11 @@ export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
     });
 
     pi.on("session_start", (_event, ctx) => {
+      try {
+        showChangelogOnce(ctx, join(dirname(lifecycle.settingsPath), "changelog.json"));
+      } catch (error) {
+        ctx.ui.notify(`CodeMCP changelog failed: ${summarizeError(error)}`, "warning");
+      }
       bindProjectChainScope(ctx, lifecycle, chains);
       chains.activatePersisted();
       for (const error of chains.startupErrors) ctx.ui.notify(error, "warning");
@@ -107,6 +128,11 @@ export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
         ctx.ui.notify(`CodeMCP settings failed: ${summarizeError(error)}`, "warning");
         return;
       }
+      const useJev = settings.jevEnabled && jevRouter !== undefined;
+      setDiscoveryTools(pi, useJev);
+      if (settings.jevEnabled && !jevRouter) {
+        ctx.ui.notify("Jev mode requires TYPESAFE_API_KEY; using local search", "warning");
+      }
       if (!settings.backgroundWarmup) return;
       void lifecycle.warmup().catch((error: unknown) => {
         ctx.ui.notify(`CodeMCP background warmup failed: ${summarizeError(error)}`, "warning");
@@ -154,6 +180,38 @@ export async function setServerEnabledFromManager(
 
 export default createCodeMcpExtension();
 
+const CHANGELOG_ID = "jev-routing-v1";
+const CHANGELOG_MESSAGE =
+  "pi-codemcp update: optional Jev routing is now available! Enable Jev in /codemcp → Settings to let Jev select and compose MCP calls, it's pretty cool";
+
+export function showChangelogOnce(
+  ctx: Pick<ExtensionCommandContext, "mode" | "ui">,
+  path: string,
+): void {
+  if (ctx.mode !== "tui") return;
+  const state = existsSync(path) ? readJsonObject(path, "CodeMCP changelog state") : {};
+  if (state.lastSeen === CHANGELOG_ID) return;
+  ctx.ui.notify(CHANGELOG_MESSAGE, "info");
+  writeJsonObjectAtomically(path, { lastSeen: CHANGELOG_ID });
+}
+
+function createJevClient(): TypeSafeClient | undefined {
+  return process.env.TYPESAFE_API_KEY?.trim() ? new TypeSafeClient() : undefined;
+}
+
+function setDiscoveryTools(pi: ExtensionAPI, useJev: boolean): void {
+  const selected = useJev ? "codemcp_route" : "codemcp_search";
+  const current = pi.getActiveTools();
+  if (
+    current.includes(selected) &&
+    !current.includes(useJev ? "codemcp_search" : "codemcp_route")
+  ) {
+    return;
+  }
+  const active = current.filter((name) => name !== "codemcp_search" && name !== "codemcp_route");
+  pi.setActiveTools([...active, selected]);
+}
+
 export async function promptForProblemReport(
   pi: Pick<ExtensionAPI, "sendUserMessage">,
   ctx: Pick<ExtensionCommandContext, "ui">,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codemcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Typed, sandboxed Code Mode access to configured MCP servers for Pi",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -52,7 +52,8 @@
     "image": "https://raw.githubusercontent.com/yolonir/pi-codemcp/main/media/preview.png"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@typesafe-ai/sdk": "0.6.0"
   },
   "optionalDependencies": {
     "@manzt/uv-darwin-arm64": "0.8.13",

package/sidecar/executor.py

@@ -93,11 +93,13 @@ class ExecutionContext:
         call_tool: ContextToolCall,
         settings: ExecutionSettings,
         deadline: float,
+        progress: ProgressReporter | None = None,
     ) -> None:
         self.catalog = catalog
         self.call_tool = call_tool
         self.settings = settings
         self.deadline = deadline
+        self.progress = progress
         self.calls_made = 0
         self.chain_calls = 0
         self.metrics = ExecutionMetrics()
@@ -117,6 +119,7 @@ class ExecutionContext:
 
 ToolCall = Callable[[str, JsonObject], Awaitable[JsonValue]]
 ContextToolCall = Callable[[str, JsonObject, ExecutionContext], Awaitable[JsonValue]]
+ProgressReporter = Callable[[int, str], Awaitable[None]]
 ExternalFunction = Callable[..., Awaitable[JsonValue]]
 ResultRetainer = Callable[[JsonValue], RetainedResult | None]
 
@@ -291,9 +294,10 @@ class MontyExecutor:
         *,
         input_value: JsonValue = None,
         retain_result: ResultRetainer | None = None,
+        progress: ProgressReporter | None = None,
     ) -> ExecutionResponse:
         async with self._execution_lock:
-            context = self._new_context(self.catalog, call_tool)
+            context = self._new_context(self.catalog, call_tool, progress=progress)
             return await self._execute_program(
                 code,
                 context,
@@ -397,6 +401,8 @@ class MontyExecutor:
         self,
         catalog: ToolCatalog,
         call_tool: ContextToolCall,
+        *,
+        progress: ProgressReporter | None = None,
     ) -> ExecutionContext:
         loop = asyncio.get_running_loop()
         return ExecutionContext(
@@ -404,6 +410,7 @@ class MontyExecutor:
             call_tool=call_tool,
             settings=self.settings,
             deadline=loop.time() + self.settings.timeout_seconds,
+            progress=progress,
         )
 
     async def _execute_program(  # ruff:ignore[complex-structure, too-many-statements]
@@ -502,9 +509,13 @@ class MontyExecutor:
                 raise ValueError(message) from error
             if spec.kind == "saved_chain":
                 context.chain_calls += 1
+                if context.progress is not None:
+                    await context.progress(context.total_calls, spec.call)
                 return await context.call_tool(name, validated, context)
 
             context.calls_made += 1
+            if context.progress is not None:
+                await context.progress(context.total_calls, spec.call)
             remaining = context.remaining_seconds()
             if remaining <= 0:
                 raise TimeoutError
@@ -607,6 +618,8 @@ class MontyExecutor:
             "max_duration_secs": remaining,
             "max_memory": context.settings.max_memory_bytes,
         }
+        if context.progress is not None:
+            await context.progress(context.total_calls, "executing")
         runtime_started = time.perf_counter()
         try:
             async with asyncio.timeout(remaining + 0.1):

package/sidecar/gateway.py

@@ -11,7 +11,7 @@ from contextlib import AsyncExitStack, asynccontextmanager, suppress
 from typing import TYPE_CHECKING, Literal, NamedTuple, Protocol, cast
 
 import pydantic_monty
-from fastmcp import Client, FastMCP
+from fastmcp import Client, Context, FastMCP
 from fastmcp.mcp_config import RemoteMCPServer, StdioMCPServer
 from pydantic_core import to_json
 from rapidfuzz import fuzz, process
@@ -33,6 +33,7 @@ from .executor import (
     ExecutionFailureInfo,
     ExecutionResponse,
     MontyExecutor,
+    ProgressReporter,
 )
 from .mcp_config import NormalizedConfig, load_mcp_json, normalize_mcp_config
 from .models import (
@@ -601,15 +602,17 @@ class GatewayRuntime:
         code: str,
         trace_id: str,
         input_ref: str | None = None,
+        progress: ProgressReporter | None = None,
     ) -> ExecutionResponse:
         async with self._execute_lock:
-            return await self._execute(code, trace_id, input_ref)
+            return await self._execute(code, trace_id, input_ref, progress)
 
     async def edit_execute(
         self,
         old_text: str,
         new_text: str,
         trace_id: str,
+        progress: ProgressReporter | None = None,
     ) -> ExecutionResponse:
         async with self._execute_lock:
             previous = self._last_execution
@@ -625,13 +628,14 @@ class GatewayRuntime:
                     f"old_text must match the previous code exactly once; found {matches} matches"
                 )
             code = previous.code.replace(old_text, new_text, 1)
-            return await self._execute(code, trace_id, previous.input_ref)
+            return await self._execute(code, trace_id, previous.input_ref, progress)
 
     async def _execute(
         self,
         code: str,
         trace_id: str,
         input_ref: str | None,
+        progress: ProgressReporter | None = None,
     ) -> ExecutionResponse:
         self._last_execution = None
         started = time.perf_counter()
@@ -682,6 +686,7 @@ class GatewayRuntime:
                 self._dispatch,
                 input_value=input_value,
                 retain_result=self.refinement_cache.retain,
+                progress=progress,
             )
         except BaseException as error:
             cancelled = isinstance(error, asyncio.CancelledError)
@@ -1615,6 +1620,13 @@ def _require_runtime() -> GatewayRuntime:
     return _runtime_state.runtime
 
 
+def _progress_reporter(ctx: Context) -> ProgressReporter:
+    async def report(total_calls: int, message: str) -> None:
+        await ctx.report_progress(progress=float(total_calls), message=message)
+
+    return report
+
+
 def configure_runtime_paths(paths: RuntimePaths | None) -> None:
     _runtime_state.paths = paths
 
@@ -1714,10 +1726,16 @@ async def set_chain_enabled(
 async def execute(
     trace_id: str,
     code: str,
+    ctx: Context,
     input_ref: str | None = None,
 ) -> ExecutionResponse:
     """Type-check and run one sandboxed Python MCP SDK chain."""
-    return await _require_runtime().execute(code, trace_id, input_ref)
+    return await _require_runtime().execute(
+        code,
+        trace_id,
+        input_ref,
+        _progress_reporter(ctx),
+    )
 
 
 @mcp.tool
@@ -1725,9 +1743,15 @@ async def edit_execute(
     trace_id: str,
     old_text: str,
     new_text: str,
+    ctx: Context,
 ) -> ExecutionResponse:
     """Patch and rerun the last sandbox execution."""
-    return await _require_runtime().edit_execute(old_text, new_text, trace_id)
+    return await _require_runtime().edit_execute(
+        old_text,
+        new_text,
+        trace_id,
+        _progress_reporter(ctx),
+    )
 
 
 @mcp.tool

package/sidecar/settings.py

@@ -26,6 +26,7 @@ class CodeMcpSettings(BaseModel):
     )
 
     version: Literal[2] = 2
+    jev_enabled: bool = False
     background_warmup: bool = True
     cache_ttl_hours: int = Field(default=24, ge=0, le=720)
     execution_timeout_seconds: int = Field(default=30, ge=1, le=300)
@@ -60,4 +61,10 @@ def load_settings(path: Path) -> CodeMcpSettings:
     if isinstance(value, dict) and value.get("version", 1) == 1:
         value = {key: item for key, item in value.items() if key != "outputLineLimit"}
         value["version"] = 2
+    if isinstance(value, dict) and "discoveryMode" in value:
+        mode = value.pop("discoveryMode")
+        if not isinstance(mode, str) or mode not in {"search", "jev"}:
+            value["discoveryMode"] = mode
+        else:
+            value.setdefault("jevEnabled", mode == "jev")
     return CodeMcpSettings.model_validate(value)

package/src/execution-rendering.ts

@@ -16,6 +16,12 @@ interface RenderResult {
   details?: unknown;
 }
 
+/** Details sent with partial updates while an execution is running. */
+export interface ExecutionProgressDetails {
+  callsMade: number;
+  currentCall?: string;
+}
+
 interface ExecutionRendererOptions {
   partialText?: string;
   expandDescription?: string;
@@ -28,6 +34,16 @@ export function renderExecutionResult(
   options: ExecutionRendererOptions = {},
 ): Text {
   if (state.isPartial) {
+    const progress = result.details as ExecutionProgressDetails | undefined;
+    if (typeof progress?.callsMade === "number") {
+      const calls = progress.callsMade;
+      const current = progress.currentCall ? ` · ${progress.currentCall}` : "";
+      return new Text(
+        `\n${theme.fg("warning", `Executing · ${calls} MCP ${calls === 1 ? "call" : "calls"}${current}...`)}`,
+        0,
+        0,
+      );
+    }
     return new Text(
       `\n${theme.fg("warning", options.partialText ?? "Preflight check, then execution...")}`,
       0,

package/src/jev-router.ts

@@ -0,0 +1,323 @@
+import { randomUUID } from "node:crypto";
+import { choice, noul, type Questions, type TypeSafeClient } from "@typesafe-ai/sdk";
+import type { CodeMcpLifecycle } from "./lifecycle.js";
+
+const TOOL_RELEVANCE_THRESHOLD = 0.65;
+const NOUL_THRESHOLD = 0.5;
+// ponytail: bound injected schemas; raise only if routing evals show recall loss.
+const MAX_SELECTED_TOOLS = 8;
+const CATALOG_PAGE_SIZE = 20;
+const JEV_CHUNK_SIZE = 40;
+
+type ToolRole = "source" | "enrichment" | "sink" | "standalone" | "unspecified";
+const TOOL_ROLE_BY_CHOICE: Readonly<Record<string, ToolRole>> = {
+  source: "source",
+  enrichment: "enrichment",
+  sink: "sink",
+  standalone: "standalone",
+  irrelevant: "unspecified",
+};
+type WorkflowShape = "single_call" | "parallel" | "pipeline" | "mixed";
+
+interface CatalogTool {
+  call: string;
+  description?: string;
+}
+
+interface IndexedTool {
+  index: number;
+  tool: CatalogTool;
+}
+
+interface ChunkResult {
+  tools: JevSelectedTool[];
+  needsAnyTool?: number;
+  needsCheckpoint?: number;
+}
+
+export interface JevSelectedTool extends CatalogTool {
+  relevance: number;
+  role: ToolRole;
+}
+
+export interface JevRoute {
+  prompt: string;
+  selected: JevSelectedTool[];
+  needsAnyTool: number;
+  workflowShape: WorkflowShape;
+  needsCheckpoint: number;
+}
+
+export class JevRouter {
+  constructor(
+    private readonly lifecycle: Pick<CodeMcpLifecycle, "request">,
+    private readonly client: TypeSafeClient,
+  ) {}
+
+  async route(task: string, recentContext = "", signal?: AbortSignal): Promise<JevRoute> {
+    const catalog = await this.loadCatalog(signal);
+    if (catalog.length === 0) return emptyRoute();
+
+    const chunks = chunk(
+      catalog.map((tool, index) => ({ tool, index })),
+      JEV_CHUNK_SIZE,
+    );
+    const results = await Promise.all(
+      chunks.map((tools, index) =>
+        this.evaluateChunk(task, recentContext, tools, index === 0, signal),
+      ),
+    );
+    const needsAnyTool = results[0]?.needsAnyTool ?? 0;
+    const needsCheckpoint = results[0]?.needsCheckpoint ?? 0;
+    const ranked = results
+      .flatMap((result) => result.tools)
+      .sort(
+        (left, right) => right.relevance - left.relevance || left.call.localeCompare(right.call),
+      );
+    const selected =
+      needsAnyTool >= NOUL_THRESHOLD
+        ? ranked
+            .filter((tool) => tool.relevance >= TOOL_RELEVANCE_THRESHOLD)
+            .slice(0, MAX_SELECTED_TOOLS)
+        : [];
+    const workflowShape = workflowShapeFor(selected);
+    if (selected.length === 0) {
+      return { ...emptyRoute(), needsAnyTool, needsCheckpoint, workflowShape };
+    }
+
+    const inspection = await this.lifecycle.request(
+      "inspect",
+      {
+        calls: selected.map((tool) => tool.call),
+        trace_id: `jev-${randomUUID()}`,
+      },
+      signal,
+    );
+    const prelude = typeof inspection.prelude === "string" ? inspection.prelude : "";
+    const stubs = Array.isArray(inspection.results)
+      ? inspection.results.flatMap((item) => {
+          if (!isRecord(item) || typeof item.stub !== "string") return [];
+          return [item.stub];
+        })
+      : [];
+    if (stubs.length !== selected.length) {
+      throw new Error("CodeMCP inspect returned incomplete Jev-selected contracts");
+    }
+
+    return {
+      prompt: jevPrompt(
+        selected,
+        workflowShape,
+        needsCheckpoint,
+        [prelude, ...stubs].filter(Boolean).join("\n\n"),
+      ),
+      selected,
+      needsAnyTool,
+      workflowShape,
+      needsCheckpoint,
+    };
+  }
+
+  private async evaluateChunk(
+    task: string,
+    recentContext: string,
+    tools: IndexedTool[],
+    includeTaskQuestions: boolean,
+    signal?: AbortSignal,
+  ): Promise<ChunkResult> {
+    const questions: Questions = {};
+    if (includeTaskQuestions) {
+      questions.needs_any_tool = noul(
+        "Does satisfying the user's request require at least one configured external-service or saved-workflow tool?",
+        {
+          true: "The request needs current, private, or external state, or asks for an external action.",
+          false: "Explanation, reasoning, or local coding tools can fully satisfy the request.",
+        },
+      );
+      questions.needs_checkpoint = noul(
+        "Must the agent inspect an intermediate result, make a semantic decision, or obtain user approval before the next external call?",
+        {
+          true: "A model or user decision is required between tool stages.",
+          false: "One deterministic CodeMCP program can safely run the complete workflow.",
+        },
+      );
+    }
+    for (const { index, tool } of tools) {
+      const toolDescription = {
+        call: tool.call,
+        description: tool.description ?? tool.call,
+      };
+      questions[`tool_${index}`] = noul(
+        {
+          question:
+            "Is this exact tool necessary to satisfy an explicit part of the user's request?",
+          tool: toolDescription,
+        },
+        {
+          true: "The minimal correct workflow needs this capability.",
+          false: "The tool is unrelated, redundant, optional, or merely adjacent.",
+        },
+      );
+      questions[`role_${index}`] = choice(
+        {
+          question: "What role should this tool have in the minimal requested workflow?",
+          tool: toolDescription,
+        },
+        {
+          source: "Retrieves initial data.",
+          enrichment: "Retrieves data using an earlier result.",
+          sink: "Performs a downstream action using earlier results.",
+          standalone: "Independently completes one requested action.",
+          irrelevant: "Should not be used for this task.",
+        },
+      );
+    }
+
+    const response = await this.client.systemOne(
+      {
+        state: {
+          task,
+          ...(recentContext ? { recent_context: recentContext } : {}),
+        },
+        questions,
+      },
+      signal ? { signal } : undefined,
+    );
+    return {
+      tools: tools.map(({ index, tool }) => ({
+        ...tool,
+        relevance: noulValue(response.answers[`tool_${index}`]),
+        role: toolRoleValue(response.answers[`role_${index}`]),
+      })),
+      ...(includeTaskQuestions
+        ? {
+            needsAnyTool: noulValue(response.answers.needs_any_tool),
+            needsCheckpoint: noulValue(response.answers.needs_checkpoint),
+          }
+        : {}),
+    };
+  }
+
+  private async loadCatalog(signal?: AbortSignal): Promise<CatalogTool[]> {
+    const tools: CatalogTool[] = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.lifecycle.request(
+        "search",
+        {
+          mode: "inventory",
+          detail: "names",
+          limit: CATALOG_PAGE_SIZE,
+          cursor,
+          trace_id: `jev-${randomUUID()}`,
+        },
+        signal,
+      );
+      if (Array.isArray(page.results)) {
+        for (const item of page.results) {
+          if (!isRecord(item) || typeof item.call !== "string") continue;
+          tools.push({
+            call: item.call,
+            ...(typeof item.description === "string" ? { description: item.description } : {}),
+          });
+        }
+      }
+      if (typeof page.next_cursor !== "number") break;
+      if (page.next_cursor <= cursor) throw new Error("CodeMCP inventory cursor did not advance");
+      cursor = page.next_cursor;
+    }
+    return tools;
+  }
+}
+
+function emptyRoute(): JevRoute {
+  return {
+    prompt: "Jev found no configured MCP tool relevant to this request.",
+    selected: [],
+    needsAnyTool: 0,
+    workflowShape: "single_call",
+    needsCheckpoint: 0,
+  };
+}
+
+function workflowShapeFor(selected: JevSelectedTool[]): WorkflowShape {
+  if (selected.length <= 1) return "single_call";
+  const independent = selected.filter(
+    (tool) => tool.role === "source" || tool.role === "standalone",
+  ).length;
+  const downstream = selected.some((tool) => tool.role === "enrichment" || tool.role === "sink");
+  if (!downstream) return "parallel";
+  return independent > 1 ? "mixed" : "pipeline";
+}
+
+function jevPrompt(
+  selected: JevSelectedTool[],
+  workflowShape: WorkflowShape,
+  needsCheckpoint: number,
+  contracts: string,
+): string {
+  const roles = selected.map((tool) => `- ${tool.call}: ${tool.role}`).join("\n");
+  const execution =
+    needsCheckpoint >= NOUL_THRESHOLD
+      ? "Run only the first stage in codemcp_execute, return compact decision data, then preserve a model/user checkpoint before downstream calls."
+      : workflowInstruction(workflowShape);
+  return [
+    `Jev selected these MCP calls:\n${roles}`,
+    `Composition: ${workflowShape}.`,
+    `Execution recommendation: ${execution}`,
+    "Use these exact typed SDK contracts:",
+    "```python",
+    contracts,
+    "```",
+  ].join("\n\n");
+}
+
+function workflowInstruction(shape: WorkflowShape): string {
+  switch (shape) {
+    case "single_call":
+      return "Write and run one minimal codemcp_execute program using the selected call.";
+    case "parallel":
+      return "Write and run one codemcp_execute program using asyncio.gather for independent calls, then combine their results locally.";
+    case "pipeline":
+      return "Write and run one codemcp_execute program that passes earlier outputs into dependent calls.";
+    case "mixed":
+      return "Write and run one codemcp_execute program that gathers independent source calls, then feeds their results into downstream calls.";
+  }
+}
+
+function toolRoleValue(answer: unknown): ToolRole {
+  const role = TOOL_ROLE_BY_CHOICE[choiceValue(answer)];
+  if (!role) throw new Error("TypeSafe returned an invalid Jev tool role");
+  return role;
+}
+
+function choiceValue(answer: unknown): string {
+  if (!isRecord(answer) || answer.type !== "choice" || typeof answer.choice !== "string") {
+    throw new Error("TypeSafe returned an invalid Jev routing choice");
+  }
+  return answer.choice;
+}
+
+function noulValue(answer: unknown): number {
+  if (
+    !isRecord(answer) ||
+    answer.type !== "noul" ||
+    typeof answer.noul !== "number" ||
+    !Number.isFinite(answer.noul)
+  ) {
+    throw new Error("TypeSafe returned an invalid Jev routing answer");
+  }
+  return answer.noul;
+}
+
+function chunk<T>(values: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let index = 0; index < values.length; index += size) {
+    chunks.push(values.slice(index, index + size));
+  }
+  return chunks;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/lifecycle.ts

@@ -1,4 +1,9 @@
-import { SidecarClient, type SidecarClientOptions, type SidecarToolName } from "./mcp-client.js";
+import {
+  SidecarClient,
+  type SidecarClientOptions,
+  type SidecarProgressCallback,
+  type SidecarToolName,
+} from "./mcp-client.js";
 import { type CodeMcpSettings, loadCodeMcpSettings } from "./settings.js";
 
 export class CodeMcpLifecycle {
@@ -37,9 +42,10 @@ export class CodeMcpLifecycle {
     name: SidecarToolName,
     args: Record<string, unknown>,
     signal?: AbortSignal,
+    onProgress?: SidecarProgressCallback,
   ): Promise<Record<string, unknown>> {
     await this.reloadBarrier;
-    return this.sidecar.call(name, args, signal);
+    return this.sidecar.call(name, args, signal, onProgress);
   }
 
   async warmup(): Promise<void> {

package/src/mcp-client.ts

@@ -66,6 +66,14 @@ export function sidecarToolTimeoutMs(
   return DEFAULT_TOOL_TIMEOUT_MS;
 }
 
+export interface SidecarProgress {
+  progress: number;
+  total?: number | undefined;
+  message?: string | undefined;
+}
+
+export type SidecarProgressCallback = (progress: SidecarProgress) => void;
+
 export interface SidecarClientOptions {
   packageRoot?: string;
   agentDir?: string;
@@ -153,7 +161,12 @@ export class SidecarClient {
     return this.client !== undefined && this.transport?.pid !== null;
   }
 
-  async call(name: SidecarToolName, args: JsonObject, signal?: AbortSignal): Promise<JsonObject> {
+  async call(
+    name: SidecarToolName,
+    args: JsonObject,
+    signal?: AbortSignal,
+    onProgress?: SidecarProgressCallback,
+  ): Promise<JsonObject> {
     await this.ensureStarted(signal);
     const client = this.client;
     if (!client) throw new Error("Sidecar client failed to initialize");
@@ -165,6 +178,7 @@ export class SidecarClient {
     const result = await client.callTool({ name, arguments: args }, undefined, {
       timeout,
       ...(signal === undefined ? {} : { signal }),
+      ...(onProgress === undefined ? {} : { onprogress: onProgress }),
     });
 
     if (result.isError) {

package/src/modal.ts

@@ -13,7 +13,12 @@ import {
 } from "@earendil-works/pi-tui";
 import type { ChainScope, SavedChainView } from "./chains.js";
 import { summarizeError } from "./errors.js";
-import type { CodeMcpSettings, EditableSettingKey, EditableSettingValue } from "./settings.js";
+import {
+  type CodeMcpSettings,
+  type EditableSettingKey,
+  type EditableSettingValue,
+  setEditableSetting,
+} from "./settings.js";
 
 export interface ToolModalState {
   name: string;
@@ -136,13 +141,22 @@ const OVERLAY_OPTIONS = {
   minWidth: 72,
   maxHeight: "85%",
 } as const;
-
 const PROBLEM_REPORT_LABEL = "Extension is broken!";
 const PROBLEM_REPORT_DESCRIPTION =
   "Well, that sucks. With this button you can ask the agent to describe the problem and prepare a GitHub issue for review. The goal is to make pi-codemcp usable for everyone, don't be lazy - submit an issue. Don't worry, you will see all prompts, this is a transparent process.";
 const PROBLEM_REPORT_SHORTCUT = "Report issue: R";
 
 const SETTING_DEFINITIONS: SettingDefinition[] = [
+  {
+    key: "jevEnabled",
+    label: "Enable Jev",
+    description:
+      "Let the agent call Jev on demand to select and compose relevant MCP contracts instead of local search. Requires TYPESAFE_API_KEY and sends routed tasks and enabled tool descriptions to TypeSafe.",
+    choices: [
+      { value: false, label: "false" },
+      { value: true, label: "true" },
+    ],
+  },
   {
     key: "backgroundWarmup",
     label: "Background warmup",
@@ -327,6 +341,7 @@ class ServerManagerModal implements Component, Focusable {
   private selectedToolIndex = 0;
   private selectedChainIndex = 0;
   private selectedSettingIndex = 0;
+  private settingBusy = false;
   private settingsError: string | undefined;
   private _focused = false;
 
@@ -1005,8 +1020,9 @@ class ServerManagerModal implements Component, Focusable {
 
   private cycleSelectedSetting(direction: -1 | 1): void {
     const definition = SETTING_DEFINITIONS[this.selectedSettingIndex];
-    if (!definition) return;
-    const current = this.options.settings[definition.key];
+    if (!definition || this.settingBusy) return;
+    const previous = this.options.settings;
+    const current = previous[definition.key];
     const currentIndex = Math.max(
       0,
       definition.choices.findIndex((choice) => choice.value === current),
@@ -1014,16 +1030,23 @@ class ServerManagerModal implements Component, Focusable {
     const choice =
       definition.choices[cycleIndex(currentIndex, direction, definition.choices.length)];
     if (!choice) return;
+    this.settingBusy = true;
     this.settingsError = undefined;
+    this.options.settings = setEditableSetting(previous, definition.key, choice.value);
+    this.requestRender();
     void this.options
       .onSetSetting(definition.key, choice.value)
       .then((settings) => {
         this.options.settings = settings;
       })
       .catch((error: unknown) => {
+        this.options.settings = previous;
         this.settingsError = summarizeError(error);
       })
-      .finally(() => this.requestRender());
+      .finally(() => {
+        this.settingBusy = false;
+        this.requestRender();
+      });
   }
 
   private focusProblemReport(): void {

package/src/settings.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { readJsonObject, requireJsonObject, writeJsonObjectAtomically } from "./json-file.js";
 
 export interface CodeMcpSettings {
+  jevEnabled: boolean;
   backgroundWarmup: boolean;
   cacheTtlHours: number;
   executionTimeoutSeconds: number;
@@ -16,6 +17,7 @@ export type EditableSettingKey = Exclude<keyof CodeMcpSettings, "disabledTools">
 export type EditableSettingValue = boolean | number;
 
 export const DEFAULT_CODEMCP_SETTINGS: Readonly<CodeMcpSettings> = {
+  jevEnabled: false,
   backgroundWarmup: true,
   cacheTtlHours: 24,
   executionTimeoutSeconds: 30,
@@ -28,6 +30,7 @@ export const DEFAULT_CODEMCP_SETTINGS: Readonly<CodeMcpSettings> = {
 
 const ALLOWED_KEYS = new Set([
   "version",
+  "jevEnabled",
   "backgroundWarmup",
   "cacheTtlHours",
   "executionTimeoutSeconds",
@@ -45,16 +48,18 @@ export function loadCodeMcpSettings(path: string): CodeMcpSettings {
   if (version !== 1 && version !== 2) {
     throw new Error(`Unsupported CodeMCP settings version: ${String(version)}`);
   }
-  const migrated =
+  const versionMigrated =
     version === 1
       ? Object.fromEntries(Object.entries(root).filter(([key]) => key !== "outputLineLimit"))
       : root;
+  const migrated = migrateDiscoveryMode(versionMigrated);
   const unknown = Object.keys(migrated).filter((key) => !ALLOWED_KEYS.has(key));
   if (unknown.length > 0) {
     throw new Error(`Unknown CodeMCP settings: ${unknown.join(", ")}`);
   }
 
   return {
+    jevEnabled: booleanSetting(migrated, "jevEnabled"),
     backgroundWarmup: booleanSetting(migrated, "backgroundWarmup"),
     cacheTtlHours: integerSetting(migrated, "cacheTtlHours", 0, 720),
     executionTimeoutSeconds: integerSetting(migrated, "executionTimeoutSeconds", 1, 300),
@@ -69,6 +74,7 @@ export function loadCodeMcpSettings(path: string): CodeMcpSettings {
 export function saveCodeMcpSettings(path: string, settings: CodeMcpSettings): void {
   writeJsonObjectAtomically(path, {
     version: 2,
+    jevEnabled: settings.jevEnabled,
     backgroundWarmup: settings.backgroundWarmup,
     cacheTtlHours: settings.cacheTtlHours,
     executionTimeoutSeconds: settings.executionTimeoutSeconds,
@@ -85,7 +91,7 @@ export function setEditableSetting(
   key: EditableSettingKey,
   value: EditableSettingValue,
 ): CodeMcpSettings {
-  if (key === "backgroundWarmup") {
+  if (key === "jevEnabled" || key === "backgroundWarmup") {
     if (typeof value !== "boolean") throw new TypeError(`${key} must be a boolean`);
     return { ...settings, [key]: value };
   }
@@ -112,7 +118,21 @@ function cloneDefaults(): CodeMcpSettings {
   return { ...DEFAULT_CODEMCP_SETTINGS, disabledTools: {} };
 }
 
-function booleanSetting(root: Record<string, unknown>, key: "backgroundWarmup"): boolean {
+function migrateDiscoveryMode(root: Record<string, unknown>): Record<string, unknown> {
+  if (root.discoveryMode === undefined) return root;
+  if (root.discoveryMode !== "search" && root.discoveryMode !== "jev") {
+    throw new TypeError("discoveryMode must be search or jev");
+  }
+  return {
+    ...Object.fromEntries(Object.entries(root).filter(([key]) => key !== "discoveryMode")),
+    jevEnabled: root.jevEnabled ?? root.discoveryMode === "jev",
+  };
+}
+
+function booleanSetting(
+  root: Record<string, unknown>,
+  key: "jevEnabled" | "backgroundWarmup",
+): boolean {
   const value = root[key] ?? DEFAULT_CODEMCP_SETTINGS[key];
   if (typeof value !== "boolean") throw new TypeError(`${key} must be a boolean`);
   return value;
@@ -120,7 +140,7 @@ function booleanSetting(root: Record<string, unknown>, key: "backgroundWarmup"):
 
 function integerSetting(
   root: Record<string, unknown>,
-  key: Exclude<EditableSettingKey, "backgroundWarmup">,
+  key: Exclude<EditableSettingKey, "jevEnabled" | "backgroundWarmup">,
   minimum: number,
   maximum: number,
 ): number {

package/src/tools.ts

@@ -12,7 +12,9 @@ import {
   previewExecutionValue,
   renderExecutionResult,
 } from "./execution-rendering.js";
+import type { JevRouter } from "./jev-router.js";
 import type { CodeMcpLifecycle } from "./lifecycle.js";
+import type { SidecarProgress } from "./mcp-client.js";
 import { type CodeMcpOutputDetails, formatCodeMcpOutput } from "./output.js";
 import {
   EXECUTE_PROMPT_GUIDELINES,
@@ -73,6 +75,8 @@ const SearchParameters = Type.Object({
   ),
 });
 
+const JevRouteParameters = Type.Object({});
+
 const InspectParameters = Type.Object({
   calls: Type.Array(Type.String({ minLength: 1 }), {
     minItems: 1,
@@ -162,6 +166,76 @@ const EditExecuteParameters = Type.Object({
   }),
 });
 
+export function registerJevRouteTool(
+  pi: ExtensionAPI,
+  getRouter: () => Pick<JevRouter, "route"> | undefined,
+): void {
+  pi.registerTool({
+    name: "codemcp_route",
+    label: "Jev MCP Route",
+    description:
+      "Use Jev to select every configured MCP call relevant to a complete task, classify each call's workflow role, recommend parallel or dependent composition, and return exact typed SDK contracts. Use when the task may require external services or saved workflows. If no configured capability applies, returns no calls.",
+    promptSnippet: "Select and compose MCP calls for a complete task with Jev",
+    promptGuidelines: [
+      "Use codemcp_route once per distinct task when MCP capabilities may be needed; route again only if the task changes or the selected contracts cannot complete it. It reads the current request and recent conversation context automatically.",
+      "After codemcp_route returns contracts, immediately write and run the recommended minimal codemcp_execute program instead of stopping to describe the plan.",
+      "Follow codemcp_route composition guidance: gather independent calls, sequence dependent calls, and preserve a model turn only for semantic decisions or approvals.",
+    ],
+    parameters: JevRouteParameters,
+    async execute(_toolCallId, _params, signal, onUpdate, ctx) {
+      const router = getRouter();
+      if (!router) throw new Error("Jev routing requires TYPESAFE_API_KEY");
+      const { task, recentContext } = currentRouteTask(ctx.sessionManager.buildContextEntries());
+      onUpdate?.({
+        content: [{ type: "text", text: "Jev is selecting and composing MCP calls..." }],
+        details: undefined,
+      });
+      try {
+        const route = await router.route(task, recentContext, signal);
+        return {
+          content: [{ type: "text", text: route.prompt }],
+          details: {
+            selected: route.selected.map((tool) => ({
+              call: tool.call,
+              relevance: tool.relevance,
+              role: tool.role,
+            })),
+            needsAnyTool: route.needsAnyTool,
+            workflowShape: route.workflowShape,
+            needsCheckpoint: route.needsCheckpoint,
+          },
+        };
+      } catch (error) {
+        const active = pi.getActiveTools();
+        if (!active.includes("codemcp_search")) {
+          pi.setActiveTools([...active, "codemcp_search"]);
+        }
+        throw error;
+      }
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("Jev MCP Route")), 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("warning", "Jev is routing..."), 0, 0);
+      if (expanded) return renderExpandedJson(result.content);
+      const details = result.details as
+        | { selected?: Array<{ call?: string }>; workflowShape?: string }
+        | undefined;
+      const selected = details?.selected ?? [];
+      let text = theme.fg(
+        "success",
+        `\n${selected.length} calls · ${details?.workflowShape ?? "no workflow"}`,
+      );
+      for (const tool of selected.slice(0, 4)) {
+        if (tool.call) text += `\n${theme.fg("dim", `  ${tool.call}`)}`;
+      }
+      text += `\n${theme.fg("muted", keyHint("app.tools.expand", "routing details"))}`;
+      return new Text(text, 0, 0);
+    },
+  });
+}
+
 export function registerCodeMcpTools(
   pi: ExtensionAPI,
   lifecycle: CodeMcpLifecycle,
@@ -330,6 +404,7 @@ export function registerCodeMcpTools(
           ...(params.inputRef === undefined ? {} : { input_ref: params.inputRef }),
         },
         signal,
+        (progress) => onUpdate?.(executionProgressUpdate(progress)),
       );
       return formatExecutionResponse(result, lifecycle);
     },
@@ -384,6 +459,7 @@ export function registerCodeMcpTools(
           trace_id: toolCallId,
         },
         signal,
+        (progress) => onUpdate?.(executionProgressUpdate(progress)),
       );
       return formatExecutionResponse(result, lifecycle);
     },
@@ -577,6 +653,17 @@ export function registerCodeMcpTools(
   });
 }
 
+function executionProgressUpdate(progress: SidecarProgress) {
+  const currentCall = progress.message === "executing" ? undefined : progress.message;
+  return {
+    content: [{ type: "text" as const, text: progress.message ?? "Executing MCP calls..." }],
+    details: {
+      callsMade: progress.progress,
+      ...(currentCall === undefined ? {} : { currentCall }),
+    },
+  };
+}
+
 function formatExecutionResponse(result: Record<string, unknown>, lifecycle: CodeMcpLifecycle) {
   const ok = result.ok === true;
   const modelValue = ok
@@ -636,6 +723,40 @@ function outputLimits(lifecycle: CodeMcpLifecycle): { maxBytes: number } {
   return { maxBytes: settings.outputLimitKiB * 1024 };
 }
 
+function currentRouteTask(entries: readonly unknown[]): {
+  task: string;
+  recentContext: string;
+} {
+  const messages: Array<{ role: "user" | "assistant"; text: string }> = [];
+  for (const entry of entries) {
+    if (!isRecord(entry) || !isRecord(entry.message)) continue;
+    const role = entry.message.role;
+    if (role !== "user" && role !== "assistant") continue;
+    const text = messageText(entry.message.content).trim();
+    if (text) messages.push({ role, text });
+  }
+  let currentIndex = messages.length - 1;
+  while (currentIndex >= 0 && messages[currentIndex]?.role !== "user") currentIndex -= 1;
+  const current = messages[currentIndex];
+  if (!current) throw new Error("Jev routing requires a text user request");
+  const recentContext = messages
+    .slice(Math.max(0, currentIndex - 3), currentIndex)
+    .map((message) => `${message.role === "user" ? "User" : "Assistant"}: ${message.text}`)
+    .join("\n\n")
+    .slice(-6_000);
+  return { task: current.text, recentContext };
+}
+
+function messageText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .flatMap((item) =>
+      isRecord(item) && item.type === "text" && typeof item.text === "string" ? [item.text] : [],
+    )
+    .join("\n");
+}
+
 function truncate(value: string, maxLength: number): string {
   return value.length <= maxLength ? value : `${value.slice(0, maxLength - 1)}…`;
 }