Skip to main content
Glama

universal-jev

Universal TypeSafe Jev Runtime Plugin, MCP Server & Autonomous Browser Engine for Coding Agents (Codex, Pi, DSH, OpenCode, Antigravity).


Core Capabilities

  1. Jev-Verified Receipt Extraction (95%+ Token Savings):

    • Evaluates lengthy terminal outputs (builds, tests, linters, game engine logs) using TypeSafe Jev System 1.

    • Dehydrates passing logs into high-confidence verified receipts ([Jev Verified Receipt ✓]) with 100% transparency to LLMs.

    • Isolates failure/error traces ([Jev Diagnostic Warning ⚠️]) while pruning routine output.

    • Triple Safety Barrier:

      • Unified Diff & Patch Immunity: Git diffs (diff --git, @@ ... @@) and patch outputs are strictly protected from pruning.

      • Exit-Code Fast-Path: Non-zero process exit codes immediately bypass LLM probabilistic guessing with 0ms latency and 100% deterministic diagnostic failure.

      • Smart Anchor Sampling & Middle Error Isolation: Automatically scans un-sampled intermediate log regions for errors (traceback, script error, exception), ensuring intermediate crashes (e.g. Godot/Blender/Cargo runs) are never concealed by normal trailing logs.

  2. Universal 2-Tier Browser Engine (jev-ultrafast × browser-use):

    • Tier 1 (jev-ultrafast): Sub-second indexed DOM decisions via TypeSafe Jev System 1 (zero vision LLM overhead).

    • Tier 2 (browser-use Fallback): Automatically falls back to full multimodal semantic snapshots and visual reasoning when encountering CAPTCHAs, complex canvas, or blocked states.

    • Zero User Disruption: Always creates a fresh, isolated Ego Lite TaskSpace, leaving your personal tabs untouched.

    • Instant Cleanup: Space is guaranteed to be closed and destroyed immediately upon task completion in a finally block.

  3. Verbatim Context Compaction & Auto Image Dehydration:

    • Compresses bloated conversation history while preserving user instructions 100% verbatim.

    • Automatically dehydrates images after 3 model turns, liberating up to 90% vision token budget.

  4. Fast Decision Primitives:

    • Millisecond multi-choice classification (Choice), boolean hypothesis probability (Noul), rubric evaluation (Score), and security guardrails (Guard).


Related MCP server: jev-mcp

Installation (初次安装)

Requires Node.js 20+.

git clone https://github.com/raj8525/universal-jev.git ~/.agents/plugins/universal-jev
cd ~/.agents/plugins/universal-jev
./install.sh

Set your API key (Official TypeSafe API or OpenRouter fallback):

# Official TypeSafe System 1 Endpoint (Recommended)
export TYPESAFE_API_KEY="apikey_..."

# Or OpenRouter Fallback:
export OPENROUTER_API_KEY="sk-or-v1-..."

Update & Upgrade (平滑更新)

对于已经安装过的用户,更新过程100% 平滑、幂等且无损:

方式 1:一键自动更新(推荐)

直接进入项目目录重新运行安装脚本:

cd ~/.agents/plugins/universal-jev && ./install.sh

为什么推荐直接运行 ./install.sh?

  • 自动拉取:脚本会自动检查并执行 git pull --ff-only 同步 GitHub 上的最新提交。

  • 配置幂等:脚本内置各 Agent 配置检测(OpenCode, Codex, Antigravity, Pi),绝不重复添加、不覆盖已有配置。

  • 符号软链接:全局命令(~/.local/bin/jev、universal-jev-mcp 等)是指向仓库源码的软链接,更新后立即指向最新代码。

  • 自动刷新 Schema:自动同步 Antigravity 最新的 MCP 工具定义(如 exitCode 参数)。

方式 2:极简 Git Pull

cd ~/.agents/plugins/universal-jev && git pull

由于 ~/.local/bin/ 下的指令均为软链接,执行 git pull 后代码立即更新生效。

🔄 各 Agent 生效与重启说明

Agent 客户端

生效方式

是否需要重启应用

Codex (GPT-6)

每次运行命令独立调用 In-Flight Hook (codex-hook.js)

无需重启! 下一次在终端执行命令即自动应用最新补丁。

Antigravity / Gemini

通过 MCP Server 连接

无需重启 IDE,新建会话(New Chat)或重连 MCP 即可生效。

OpenCode / Claude Code

通过 MCP Server 连接

新建会话(New Session)或重启一次命令行即可。

Pi Coding Agent

TypeScript 扩展插件加载

重启 Pi 客户端或执行 /reload 即可。


Usage (使用指南)

1. CLI 命令行工具

