pi-codemcp 1.4.0 → 1.5.1

package/README.md

@@ -1,94 +1,71 @@
 # pi-codemcp
 
-Fast, typed, sandboxed **Code Mode for every MCP server configured in Pi**.
+> [!IMPORTANT]
+> **Something failed? Please open an issue.**
+>
+> Please do not assume your failure is too specific or not worth reporting. Platform differences, strange schemas, slow startup, confusing rendering, OAuth problems, and rough edges are exactly the reports that make this project better.
+>
+> Open an issue at <https://github.com/yolonir/pi-codemcp/issues>, or use **Extension is broken!** in `/codemcp` → Settings to ask the agent to investigate and prepare one.
+>
+> You can ask your coding agent to do the work:
+>
+> ```text
+> Reproduce this pi-codemcp problem, redact all credentials and private data,
+> collect the pi-codemcp version, Pi version, OS/architecture, MCP transport,
+> minimal configuration shape, exact error, and relevant logs, then open a
+> GitHub issue at https://github.com/yolonir/pi-codemcp/issues.
+> ```
+>
+> If the agent cannot create the issue, ask it to prepare the title and body for you. I would much rather receive an incomplete report than have someone hit a problem, abandon the package, and never say anything. I will read the issues and work through them.
+
+Typed, sandboxed **Code Mode for your MCP servers in Pi**.
+
+The agent discovers the tools it needs, writes a Python program, and runs dependent or parallel calls across MCP servers. Intermediate data stays in the sandbox; only the program's compact return value goes back to the model.
 
-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.
-- `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.
-- `codemcp_save_chain` turns a repeated call graph into a reusable native Pi tool.
-- `codemcp_manage_chains` lists chains or performs an explicitly confirmed enable, disable, revalidate, or delete.
-
-Intermediate results stay inside the sandbox. The model receives only the compact value returned by the program.
-
-## Why Code Mode?
-
-MCP has an uncomfortable scaling property: the more tools an agent can use, the more tool schemas compete with the actual task for context. Multi-step work also tends to bounce every intermediate result through the model, adding tokens, latency, and opportunities for mistakes.
-
-Cloudflare described a better pattern in [Code Mode: give agents an entire API in 1,000 tokens](https://blog.cloudflare.com/code-mode-mcp/): expose a small search-and-execute surface, let the model write code against a typed SDK, and execute that code in a sandbox. Their work reports a fixed tool footprint and dramatic context savings for very large APIs. The open-source implementation lives in [`@cloudflare/codemode`](https://github.com/cloudflare/agents/tree/main/packages/codemode).
-
-pi-codemcp applies that idea on the **client side** to the MCP servers you already use in Pi:
-
-1. Search the combined catalog or page through a compact inventory.
-2. Inspect exact schemas only for the calls selected for the task.
-3. Type-check a compact Python plan before any upstream call happens.
-4. Execute dependent or parallel calls without model round-trips between them.
-5. Return only the final data the agent actually needs.
-6. Save stable plans as native tools and reuse them without rewriting the call graph.
-
-That can make complex MCP workflows faster and substantially more token-efficient. Exact savings depend on the servers, schemas, model, and task.
-
-## Built for daily use, not a demo
-
-I built this because I care a lot about software that is genuinely fast, efficient, and predictable enough to use every day. Too many AI extensions look good in a short demo but become slow, noisy, fragile, or effectively unusable in real work.
-
-pi-codemcp is deliberately opinionated about operational quality:
+## Install
 
-- Pi startup does not wait for Python or MCP servers.
-- Each upstream connection is lazy and independent. A dead connection is evicted after the original call fails; that call is never replayed, and the next explicit call reconnects.
-- Upstream failures include stable `kind`, `server`, `tool`, `retryable`, `status`, and `message` fields.
-- Tool catalogs are cached per server and invalidated independently.
-- Agent-written code is type-checked before execution.
-- Time, memory, call count, and output size are bounded.
-- Failures are explicit; there are no silent retries or compatibility fallbacks.
-- Tool output is compact by default and expands with Pi's normal `Ctrl+O` UI.
-- Bounded local telemetry uses fixed rollups rather than session event logs and appears in the `/codemcp` Stats tab.
+```bash
+pi install npm:pi-codemcp
+```
 
-There is always room to make it faster and more reliable. If something is not working well, please report it rather than silently giving up on the extension.
+Reads `<agent-dir>/mcp.json`. Supports stdio, Streamable HTTP, SSE, bearer authentication, and FastMCP-managed OAuth.
 
-## Saved MCP chains
+Open **`/codemcp`** to manage servers, individual tools, saved chains, settings, and usage stats. Changes are saved immediately. Tool output expands with Pi's normal `Ctrl+O`.
 
-Any successful MCP call graph can become a reusable tool with an explicit input and output JSON Schema.
+No separate Python, uv, Bun, or just installation is needed. The package bootstraps a locked Python 3.13 runtime on first use; this needs network access unless already cached. Pi startup does not wait for MCP connections.
 
-A saved chain is exposed in two forms from one manifest:
+## How it works
 
 ```text
