use-jev

use-jev

Servidor MCP e CLI que expõem a API System One da TypeSafe (modelo: Jev) para qualquer agente compatível com MCP — com escalonamento, um portão de ação e quatro backends intercambiáveis.

Jev não é um modelo de chat ou código, e não pode alimentar um agente de codificação. Ele recebe um state mais perguntas tipadas e retorna respostas tipadas com probabilidades calibradas. Veja docs.typesafe.ai.

É uma vitória de RATE, não de tokens. Jev gasta mais tokens por decisão do que um LLM gastaria, a um preço por token muito menor e em algumas centenas de milissegundos. A economia é real apenas quando a decisão sai da conversa — um hook, ou um script canalizando um arquivo para o CLI. Dados colados no jev_ask atravessam seu contexto duas vezes: uma vez como entrada da ferramenta, outra nos veredictos que voltam.

Instalação

npx -y @silkyland/use-jev install     # or, from a clone: npm install && node cli.mjs install

Quer apenas a habilidade de roteamento, sem o servidor? O skills CLI lê este repositório diretamente:

npx -y skills add silkyland/use-jev

install detecta os agentes presentes na máquina, escreve uma entrada MCP para cada um, vincula a habilidade de roteamento incluída e faz backup de cada arquivo que toca. Ele nunca escreve uma credencial. Adicione --dry-run para ver o plano primeiro, --agent claude-code,codex para restringi-lo, ou --no-skills para conectar apenas as ferramentas. uninstall reverte isso.

Cada caminho é resolvido em tempo de execução — a localização do próprio pacote, e um node no PATH cuja versão corresponde à que está rodando (para que uma atualização via Homebrew não quebre a entrada que ele escreveu). Nada é codificado, então um clone funciona onde quer que você o coloque.

Depois, dê a ele uma credencial e verifique:

export TYPESAFE_API_KEY=...     # or OPENROUTER_API_KEY, or AI_GATEWAY_API_KEY
npx -y @silkyland/use-jev doctor

Prefira um arquivo se quiser uma credencial para todos os agentes, já que ele é lido por qualquer agente que inicie o servidor:

mkdir -p ~/.use-jev && cat > ~/.use-jev/config.json <<'JSON'
{ "backend": "auto", "apiKey": "PUT-YOUR-TYPESAFE-KEY-HERE" }
JSON
chmod 600 ~/.use-jev/config.json

config.example.json neste pacote lista cada campo. Preencha apenas os provedores que você usa. baseUrl é uma origem (uma /v1 final é tolerada).

Execuções sem cabeça precisam de uma regra de permissão. Nenhum modo de permissão permite automaticamente uma ferramenta MCP, então uma execução não interativa não tem ninguém para perguntar e a chamada é recusada. Adicione às configurações do seu agente:

{ "permissions": { "allow": ["mcp__use-jev"] } }

Nada aqui escreve essa regra por você: pré-autorizar uma ferramenta que envia seu estado a um terceiro é sua decisão.

Ferramentas

Ferramenta	O que faz
jev_ask	Principal. Um estado, muitas perguntas tipadas, uma chamada. Um veredicto por pergunta.
jev_noul	Uma pergunta sim/não → probabilidade de sim (0–1).
jev_choice	Escolha uma opção de um conjunto → escolha + probabilidades por opção + confiança.
jev_score	Avalie em níveis ordenados → pontuação ponderada + legenda + probabilidades + confiança.
jev_gate	Verificação de risco de UMA ação proposta → allow / deny / ask.
jev_route	Local e gratuito: este passo é do Jev, ou estruturalmente do LLM?
jev_models	Liste os modelos que o backend ativo aceita.
jev_status	Backend ativo, fonte de credencial, estado de cada provedor. Nunca retorna uma chave.
jev_howto	Orientação de design e roteamento para agentes sem a habilidade instalada.

Veredictos e escalonamento

