Skip to content

chrismarchant/jev-router

v0.1.0MIT

Route parallel-workstream decisions to TypeSafe's Jev System One model (speculative fan-out, routing, review, batch triage, Box image localization) via a bundled zero-dependency MCP server plus a CLI. Works in Mistral Vibe and any Agent Plugins 1.0 harness.

jev-router

An agent- and harness-agnostic router that opens up parallel workstreams whose decisions are offloaded to TypeSafe's Jev System One model (POST https://api.typesafe.ai/v1/systemone) β€” using its speculative fan-out pattern (many typed questions answered in parallel in one request, https://docs.typesafe.ai/patterns/fan-out) and its Box primitive for image localization (https://docs.typesafe.ai/primitives/box).

Jev is a System One decision model, not a chat LLM: it does not write code or prose. It takes a state plus typed questions (noul / choice / score / box) and returns structured answers β€” probabilities, choices, scores, bounding boxes β€” that your code branches on. So this router offloads the routing, triage, prioritization, conflict detection and verification of parallel workstreams to Jev, while your agent (Claude Code, Mistral Vibe, Codex, …) still executes the work itself. Same spirit as chrismarchant/mistral-code-router, but for decision offload instead of generation offload.

Zero dependencies (Node β‰₯ 18 standard library only). MIT licensed.

Documentation

PageContents
docs/installation.mdInstall in Mistral Vibe, Claude Code, Codex/skills.sh, any MCP client, or plain CLI
docs/architecture.mdRepo layout, data flow, MCP transport, retries, plugin packaging
docs/tools.mdReference for all 9 jev_* MCP tools / CLI commands (args, returns, examples)
docs/cli.mdCLI commands, flags, @file convention, exit codes
docs/configuration.mdEvery environment variable
docs/primitives.mdHow the router uses noul / choice / score / box (+ structured questions)
docs/patterns.mdTypeSafe patterns β†’ where each is implemented in the router
docs/confidence-and-thresholds.mdHow confidence works, noul bands, probability vs confidence, the router's thresholds
docs/limitations.mdJev's limits (AI primer, model jaggedness, model limits) and how they are encoded
docs/examples.mdEnd-to-end walkthroughs with sample output
docs/development.mdTests, scripts/verify.sh, committing/releasing

Quick start

# 1. key (https://console.typesafe.ai/keys, or the Vercel AI gateway)
export TYPESAFE_API_KEY=...

# 2. run from a checkout of this repo (no npm install needed β€” zero deps)
node bin/jev-router.js models

# 3. plan parallel workstreams for a task β€” ONE fan-out request to Jev
node bin/jev-router.js plan \
  --task @examples/task.txt \
  --candidates @examples/plan-candidates.json \
  --files '["src/server.js"]'

Or install it into your agent β€” see docs/installation.md β€” and call the jev_* MCP tools directly.

The 60-second mental model

  1. Fan-out by default. Every question that shares a state goes in one request; Jev evaluates them all in parallel (no question-count limit β€” only context limits), and your code keeps the answers it needs. jev_plan_workstreams and jev_fan_out do this for you; jev_batch is for items that each have their own state.
  2. Jev decides, you execute. Jev never generates text, does math, or compares dates β€” closed option sets are drafted by a small LLM (jev_draft_options, default mistral-small-latest) and Jev only picks; arithmetic/ordering happens in your code.
  3. Threshold responsibly. Nouls: >0.7 yes, <0.3 no, between = its own outcome. Choices: threshold the probability of the option you'll act on; use confidence only to decide whether to act at all (below ~0.5, escalate). See docs/confidence-and-thresholds.md.

Tools at a glance

MCP toolCLIOne-liner
jev_modelsmodelsList available Jev models + limits
jev_askaskOne POST /v1/systemone: state + typed questions β†’ answers
jev_fan_outfan-outMany questions in ONE request (default mode) + optional confidence discard
jev_plan_workstreamsplanDecompose a task into scored/routed parallel workstreams (one fan-out request)
jev_routerouteRoute an item: choice + companion noul + probability threshold + confidence floor
jev_reviewreviewVerify an output against acceptance criteria (three-band nouls)
jev_batchbatchMany items with their own states, parallel bounded pool
jev_boxboxLocate something in an image (Box + present noul; Jev 1.14+)
jev_draft_optionsdraft-optionsDraft closed option sets with mistral-small-latest (Jev only picks)

Full reference: docs/tools.md.

Guardrails

  • Never send secrets β€” API keys stay in the environment, never in state/questions/draft prompts.
  • Keep state lean (Jev suffers context rot); request bodies ≀ 32 MiB, nesting ≀ 64.
  • 401 β†’ bad key; 422 β†’ malformed question (error names the field); 429/529/5xx β†’ auto-retried with backoff.
  • On tool failure inside an agent loop: retry once, then decide locally β€” never block the workstream.

Development

node --test test/*.test.js   # 36 tests against mock APIs (no keys needed)
bash scripts/verify.sh       # syntax + MCP handshake + tools/list + missing-key + optional live test

See docs/development.md.

License

MIT β€” see LICENSE.