-mcp_chain_weekly_digest(...)   # native Pi tool
-chains.weekly_digest(...)      # typed call inside Code Mode
+Discover tools → load selected contracts → execute a program → return compact data
 ```
 
-Chains can call upstream MCP tools, other saved chains, or themselves recursively. This enables reusable composition such as:
+| Tool | Purpose |
+| --- | --- |
+| `codemcp_search` | Search capabilities or browse the compact catalog. |
+| `codemcp_route` | Optional Jev routing: select tools, roles, and composition guidance. |
+| `codemcp_inspect` | Load exact typed SDK contracts for selected calls. |
+| `codemcp_execute` | Type-check and run a sandboxed Python program. |
+| `codemcp_edit` | Patch the previous program and rerun it. |
+| `codemcp_save_chain` | Save a tested program as a reusable tool, with user approval. |
+| `codemcp_manage_chains` | List chains; explicitly confirm enable, disable, revalidate, or delete. |
 
-```python
-issues = await chains.collect_open_issues({"assignee": input["assignee"]})
-result = await slack.post_message({
-    "channel": input["channel"],
-    "text": issues["summary"],
-})
-return {"posted": result["ok"], "count": issues["count"]}
-```
+Independent calls can use `asyncio.gather`; dependent calls pass earlier outputs into later inputs. Filtering and aggregation happen inside the sandbox, without model round trips for every intermediate result.
 
-Nested chains share the same deadline, cancellation signal, catalog snapshot, and total call budget. Every nested input and output is runtime-validated. Recursion is supported but bounded. Dependency fingerprints mark chains stale when a referenced contract changes.
+## Optional Jev routing
 
-New manifests default to project scope under `<project>/.pi/pi-codemcp/chains`; explicitly global chains live under `<agent-dir>/pi-codemcp/chains`. A project chain overrides a same-named global chain without deleting it. Manifests contain sandboxed code and schemas, never credentials or execution results. `/codemcp` labels both scopes and can revalidate, enable, disable, or delete chains.
+Provide `TYPESAFE_API_KEY`, then set **Enable Jev → true** in `/codemcp` → Settings. This replaces `codemcp_search` with `codemcp_route` as the agent's discovery tool.
 
-There is deliberately no implicit “save last execution” state: the agent must submit the exact successfully tested code plus explicit input and output contracts. This keeps persistence reviewable and avoids saving the wrong attempt from a long session.
+1. The agent calls `codemcp_route` with a short `intent`, such as “read staging logs to diagnose the approval error.” The extension includes the original user request and up to three preceding user/assistant messages as context. A changed subtask can be routed again with a new intent.
+2. Enabled tool names and descriptions go to Jev in parallel chunks of up to 40. Jev scores relevance to that subtask (including prerequisites), assigns workflow roles, and checks whether an intermediate model decision or user approval is needed.
+3. CodeMCP ranks and filters the answers, selects at most eight tools, derives composition guidance, and fetches their exact typed contracts.
+4. The agent writes the actual `codemcp_execute` program, keeping a checkpoint between stages when needed.
 
-## Install
-
-```bash
-pi install npm:pi-codemcp
-```
-
-It reads Pi's existing `<agent-dir>/mcp.json` and supports stdio, Streamable HTTP, SSE, bearer authentication, and FastMCP-managed OAuth. Open `/codemcp` to manage servers, per-tool policy, saved chains, cache, and execution limits.
+Jev does not execute tools or block ordinary messages. **Routing sends the intent, your request, recent context, and tool descriptions to TypeSafe**, so it is opt-in. Without a key, local search stays active; a failed route enables search as a fallback. The SDK also honors `TYPESAFE_BASE_URL` and `TYPESAFE_DEFAULT_MODEL`.
 
-Package users do not need Python, uv, Bun, or just. A pinned uv binary bootstraps the locked Python 3.13 runtime under Pi's writable agent directory on first use; the first bootstrap needs network access unless already cached.
+## MCP configuration
 
-## MCP configuration examples
-
-`pi-codemcp` reads the same MCP config Pi uses. Either shape is accepted:
+Use an `mcpServers` object or a root-level server map:
 
 ```json
 {
@@ -96,43 +73,29 @@ Package users do not need Python, uv, Bun, or just. A pinned uv binary bootstrap
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.linear.app/mcp",
+      "auth": "oauth"
     }
   }
 }
 ```
 
-or a root server map:
-
-```json
-{
-  "linear": {
-    "type": "http",
-    "url": "https://mcp.linear.app/mcp",
-    "auth": "oauth"
-  },
-  "grafana": {
-    "type": "sse",
-    "url": "https://grafana.example.com/sse",
-    "headers": {
-      "authorization": "Bearer ${GRAFANA_MCP_TOKEN}"
-    }
-  },
-  "disabled-example": {
-    "command": "example-server",
-    "disabled": true
-  }
-}
-```
+Set `disabled: true` or `enabled: false` to disable a server. For stdio, only a safe base environment, comma-separated variables in `MY_PI_CHILD_ENV_ALLOWLIST` / `MY_PI_MCP_ENV_ALLOWLIST`, and explicit server `env` values are passed through. Remote `headers` can reference allowed environment variables with `${NAME}`.
 
-For stdio servers, pi-codemcp passes a small safe base environment plus variables listed in `MY_PI_CHILD_ENV_ALLOWLIST` or `MY_PI_MCP_ENV_ALLOWLIST`. Explicit `env` values in `mcp.json` are also passed. Remote headers can reference allowed environment variables with `${NAME}`. Pi-only fields such as `directTools`, `lifecycle`, `idleTimeout`, `enabled`, and `disabled` are understood locally and are not forwarded to FastMCP.
+## Settings
 
-## Settings JSON
+Edit settings in `/codemcp` or `<agent-dir>/pi-codemcp/settings.json`. Defaults: 30-second execution and tool timeouts, 50 upstream calls, 16 KiB returned data, 50 KiB rendered output, and a 24-hour catalog cache.
 
-Settings live at `<agent-dir>/pi-codemcp/settings.json` and can also be edited in `/codemcp`:
+<details>
+<summary>Settings JSON</summary>
 
 ```json
 {
   "version": 2,
+  "jevEnabled": false,
   "backgroundWarmup": true,
   "cacheTtlHours": 24,
   "executionTimeoutSeconds": 30,
@@ -146,135 +109,68 @@ 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.
-
-## 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.
-
-```python
-issues = await linear.list_issues({"assignee": "me", "limit": 50})
-return {"count": len(issues), "ids": [issue["identifier"] for issue in issues]}
-```
-
-The same flow is available through the internal CLI for debugging:
+Older settings are migrated on load, including `discoveryMode` → `jevEnabled`.
 
-```bash
-uv run --project sidecar --frozen -m sidecar.cli search "issues assigned to me"
-uv run --project sidecar --frozen -m sidecar.cli execute --code-file plan.py
-```
-
-A direct one-shot plan can call multiple servers without model round trips between calls:
+</details>
 
-```bash
-uv run --project sidecar --frozen -m sidecar.cli execute --code '
-number = await alpha.get_number({"seed": 41})
-saved = await beta.save_number({"value": number["value"]})
-return {"number": number["value"], "identifier": saved["identifier"]}
-'
-```
+## Saved chains
 
-Incomplete upstream schemas become recursive `JsonValue`, not `Any`; use the prebound `expect_object`, `expect_list`, `expect_string`, and `expect_integer` helpers to narrow unknown values explicitly. For unfamiliar outputs, `inspect_json(value, samples=2, max_depth=3)` returns a byte-bounded structural summary, cardinality, field sizes, and samples; `samples` is limited to 1–3 and `max_depth` to 1–6 during preflight. The generated prelude documents the sandbox surface: use `import asyncio` with `asyncio.gather`; unavailable host or stdlib APIs are rejected. Preflight type errors happen before any upstream call is made, and oversized final results fail explicitly with the same actionable inspection data.
+With your approval, a successfully executed program can be saved with explicit input/output JSON Schemas. One manifest exposes both:
 
-When an oversized value fits the bounded in-memory refinement cache, the failure also returns an opaque `result_ref` and expiry. Pass that reference back as `inputRef` on one follow-up `codemcp_execute`; the retained JSON is exposed as `input`, so code can filter or aggregate it without repeating upstream calls. References expire after five minutes, are valid only in the originating sidecar, and are never persisted.
-
-For a small correction, `codemcp_edit` replaces one uniquely matching `oldText` with `newText` in the most recent execution and reruns it with the same `inputRef`. The state is in-memory and disappears when the sidecar restarts. The full call graph runs again, including upstream MCP calls.
-
-## Saved-chain CLI flow
-
-Saved chains are JSON manifests with sandboxed code plus explicit input/output JSON Schemas. Project-scoped chains live under `<project>/.pi/pi-codemcp/chains`; global chains live under `<agent-dir>/pi-codemcp/chains`.
-
-```bash
-uv run --project sidecar --frozen -m sidecar.cli chain save save_number \
-  --description "Fetch and save one generated number." \
-  --code 'number = await alpha.get_number({"seed": input["seed"]})
-return await beta.save_number({"value": number["value"]})' \
-  --input-schema '{"type":"object","properties":{"seed":{"type":"integer"}},"required":["seed"],"additionalProperties":false}' \
-  --output-schema '{"type":"object","properties":{"saved":{"type":"boolean"},"identifier":{"type":"string"}},"required":["saved","identifier"],"additionalProperties":false}'
-
-uv run --project sidecar --frozen -m sidecar.cli chain list
-uv run --project sidecar --frozen -m sidecar.cli chain run save_number --input '{"seed":41}'
-uv run --project sidecar --frozen -m sidecar.cli chain revalidate save_number --scope project
-uv run --project sidecar --frozen -m sidecar.cli chain delete save_number --scope project
+```text
+mcp_chain_weekly_digest(...)   # native Pi tool
+chains.weekly_digest(...)     # typed call inside another CodeMCP program
 ```
 
-Revalidation checks the saved code against the current enabled catalog. Deletion refuses to remove chains still referenced by other chains. Disabling a project chain does not fall back to a same-named global chain; project scope continues to shadow global scope until the project manifest is deleted.
-
-## Output and result normalization
+Chains can call MCP tools or other chains. Nested calls share time and call budgets; inputs and outputs are validated. Changed dependency contracts mark chains stale for revalidation.
 
-When an upstream tool declares an output schema, pi-codemcp requires `structuredContent`, validates it, dumps it back to JSON-compatible values, and preserves declared structured string fields as strings. FastMCP-wrapped `result` strings are intentionally unwrapped and parsed because those wrappers commonly carry JSON payloads as text. When no output schema exists, single text responses that look like JSON objects, arrays, `null`, `true`, or `false` are normalized into native JSON values; non-JSON text remains a string.
+- **Project:** `<project>/.pi/pi-codemcp/chains` (activated in trusted projects).
+- **Global:** `<agent-dir>/pi-codemcp/chains`, when explicitly requested.
 
-Execution results report explicit stages:
+Project chains override same-named global chains, even when disabled. Manifests store code and schemas, not credentials or execution results. Manage them through `/codemcp`.
 
-- `preflight`: code did not run and no upstream call was made.
-- `runtime`: the sandbox or an upstream call failed after execution started.
-- `timeout` / `cancelled`: execution was stopped.
-- `result`: the call graph completed, but the returned value exceeded `resultLimitKiB`.
+## Execution and safety
 
-Rendered Pi output is separately truncated by `outputLimitKiB`; the full oversized rendered value is not persisted.
+[FastMCP](https://github.com/jlowin/fastmcp) handles transports, validation, and OAuth. [Pydantic Monty](https://github.com/pydantic/monty) type-checks and executes Python without host filesystem, environment, network, or subprocess access. External access is only through the exposed MCP and saved-chain calls.
 
-## Safety and limits
+- Type errors stop execution **before any upstream call**. Time, memory, call count, and output size are bounded.
+- Enabled tools retain their upstream permissions. Chains cannot bypass server or per-tool policy.
+- No automatic call retries or cross-service rollback: a later failure does not undo earlier side effects.
+- `codemcp_edit` reruns the **whole program**, including upstream calls; it is not a continuation.
+- Unscoped search returns available results plus explicit `discovery_failures`; server-scoped search fails if that server is unavailable.
 
-FastMCP owns MCP transports, runtime validation, and OAuth. [Pydantic Monty](https://github.com/pydantic/monty) type-checks and executes agent-written Python without host filesystem, environment, network, or subprocess access. Code Mode can only call the typed MCP tool and saved-chain facades exposed in the generated stubs.
+<details>
+<summary>Working with unknown or oversized results</summary>
 
-`/codemcp` configures servers, saved chains, per-tool policy, timeouts, call limits, output limits, cache TTL, and warmup, and shows bounded lifetime/recent telemetry in its Stats tab. Server, chain, tool-policy, and setting changes are persisted immediately. Discovery, revalidation, and deletion remain explicit immediate actions. The sandbox also has a fixed memory ceiling; executions are serialized per Pi session. There are no automatic retries or cross-service rollback.
+Incomplete schemas use recursive `JsonValue`, not `Any`. Use the prebound `expect_object`, `expect_list`, `expect_string`, and `expect_integer` helpers to narrow values. `inspect_json(value, samples=2, max_depth=3)` returns a bounded structural summary.
 
-Enabled tools retain their upstream permissions. Saved chains never bypass server or per-tool policy and are checked against the current enabled catalog whenever they run. Preflight safety does not make upstream tools transactional: if a later call fails after earlier calls succeeded, pi-codemcp does not roll those upstream side effects back.
+Oversized results fail explicitly. If the value fits the in-memory refinement cache, the error includes a `result_ref`. Pass it as `inputRef` in a follow-up `codemcp_execute` to filter the retained value as `input` without repeating upstream calls. References expire after five minutes and are valid only in the originating sidecar.
 
-## Something failed? Please open an issue
+Failures distinguish `preflight`, `runtime`, `timeout`, `cancelled`, and oversized `result` stages. Rendered output has a separate `outputLimitKiB` cap.
 
-Please do not assume your failure is too specific or not worth reporting. Platform differences, strange schemas, slow startup, confusing rendering, OAuth problems, and rough edges are exactly the reports that make this project better.
+</details>
 
-Open an issue at <https://github.com/yolonir/pi-codemcp/issues>.
-
-You can ask your coding agent to do the work:
-
-```text
-Reproduce this pi-codemcp problem, redact all credentials and private data,
-collect the pi-codemcp version, Pi version, OS/architecture, MCP transport,
-minimal configuration shape, exact error, and relevant logs, then open a
-GitHub issue at https://github.com/yolonir/pi-codemcp/issues.
-```
-
-If the agent cannot create the issue, ask it to prepare the title and body for you. I would much rather receive an incomplete report than have someone hit a problem, abandon the package, and never say anything. I will read the issues and work through them.
-
-## Local development
-
-```bash
-just init
-just check
-just release-check
-```
-
-Development and packaged runtime checks target Python 3.13. The sidecar metadata, `.python-version`, mypy, ty, and CI all align on that version.
-
-To test the checkout without loading an installed copy:
+## Development
 
 ```bash
+just init           # locked dependencies and hooks
+just check          # locks, lint, types, and tests
+just release-check  # also verify the packed clean-install path
 pi -ne -e . --no-session
 ```
 
-The sidecar also has a stable internal CLI for development, debugging, and future runtime adapters:
+Uses Bun and uv with Python 3.13. For sidecar debugging:
 
 ```bash
-uv run --project sidecar --frozen -m sidecar.cli serve --stdio
-uv run --project sidecar --frozen -m sidecar.cli status --agent-dir ~/.pi/agent
+uv run --project sidecar --frozen -m sidecar.cli doctor --agent-dir ~/.pi/agent
 uv run --project sidecar --frozen -m sidecar.cli search "linear issues"
 uv run --project sidecar --frozen -m sidecar.cli execute --code-file plan.py
-uv run --project sidecar --frozen -m sidecar.cli chain list
-uv run --project sidecar --frozen -m sidecar.cli doctor --agent-dir ~/.pi/agent
 ```
 
-`just check` runs lockfile checks, TypeScript, Biome, Bun tests, Ruff, mypy, ty, and pytest. `just release-check` additionally packs the npm artifact, installs it into a clean consumer directory, and runs the packaged sidecar without a system uv on `PATH`.
-
-## Releases
-
-Release Please derives versions and release notes from Conventional Commit titles on `main`: `fix:` publishes a patch, `feat:` publishes a minor, and a `!` or `BREAKING CHANGE:` publishes a major. It maintains the release PR, `CHANGELOG.md`, `package.json`, version tag, and GitHub Release.
-
-Merging a release PR publishes the verified package to npm from `.github/workflows/release.yml` using trusted publishing and provenance. Quality gates the exact merge commit on Linux, macOS, and Windows; the publish job checks out its release tag, packs it with Bun, and uses npm only for the final OIDC-authenticated upload.
+Conventional Commit titles drive Release Please. Feature PRs do not publish; merging the release PR triggers the verified npm release.
 
 ## Credits
 
-The core search-and-execute philosophy is inspired by Cloudflare's Code Mode work. pi-codemcp is an independent implementation for Pi that composes arbitrary configured MCP servers through FastMCP and a Pydantic Monty sandbox.
+Inspired by [Cloudflare's Code Mode](https://blog.cloudflare.com/code-mode-mcp/). Independent implementation for Pi using FastMCP and Pydantic Monty.
 
 MIT

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.1",
   "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):