# 1. 检查 API 连通性与模型延迟
jev status

# 2. 自主 2-Tier 浏览器任务 (jev-ultrafast -> browser-use 自动降级)
jev browse https://example.com "Verify page title and confirm done"
# 或直接通过专用 CLI:
ego-browse https://www.google.com/travel/flights "Find one-way flights from Zurich to London on Sep 20"

# 3. 布尔真值置信度验证 (Noul)
jev noul "Is this an emergency?" --state "Database CPU 100%"

# 4. 多选项分类 (Choice)
jev choice "Department" --criteria "infra:Server down,billing:Payment issue" --state "Service timeout"

# 5. 标尺评分 (Score)
jev score "Severity" --criteria "low,medium,high" --state "SyntaxError in script"

# 6. 命令安全风控检查 (Guard)
jev guard "rm -rf /"

# 7. 查看 Token 节省数据遥测
jev stats

# 8. 会话历史无损脱水
jev compact transcript.json --out compacted.json

2. MCP Server 与 Hook 自动集成

运行 ./install.sh 后,已为各大 Agent 自动注册如下能力:

  • Codex (GPT-6):通过 universal-jev-codex-hook 拦截工具输出,长日志毫秒级收据化。

  • Pi Agent:通过 pi-extension.ts 实现工具结果脱水与 >=3 轮图片上下文自动瘦身。

  • Antigravity / OpenCode / Claude Code:通过 universal-jev-mcp 暴露核心工具:

    • jev_receipt:终端与工具长日志脱水为验证收据(支持 exitCode 短路)。

    • jev_compact:对话历史上下文无损压缩。

    • jev_decide_choice:快速多选项分类。

    • jev_decide_noul:布尔假说真值概率评估 ($0.0 \sim 1.0$)。

    • jev_decide_score:有序评分标尺。

    • jev_guard:高危命令与死循环熔断防护。

    • jev_status:服务连通性与延迟探针。


Development & Testing (测试与验证)

# 运行全量端到端测试 (原语、压缩、MCP Stdio 协议、收据)
npm test

# 运行收据脱水引擎专项测试 (涵盖 Diff 免疫、退出码短路、中间盲区采样等 7 大场景)
node ./test/test-receipt.js

License

MIT

Available Tools

6 tools
jev_compactA

Verbatim context compaction: prunes old verbose tool results while preserving conversation messages 100% verbatim.

Inputs: rawJson, messages, truncateHeadChars.

jev_decide_choiceB

Fast, calibrated multi-option classification with confidence and relative probabilities.

Inputs: state (required), criteria (required), question (required).

jev_decide_noulB

Calibrated boolean verification (Noul) returning true probability between 0.0 and 1.0.

Inputs: state (required), question (required).

jev_decide_scoreC

Calibrated rubric scoring across ordered levels (e.g. 0 to 3 severity/quality).

Inputs: state (required), criteria (required), question (required).

jev_guardB

Security and loop-detection guardrail before running risky commands or tool calls.

Inputs: command (required), context.

jev_statusB

Check Jev provider connectivity, model availability, and response latency.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct operation: compaction, guard, status, and three decision types that differ in output format (classification, boolean, score). The decide_* tools are clearly differentiated by their suffixes and descriptions, leaving no genuine ambiguity.

    Naming Consistency5/5

    All tools use the 'jev_' prefix followed by snake_case verbs and descriptive modifiers (compact, decide_choice, decide_noul, decide_score, guard, status). The pattern is uniform and predictable, with no mixing of conventions.

    Tool Count5/5

    Six tools is well within the ideal 3-15 range, providing a focused utility set without redundancy or bloat. Each tool earns its place for the server's stated purpose.

    Completeness4/5

    The tool surface covers core utility needs: compaction, guardrails, status monitoring, and three decision modalities. Minor gaps exist (e.g., no configuration tool or free-form generation), but these are likely outside the intended scope and do not create dead ends for typical workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables governed tool-calling agents with policy decisions, optional human approval, hash-chained audit logging, and deterministic evaluation.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables coding agents to make cheap, fast probabilistic decisions on every turn, with tools for coding-loop checks, review, verification, screening untrusted input, and ranking candidates.
      6
      209 npm
      68
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides deterministic context compaction and safety gating for AI agents, preserving original messages verbatim while dropping irrelevant ones and flagging destructive commands.
      2
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables agents to resolve routine typed routing, loop-stall arbitration, and tool safety checks locally instead of invoking a frontier LLM, returning schema-enforced decision outputs and telemetry at sub-millisecond latency. Also provides reversible execution checkpoints, token budgets, and decay-based episodic memory for safe, privacy-preserving autonomous operation.
      MIT