jevnav

jevnav

ブラウザーエージェントのためのページの真実 — そして、再実行・テスト・監査ができる判断。

https://github.com/user-attachments/assets/502550ec-77d4-439e-b334-fe7007f946b9

jevnav は、エージェントとテストのためのブラウザーレイヤーです。ページを事実 （構造、計算済みスタイル、画面上のコントロール）として読み取り、 Jev — 構造化された質問に対応する TypeSafe のモデル — に、意図に合う要素を校正済みの確率で選ばせ、 リスクの高い操作や確信度の低い操作をゲートで人間の確認に回し、あらゆる判断を トレースに記録します。replay は CI でそのトレースをオフラインで再検証します。

• ピクセルではなく、ページの真実。 outline、styles、diff は、ブラウザーが解決した内容を返します。モックアップと実行中のアプリの間で font-size 32px → 28px になっていれば、エージェントが修正できます。判断ループにスクリーンショットは不要です。
• 確信度ではなく、証拠。 各判断には確率、ゲートの判定、コストが含まれます。記録された判断を壊すサイト変更があると、replay は終了コード 1 で終了します — モデル呼び出しも API キーも不要です。
• エージェントが動作する場所で使えます。 CLI、Python/pytest、Claude Code、Cursor、Codex などに対応する MCP サーバー、そして GitHub Action を利用できます。

このツールが生まれた理由 — ラベルが変わるとセレクターテストは壊れます。LLM ブラウザーエージェントは確信度が高く、監査できず、ときには誤ります：docs/why.md。

インストール

uv tool install jevnav          # or: pip install jevnav  (the MCP server is included)
playwright install chromium     # one-time browser download

Python 3.10 以降が必要です。判断を行うコマンド（go、run、browse、goal）には、TYPESAFE_API_KEY または ~/.config/typesafe/apikey.txt に TypeSafe API キーが必要です。replay、diff、outline、styles にキーは不要です — それがこのツールの要点です。

クイックスタート

1. Jev に操作させる — 目標と、それを達成したと証明する結果を指定します。

jevnav go --goal "sign in with the demo account and open the pricing page" \
  --start https://app.example.com/login \
  --context [email protected] --context password="${ACME_PASSWORD}" \
  --success "#pricing.visible" \
  --report goal.md

status: done — outcome verified against the page
steps: 5 — auto 4, review 0, blocked 0

ステップごとに Jev へのリクエストを 1 回行い、すべてのステップにゲートとトレースが適用されます。目標を達成したとき、ページ上で進行できることがなくなったとき（stuck）、ゲートが人間の確認を求めたとき（review）、ページの変化が止まったとき（no_progress）、または --max-steps に達したときにループは停止します。done は主張です — --success を指定すると証拠になり（verified、または unverified となり実行は失敗します）。--dry-run は操作せずに判断します。

2. またはフローをスクリプト化して、Jev に各意図を解決させます。

# flows/acme-login/flow.yaml
id: acme-login
start: https://app.example.com/login
steps:
  - intent: "Sign in to the existing account"
    action: click
  - intent: "Type the password"
    action: fill
    value: "${ACME_PASSWORD}"   # read from the environment, never written to the trace
  - intent: "Submit the login form"
    action: click

jevnav run flows/acme-login/flow.yaml --report run.md

3. CI でリプレイする — オフライン、決定論的、キー不要です。

jevnav replay acme-login.trace.jsonl            # re-resolve every recorded decision
jevnav replay acme-login.trace.jsonl --execute  # also re-run the actions + check --success

steps 3  verdicts: ok 3

サイト上で Sign in を Log in に変更すると、同じリプレイが失敗します。

[01] changed   Sign in to the existing account
      no element now has 'button|sign in' (was 'Sign in' / 'button')

終了コード 1 と、その理由が返されます。これがリグレッションテストです。

エージェントのためのページ情報

スクリーンショットなしで、コーディングエージェントがレンダリング済みページについて必要とする事実を取得できます。 領域の構造（タグ、見出し、テキスト、ボックス）は outline(selector)、 計算済みの値は styles(selector, props)、 jevnav が操作できるコントロールは page_state() で確認できます。

jevnav diff はモックアップと実行中のアプリを事実に基づいて比較し、差異がある場合は終了コード 1 で終了します。

jevnav diff new-ui.html http://localhost:3000 --report ui-diff.md

要素	プロパティ	モックアップ	アプリ
h1 [Pricing]	font-size	32px	28px
button#cta [Start free]	border-radius	8px	4px

レポートには構造の差異（要素の欠落、新規追加、移動、4px の --tolerance と比較したボックス）も記載されます。「新しい UI ができたので、コードベースを更新する」場合のループは、エージェントが jevnav で両方のページを読み取り、自らコードを編集し、終了コードが 0 になるまで diff を再実行し、その後 goal(..., success="<selector>") で結果を固定して、replay --execute で継続的に検証するというものです。jevnav はレポートを出力するだけで、リポジトリを編集したり、ピクセルを比較したりすることはありません。