Cada pergunta recebe um veredicto, mesmo aquela que nunca chegou ao provedor. escalate: true significa que é seu para assumir — e a resposta ainda está lá, como um prior que vale a pena ler.

reason	Significado
writing	O passo deve produzir novo conteúdo. Estruturalmente do LLM.
open_ended	As opções não podem ser enumeradas, ou a pergunta está malformada. Capturado antes de qualquer chamada.
oversized	O estado tem mais de ~30k tokens. Encolha ou divida. Capturado antes de qualquer chamada.
malformed	O provedor respondeu, mas não em um formato que pudéssemos ler para esta pergunta. O resto do lote não é afetado.
unsure	Respondido abaixo do limite de confiança. Trate a resposta como uma dica.
unreachable	O provedor falhou. Prossiga como se o Jev não existisse.

writing é produzido por jev_route, não por um veredicto — um passo que deve escrever é roteado para fora antes de qualquer chamada ser feita, então judge nunca o retorna.

Uma resposta ruim custa uma pergunta, não o lote. A API é chamada com todas as perguntas em uma única solicitação, então uma única resposta ilegível derrubaria o lote inteiro — o que puniria exatamente o agrupamento que esta ferramenta existe para incentivar. As três razões que significam nenhum julgamento foi produzido (oversized, malformed, unreachable) são exportadas como NO_JUDGMENT_REASONS; um portão deve falhar aberto em todas as três.

confidenceFrom diz de onde veio o número, e os dois escalam abaixo de limites diferentes: reported é a própria cabeça do Jev (escolha/pontuação apenas, limite 0.5), estimated é a margem entre o primeiro e o segundo colocado (limite 0.4, porque lê mais baixo uma vez que a massa perdedora se divide entre três ou mais opções). Ambos são calibração do jev-use — reajuste-os com seus próprios dados via --threshold, JEV_CONFIDENCE_THRESHOLD, ou confidenceThreshold na configuração.

A armadilha que vale conhecer

As probabilidades de escolha sempre somam 1, então algo sempre fica em primeiro — mesmo quando nada se encaixa. Sempre que "nenhuma dessas" for possível, combine a escolha com um noul de presença na mesma chamada e leia isso primeiro, ou dê à escolha uma opção explícita de none.

Backends

Backend	Endpoint	Credencial
typesafe	POST api.typesafe.ai/v1/systemone	TYPESAFE_API_KEY / JEV_API_KEY
openrouter	POST openrouter.ai/api/alpha/decisions (alfa — o caminho pode mudar)	OPENROUTER_API_KEY
vercel	POST ai-gateway.vercel.sh/v4/ai/evaluation-model	AI_GATEWAY_API_KEY
mock	nenhum — local, determinístico, respostas sem sentido	nenhuma

JEV_BACKEND escolhe um; não definido significa auto, pegando a primeira credencial encontrada na ordem typesafe → openrouter → vercel. JEV_BACKEND=mock executa todo o pipeline offline, que é como a suíte de testes cobre triagem, escalonamento, o portão e o CLI sem uma chave.

Apenas o caminho typesafe é verificado aqui contra respostas ao vivo. Os outros dois são implementados a partir da documentação do jev-use sobre eles.

CLI

use-jev install [--dry-run] [--agent a,b] [--no-skills]   # wire detected agents
use-jev uninstall [--dry-run]
use-jev doctor                                            # what is configured, and does it work
use-jev judge --questions-file q.json [--state-file f]    # or pipe the state on stdin
use-jev hook-config                                       # print the PreToolUse fragment
use-jev gate --hook                                       # the hook itself
use-jev serve                                             # the MCP server on stdio

judge é o caminho para dados já em um arquivo: os itens nunca entram no contexto de um agente. Ele sai com 0 quando todos os veredictos permanecem e 3 quando qualquer um escalou, então um script pode ramificar com base nisso.

q.json é um mapa de id da pergunta → pergunta, na própria forma da TypeSafe:

