Jev Tool Routing¶

Open the TUI setup route with :connect jev.

Jev Tool Routing reduces the tool-schema context sent to coding models. It asks TypeSafe AI's Jev which tools a request is likely to need, applies SuperQode's safety rules, and keeps one stable selection for the complete turn.

The coding model still writes every command, path, patch, and tool argument. The harness still owns permissions and execution. Jev only selects tool definitions from a closed catalogue.

What problem it solves¶

Coding harnesses commonly send every available tool definition on every model call. Names, descriptions, JSON schemas, enums, examples, and provider metadata can consume thousands of input tokens even when a turn needs only repository reads and a test command.

Jev is a structured decision model rather than a chat model. SuperQode presents the task and bounded tool choices to Jev once, then applies a threshold, protected-tool floor, and dependency rules. The catalogue remains unchanged across later steps in the turn, preserving a stable prefix for provider caching.

flowchart LR
    A[User request] --> B[Harness tool catalogue]
    B --> C[Jev closed-set decision]
    C --> D[Threshold and safety floor]
    D --> E[Stable catalogue for the turn]
    E --> F[Coding model]
    F --> G[Harness permission check]
    G --> H[Tool execution]
    C -. timeout or error .-> I[Full catalogue]
    I --> F

Jev never receives authority to execute a tool. A timeout, transport error, incomplete answer, or empty selection returns the complete catalogue.

Quick start¶

Install SuperQode and provide a TypeSafe key:

uv tool install superqode==2.4.10
export TYPESAFE_API_KEY="..."

Inspect the machine, test Jev connectivity, and verify an adapter without calling its coding model:

superqode optimize doctor
superqode optimize setup
superqode optimize verify opencode

Run OpenCode in the default shadow mode:

export GEMINI_API_KEY="..."
superqode optimize run opencode \
  --provider google \
  --model gemini-3.8-flash -- \
  run "review this repository"

The command starts a loopback gateway, injects a process-scoped endpoint override, launches the original harness, prints aggregate routing metrics, and removes temporary state. It does not rewrite persistent harness configuration.

After reviewing the shadow result, apply the selection:

superqode optimize run opencode \
  --provider google \
  --model gemini-3.8-flash \
  --mode enforce -- \
  run "review this repository"

Shadow and enforce modes¶

The default keep threshold is 0.30. A higher value removes more candidates and needs stronger evaluation. A lower value is more conservative. Protected workspace tools and dependency rules take precedence over the threshold.

Supported harnesses¶

gateway-limited means model traffic is visible while tool definitions are absent from the client request. detect-only means SuperQode can identify the installation but cannot safely intercept model traffic. Neither state is presented as a saving.

Harness recipes¶

Pass harness-native arguments after --.

export TYPESAFE_API_KEY="..."
export GEMINI_API_KEY="..."
superqode optimize run opencode \
  --provider google --model gemini-3.8-flash -- \
  run "fix the failing tests"

export TYPESAFE_API_KEY="..."
export ANTHROPIC_API_KEY="..."
superqode optimize run claude --provider anthropic -- \
  --print --no-session-persistence "review this repository"

export TYPESAFE_API_KEY="..."
export XAI_API_KEY="..."
superqode optimize run grok --provider xai -- \
  --single "review this repository"

export TYPESAFE_API_KEY="..."
export GEMINI_API_KEY="..."
superqode optimize run pi \
  --provider google --model gemini-3.8-flash -- \
  --print "review this repository"

export TYPESAFE_API_KEY="..."
export SUPERQODE_TOOL_ROUTING=shadow
superqode

Managed launchers¶

Create separate *-jev commands after validating the routes:

superqode optimize enable opencode claude grok pi
superqode optimize status
opencode-jev run "review this repository"

The original vendor commands remain unchanged. Preferences contain provider, model, mode, threshold, and launcher location; credentials remain in the environment. Remove selected or all managed launchers with:

superqode optimize disable opencode
superqode optimize uninstall

A launcher is removed only when it still carries SuperQode's management marker, protecting a user-owned replacement at the same path.

Environment variables¶

Credentials¶

Provider and harness processes inherit the launching shell environment. Temporary OpenCode and Pi configuration uses a non-secret loopback placeholder; provider credentials are never serialized into those generated files.

Routing controls¶

Command options such as --mode, --threshold, --model, --provider, and --port configure one managed run. Native-loop variables apply when SuperQode owns the model loop. See the central environment-variable reference.

Python SDK¶

Python harnesses can route in-process:

from superqode.jev_tools import JevToolRouting

router = JevToolRouting(mode="enforce", threshold=0.30, timeout_ms=1500)
result = await router.route(
    "Review this repository and run its tests",
    tool_catalogue,
    turn_id="turn-123",
)
model_tools = list(result.tools)

Create one router per process and reuse turn_id across every model step in one user turn. RoutingResult includes selected objects, counts, dropped names, schema bytes, mode, status, latency, and cache status.

For a remote service:

from superqode.jev_tools import JevToolRoutingClient

client = JevToolRoutingClient(
    "https://jev.superqode.dev",
    token="service-token",
)
result = await client.route(
    "Fix the failing parser test",
    tool_catalogue,
    turn_id="turn-123",
    mode="enforce",
    threshold=0.30,
)

HTTP and MCP service¶

Start the reusable service locally:

export TYPESAFE_API_KEY="..."
superqode serve jev

The HTTP request contains request, tools, turn_id, mode, and threshold. The response returns preserved selected objects, counts, dropped names, status, latency, cache status, and schema-byte counts.

Non-loopback binds require --allow-remote and SUPERQODE_JEV_SERVICE_TOKEN. Every endpoint except /healthz then requires Authorization: Bearer <token>.

The public deployment is jev.superqode.dev. The complete Cloud Run procedure is in deploy/jev/README.md.

Safety and data handling¶

• Routing fails open: errors preserve the full catalogue.
• Core workspace tools can remain protected regardless of probability.
• One decision is cached in memory for a stable turn_id.
• The router returns definitions and never executes tools.
• The harness retains its permission and sandbox policy.
• The service stores no prompts, definitions, credentials, or decisions on disk.
• Aggregate gateway reports exclude prompts, arguments, bodies, and credentials.
• Cloud instances can restart, so callers must accept a safe repeated decision.

Benchmark results¶

The snapshot used SuperQode 2.4.10 and threshold 0.30. Grok Build, Claude Code, and OpenCode ran the calculator task twice per mode in alternating order. Every included run returned two passing tests and add(19, 23) = 42.

OpenCode shows why schema reduction and end-to-end cost are separate measures: one enforce repetition added a model step, leaving cost effectively flat. This small sample establishes integration behavior; it is not a distribution.

The coding-model-free labelled evaluation produced:

The Cloud Run service selected the same sets with 556ms average server-reported latency. Pi remained 4 → 4. Codex completed the task, while zero client-visible definitions made the route gateway-limited. Antigravity remained detect-only.

Read the measurement definitions, caveats, and complete reproduction procedure. The exact fixture is committed under examples/bench/jev-tool-routing.

Command map¶

See the complete CLI reference for arguments, output fields, and benchmark commands.

Troubleshooting¶

Use superqode optimize status for launchers, superqode optimize env HARNESS --json for a launch plan, and superqode optimize run to verify actual harness traffic.

Related documentation¶

• CLI and benchmark reproduction
• HTTP gateway and service commands
• SystemOne typed decisions
• Progressive Tool Discovery
• SystemOne Tune
• Environment variables