ゲート

すべての判断には、次の 3 つの判定のいずれかが割り当てられます。

判定	意味
auto	信頼度がしきい値以上で、リスクがない場合、アクションを実行します
review	低い p、リスクのある意図、候補リストの切り捨てなどの場合、先に人間が確認します
blocked	判断できなかった場合（モデルが none と回答した、または呼び出しに失敗した場合）

review と blocked では実行されません。しきい値とリスクのあるパターンは任意の gates.yaml に記述されます。デフォルトでは 9 言語に対応しています。

# flows/acme-login/gates.yaml
min_confidence: 0.9        # scripted flows: one question per step, well calibrated
loop_min_confidence: 0.5   # goal loop: four questions at once, p runs lower
risky:
  - "\\b(delete|remove|purchase|pay)\\b"   # matched against intent + element name + role
intents:
  "delete the *": { min_confidence: 0.99 }
truncated: review          # the page had more than 255 candidates

goal のループでは、意図的にしきい値を低く設定しています。正しいループ判断の測定値は p 0.41～0.99、誤った判断は 0.39～0.47 となるため、安全性は代わりに決定論的なチェックで確保します。ボタンに対する fill は拒否され、コンテキスト値のないフィールドはブロックされ、何も変更しないステップが 2 回続くと実行を停止し、リスクのあるパターンは必ずレビューに回され、結果は --success と照合して検証されます。

MCP サーバー

claude mcp add --scope user jevnav -- uvx jevnav mcp

または、Cursor、Claude Desktop、VS Code などのクライアントの場合：

{
  "mcpServers": {
    "jevnav": {
      "command": "uvx",
      "args": ["jevnav", "mcp"],
      "env": { "TYPESAFE_API_KEY": "..." }
    }
  }
}

URL やフラグは不要です。エージェントは goto でページを開き、1 つのサーバーですべてのサイトに対応し、各セッションでは監査可能な jevnav-session.trace.jsonl が書き込まれます（--no-trace で無効化できます）。判断を担うツールが、ほかのブラウザー MCP にはない機能です。

ツール	機能
browse(intent, action, value, min_confidence)	1 ステップを実行します。Jev が要素を選び、ゲートが判断し、auto の場合のみ実行します
goal(goal, context_json, max_steps, success)	最後まで実行します。検証結果とともに done／stuck／review を返します
goto(url) · page_state() · summary()	ページを開く、jevnav が操作できる対象を一覧表示する、セッションの合計を取得する

さらに、操作と調査のための 28 個のツール（フォーム、キー、アップロード、タブ、コンソール、ネットワーク、スタイル、アウトライン、エミュレーション、トレース、Lighthouse）があり、それぞれに MCP アノテーションが付いているため、ホストはどの呼び出しが状態を変更するかを把握できます。判断 1 回あたりのコストは約 $0.00004、所要時間は約 330ms で、ページが LLM のコンテキストに入ることはありません。ツールの完全なリファレンス、セキュリティフラグ、jevnav と Playwright または chrome-devtools-mcp の使い分けについては、docs/mcp.md を参照してください。

CI — GitHub Action

- uses: dtduc-git/jevnav@v0
  with:
    trace: examples/local-demo/demo.trace.jsonl
    execute: "true"          # also re-run the recorded actions
    report: replay.md

モデル呼び出しも API キーも不要で、約 30 秒で完了します。記録された対象が変更された場合、曖昧になった場合、または記録された --success セレクターが表示されなくなった場合に失敗します。入力：trace、report、execute、json、version（デフォルトは PyPI の latest、チェックアウトには local）。@v0 は最新のバージョンを指します。CI の完全な再現性を確保するには、@v0.2.2 などのリリースタグを指定してください。

pytest

jev フィクスチャはパッケージに同梱されています。通常の Playwright テストで Jev の判断を利用でき、すべてのテストで CI で再生できるトレースが書き込まれます。

def test_sign_in(jev):
    jev.goto("https://app.example.com/login")
    jev.fill("the email address", "[email protected]")
    jev.fill("the password field", "${DEMO_PASSWORD}")
    jev.click("the sign-in button")
    jev.expect("#welcome")

DEMO_PASSWORD=... pytest --jev-trace-dir=traces
DEMO_PASSWORD=... jevnav replay --execute traces/test_sign_in.trace.jsonl   # offline, no key

review 判定の場合、アクションが実行される前にテストは失敗します。${VAR} の値は名前のみが記録され、jev.page はそれ以外のすべてに使用できる実際の Playwright ページです。トレースをコミット済みの実行可能なサンプルは、examples/pytest-interop/ を参照してください。

自分専用のブラウザー