{
  "failed":   { "type": "noul",   "instructions": "Did the run fail?" },
  "next":     { "type": "choice", "instructions": "What should happen next?",
                "criteria": { "retry": "Looks flaky", "investigate": "A real failure" } },
  "severity": { "type": "score",  "instructions": "How bad is it?",
                "criteria": ["Cosmetic", "Blocks one user", "Blocks everyone"] }
}

O portão de zero tokens

use-jev hook-config imprime um fragmento de configurações para um hook PreToolUse do Claude Code, com os caminhos desta instalação preenchidos. Mescle sua chave hooks nas suas configurações.

Ele apenas apertam: deny → negar com uma razão, incerto → perguntar, allow → nenhuma saída para que seu fluxo de permissão normal decida. Cada falha — entrada ruim, sem credencial, provedor fora do ar, um estado que recusamos enviar, uma resposta que não pudemos ler — falha aberto, porque um sidecar de julgamento fora do ar nunca deve bloquear o agente. "Falhar aberto" significa silêncio mais uma linha no stderr: um portão que responde ask quando ninguém pode respondê-lo recusa a chamada, o que é um bloqueio.

A entrada da ferramenta é cortada antes de ser enviada (DEFAULT_GATE_MAX_INPUT_CHARS, 4000). Um Write de um arquivo de 200 kB é um evento de hook, e o portão precisa da forma da ação, não do seu payload.

Ele deliberadamente não é habilitado por install: ele envia uma descrição de cada chamada de ferramenta correspondida ao seu provedor configurado.

• JEV_GATE_THRESHOLD — mais alto envia mais ações para revisão.
• JEV_GATE_STATE — um evento de hook carrega apenas o cwd e o modo de permissão; qualquer outra coisa que mude a resposta ("credenciais de produção estão presentes") vai aqui, anexada a cada estado.

Verificação

npm test     # or: node smoke.mjs

Quatro fases como um cliente MCP real sobre stdio. As três primeiras não precisam de credencial — o backend mock executa todo o pipeline localmente, cobrindo veredictos, escalonamento, triagem, o portão, o helper de rota, resolução de caminhos e cada caminho do CLI incluindo o contrato de hook. A quarta usa sua configuração real e faz chamadas ao vivo, ou diz claramente por que pulou.

Layout

Arquivo	Função
index.mjs	O servidor MCP e suas nove ferramentas
cli.mjs	install, uninstall, hook-config, doctor, judge, gate --hook, serve
lib/paths.mjs	Caminho em tempo de execução e resolução do Node — a razão de nada ser codificado
lib/install.mjs	O registro de agentes e os escritores de configuração
lib/protocol.mjs	Validação de perguntas, limites, aritmética de confiança, roteamento local
lib/backends.mjs	Adaptadores typesafe / openrouter / vercel / mock, retry e backoff
lib/config.mjs	Resolução de backend e credencial
lib/judge.mjs	triagem → chamada → portão de confiança → veredictos; gate
skills/use-jev/SKILL.md	As regras de roteamento que um agente deve seguir

Dependências: @modelcontextprotocol/sdk, zod. Provedores são chamados com fetch puro, então nenhum SDK de fornecedor é fixado.

Créditos

O contrato de escalonamento, os dois limites de confiança calibrados, o roteamento determinístico pré-chamada, o portão de ação e as regras de hook de apenas-apertar / falhar-aberto são adaptados de jev-use (MIT) — assim como os formatos de wire do OpenRouter e Vercel, que não estão na própria documentação da TypeSafe. Nenhum código foi copiado; as implementações aqui são independentes. Veja NOTICE.

Esse projeto é o mais completo. Se você quer algo mantido, com benchmarks e publicado no npm, em vez de algo pequeno que você possui e edita, use-o. Isto existe para manter uma credencial para cada agente, expor fielmente os primitivos brutos e permanecer curto o suficiente para ler de uma vez.

TypeSafe, System One e Jev são produtos da TypeSafe AI. Este projeto é um cliente não afiliado.

Licença

MIT — veja LICENSE.