jevnav go --goal "..."                                          # fresh headless Chromium (default)
jevnav go --goal "..." --user-data-dir ~/.cache/jevnav-profile --headed   # persistent profile
jevnav go --goal "..." --cdp http://127.0.0.1:9222              # attach to a running Chrome

--headed で一度ログインすると、以降の実行では同じプロファイルが再利用されます。--cdp はすでに開いている Chrome を操作し、独自の設定を維持するため（--user-data-dir、--locale、--timezone、--user-agent は受け付けません）、Chrome を閉じることもありません。どちらも run、 go、replay、mcp で使用でき、firefox または webkit を指定する --browser も同様です（さらに --locale、--timezone、--user-agent も使用できます）。プロファイルのパスと Cookie がトレースに含まれることはありません。

エビデンス

対象	結果	出典
実際のサイトでの要素選択（9 サイト、jev-1.13.0）	評価対象の 41 件すべてで正解。p ≥ 0.9 の基準では 30 件すべてで正解	research/browser-element-selection.md
判断のレイテンシとコスト	p50 365ms、判断 1 回あたり $0.000153	同上
目標達成ループ（ローカルのフィクスチャ、目標 4 件 × 表現 2 通り）	不可能な目標（stuck）を含め、8 件すべての目標で正解	docs/evidence.md
chrome-devtools-mcp との操作タスク比較（同じ LLM、n=2）	jevnav は 8 件中 8 件、chrome-devtools-mcp は 8 件中 6 件。chrome-devtools のエンドツーエンド処理は 2.4 倍高速	research/driving-benchmark.md
リプレイ	決定論的：オフラインで実行でき、キーは不要。判断に失敗すると終了コード 1	お手元のトレースで実行してください

サンプル数が少なく、アノテーターも 1 人です。証明ではなく、傾向として読み取ってください。jevnav の強みは判断コストとエビデンスであり、小規模なページでの実時間の速さではありません。手法、注意事項、ツール単位の比較については、 docs/evidence.md をご覧ください。

仕組み

• ページ全体ではなく、候補を絞り込みます。 すべてのフレームと開いているシャドウルートから、表示中のインタラクティブ要素を抽出し、人が操作する可能性の高さで順位付けして、最大 120 件に制限します（--max-candidates、上限 254 件）。各要素にはロール、アクセシブル名、タイプ、href、プレースホルダー、スコープが付与されるため、3 つの「Email」フィールドを区別できます。
• 各ステップで質問は 1 つです。 候補リストに none を加えて選択式の質問を作り、Jev は要素 1 つとその確率で回答します。
• 位置ではなく、フィンガープリントを使います。 要素の識別子は role|name です。トレースには、モデルが認識したすべての候補のフィンガープリントが保存されます。また、アクションとリプレイでは、一意性を確認したうえでフィンガープリントから要素を特定するため、ページのレイアウトが変わっても誤った要素をクリックしません。
• リプレイの判定結果。 ok、moved、changed、ambiguous、error の 5 種類で、最後の 3 つは失敗を示します。--normalize REGEX を使うと、Cart (3) → Cart (4) のような既知の変動を許容できます。デフォルトは厳密モードです。

トレース形式は公開仕様です：SPEC.md。操作可能なアーキテクチャ図：docs/architecture.html。Web の枠を超えた用途については、docs/games.md（Jev が構造化状態からゲームをプレイし、ランダムな対照群と比較した測定結果）をご覧ください。

対象外

• プランナーではありません。 go／goal は、指定した目標に向けて操作します。何をするかの判断はユーザーまたはエージェントが担います。jevnav はどこを操作するかを判断し、その理由を記録します。
• ピクセルによる判断は行いません。 判断ループでスクリーンショットやキャンバスの画像認識は行わず（screenshot は人間向けに用意されています）、テキスト生成も行いません。fill の値はユーザーのフロー、コンテキスト、または環境から取得します。
• ホステッドサービスもテレメトリーもありません。 設定済みの Jev エンドポイントに送信する質問を除き、マシンの外にデータが送信されることはありません。

プライバシー

トレースにはページ URL、要素名、操作内容が含まれますが、スクリーンショットは含まれません。目標達成ループでは、ページ上で表示されているテキストと現在のフォーム値の短いダイジェストも送信されます（パスワードはマスクされます）。スクリプト化されたフローでは、どちらも送信されません。${ENV} の値は名前だけが記録されます。.gitignore に *.trace.jsonl を追加し、トレースを共有する前に内容を確認してください。MCP サーバーの権限境界については、SECURITY.md をご覧ください。

スイート

jevnav は、検証スタックにおけるブラウザー部分です。 mcplint（MCP 設定）、 harnessguard（エージェントハーネス）、 jevassert + jev-packs（キャリブレーション済みの判定パック）、 および jev-table で構成されています。

ライセンス

Apache-2.0 · リリースと変更履歴