jev-browser-use

Jev ブラウザー操作

Codex、Claude Code、その他の互換性のある Skill ホストでは、npx skills add でインストールできます。ブラウザーの実行が現在検証されているのは、必要な Computer Use ランタイムを備えた Codex のみです。Claude Code のブラウザー連携は近日対応予定です。インストールしただけでは利用できません。ランタイムがない場合は、無関係なブラウザーツールで代用せず、その要件を報告してください。

ブラウザー検証では、これをデフォルトの最初の手段として使用してください。クリックごとにホストモデルがターンを消費しないよう、判断と操作のループは cua_repl 内で実行します。これはブラウザープラグインとのブリッジであり、単独で動作するブラウザードライバーでも、Codex の判断力の代わりになるものでもありません。

責任と制限

• タスク、認可、すべてのテキスト入力、グラフィカルな認識、視覚的な解釈、機密性の高い操作、最終確認は Codex が担います。Jev は高速な機械式ブラウザーオペレーターです。現在確認されている許可済みのナビゲーション、クリック、切り替え、スクロール、再読み込み、範囲を限定したキー操作から選択します。Jev は会話、入力、コンテンツの作成、スクリーンショットの認識、セレクター、コード、座標、URL、任意のテキストの生成は行いません。
• アプリ内ブラウザーまたは Google Chrome のみを使用し、Edge は使用しないでください。現在のブラウザーツールにおける初回呼び出しのルールとドキュメントに従ってください。すべての UI 操作には cua_repl を使用します。Playwright/CDP ドライバーを別途起動しないでください。
• このヘルパーは、名前を指定したクリック、範囲を限定したスクロール、安全なナビゲーションキー、再読み込み、複数チャンクにまたがる永続的なセッション、決定論的な状態待機に対応しています。スクロールの対象には、ページ、新たに解決された名前付き AX コンテナー、または視覚認識後に Codex が一度だけ指定した座標を選べます。Jev が座標を作り出すことはありません。このヘルパーには、意図的にテキスト入力アクションがありません。Codex がテキストを入力し、同じ Jev セッションを再開します。ネイティブのセレクト API、フレーム、キャンバス、ドラッグ＆ドロップ、アップロード、モデル入力としてのスクリーンショット、ネイティブデスクトップアプリは、ヘルパーで実装されていません。こうした不足への対応には Codex の CUA ツールを使用し、委任を中断せずに Jev を再開してください。
• Jev が返すのは needs_verification であり、検証済みの合格ではありません。適切な場合は新しいブラウザー状態とスクリーンショットを使用して、Codex が要求された結果を独自に確認する必要があります。スクロールに成功しても AX テキストが変わらない場合があります。その際、ヘルパーは effectNeedsVisualVerification を記録して処理を続け、誤って進展がないと判定することはありません。

想定される規模の境界は、操作の多いブラウザー作業です。ナビゲーション、パネルの展開、ボタンのクリック、コントロールの切り替え、ページ送り、スクロールは Jev のループ内で行い、機械的な操作ごとに Codex がモデルターンを消費しないようにしてください。テキスト入力、視覚的または意味的な判断、未対応のウィジェット、重大な承認ゲート、最終確認では、Codex に操作を引き継いでください。

設定済みヘルパーの読み込み

以下に示すように、loadConfig() を呼び出し、その結果を変更せずに createSession() または run() に渡してください。認証、API リクエスト、レスポンスの検証はヘルパーが担当します。ブラウザータスクでは、ユーザーから変更の依頼がない限り、プロバイダーの選択、設定済みモデルの上書き、独自 API クライアントの作成、認証情報の設定変更を行わないでください。

ユーザー設定はプロジェクトディレクトリをまたいで使用できます。ヘルパーは設定済みのローカルファイルから認証情報を読み込みます。認証情報、dotenv の内容、未加工の HTTP エラーボディを表示したり、ページやトレースに含めたりしないでください。認証情報がない場合は設定の問題です。無関係なファイルを検索したり、気付かれないようにプロバイダーを切り替えたりしないでください。

インストール、プロバイダーの変更、API のトラブルシューティングの場合に限り、API integration maintenance を参照してください。現在サポートされているすべてのアダプターが記載されています。ブラウザー検証のために読む必要はありません。

ブラウザツールを正しく検出する — 利用不可と判断する前に必ず確認してください

cua_repl は通常、mcp__cua_repl.js および mcp__cua_repl.js_reset として公開される直接のツール名前空間です。functions.exec 内の ネストされた tools.* メソッドではありません。アプリが管理するプラグインでは、コードモードや遅延ツールのリストから これらのツールが意図的に除外されています。そのため、 ALL_TOOLS.filter(... /cua|browser/ ...) の結果が空でも、ブラウザプラグインが 存在しないことを示すものではありません。そのリストを何度も検索したり、それを理由に処理を中断したりしないでください。

1. 汎用ツールカタログを検索する前に、このターンで利用できる直接ツールの宣言を確認してください。mcp__cua_repl.js がある場合は、優先して使用してください。ドキュメントに記載された初回呼び出しのエントリーポイントを使用し、続行する前に返されたランタイムドキュメントを読んでください。ツール名を推測したり、シェル、HTTP、推測した tools.* メソッドを介して直接ツールを呼び出したりしないでください。
2. その正確な名前空間がない場合は、ほかに宣言されているブラウザ／コンピューター操作ツールと、利用可能な検出手段を一度確認してください。それぞれのドキュメントに記載されたエントリーポイントに従ってください。ツール名が異なるからといって非互換だとは限りませんが、このブリッジには互換性のあるタブ API とモジュールインポートの実行環境が必要です。インポートする前に、これらの機能を確認してください。ホスト側のブラウザー操作機能しか利用できない場合は、ユーザーの指定範囲内でそれを使用し、Jev への委任は利用できなかったと報告してください。ブリッジが動作したと主張したり、テストしていないアダプターを即興で作成したりしないでください。
3. 次の3つの状態を区別してください。プラグインが全体で有効になっていること、このターンでツールが公開されていること、要求されたブラウザー／プロファイル／タブに到達できること。設定で証明できるのは有効化だけです。プラグインへの言及で証明できるのは選択だけです。要求されたタブを、ドキュメントに記載された方法で読み取れた場合にのみ、到達可能だと確認できます。アプリ内の空白タブが表示されても、ユーザーの Chrome セッションにアクセスできるとは限りません。
4. ユーザーが Chrome または既存のタブを指定した場合は、その対象に対応する、ランタイムのドキュメントに記載された検出／接続 API を使用してください。別のブラウザーセッションを開いたり、無関係な確認を根拠に既存のタブを調査したと主張したりしないでください。ブラウザーの指定がない場合は、以下の空白タブの確認方法を使用できます。
5. 処理が妨げられた場合は、失敗した状態と、実際に行った確認を正確に報告してください。存在しないタスク単位の切り替えを有効にするようユーザーに求めたり、すでに完了している全体設定を繰り返すよう求めたりしないでください。現在のアプリのドキュメントで @Chrome によるブラウザー選択がサポートされている場合は、メンションメニューから一度選択するよう提案してください。次のターンで再確認してください。ツールが引き続き見つからない場合は、プラグインがアンインストールされていると主張せず、その旨を伝えてください。新しいタスクの作成やアプリの再起動は復旧手段にはなりますが、解決が保証されるわけではありません。ユーザーが明示的に求めた場合にのみ新しいタスクを作成し、以下の引き継ぎチェックリストを使用してください。 Chrome への接続でログイン方式が拒否された場合は、そのブラウザーコネクターのエラーを Jev のプロバイダー認証とは分けて報告してください。ユーザーが Chrome や既存のタブを指定していない場合は、アプリ内ブラウザーを利用できます。Chrome セッションを明示的に指定されている場合に、それを黙って置き換えないでください。
6. 同じ空の検出クエリを何度も実行したり、既定で診断ファイルを書き込んだり、同梱のランチャーを書き換えたり、非公開のプラグイン環境をコピーしたり、安全策を無効にしたり、機能不足を回避するために別のブラウザードライバーをインストールしたりしないでください。

Skill は現在のプロジェクトディレクトリとは独立しています。Skill の絶対パスをインポートして loadConfig() を呼び出してください。loadConfig() は、インストール先や作業ディレクトリに関係なく、ユーザーのホームディレクトリにある ~/.config/jev-browser-use/config.json を読み込みます。loadConfig() が返すのは envFile、provider、model であり、API キーではありません。config.apiKey が存在しないのは想定どおりであり、認証情報の不足として報告してはいけません。承認された API リクエストを行う際に、参照先の dotenv 認証情報を読み込むのは decide() だけです。

コピー可能な最初のプローブ

ツールの呼び出し先：mcp__cua_repl.js（functions.exec の外部から直接ツールを呼び出します）。 引数：

{
  "code": "var taskTab = await cua.createBrowserTab('iab', 'about:blank', {visible:false});",
  "title": "检查浏览器操作接口"
}

このツールが現在のターンで宣言されている場合にのみ使用してください。最初の呼び出しには、この API 呼び出しだけを含めてください。次の呼び出しの前に、返されたドキュメントを読んでください。以降のナビゲーションと Jev ループでは taskTab を維持してください。

観察結果	正しい結論／次の手順
ALL_TOOLS に cua の結果がない	判断できません。直接ツールの宣言を確認してください。
ブラウザーパネルが開く	表示は機能していますが、操作はまだテストされていません。
直接の CUA 呼び出しが AX 状態を返す	ブラウザーランタイムは機能しています。Jev を続行してください。
config.apiKey が存在しない	想定どおりです。ヘルパー経由で envFile を使用してください。
API が HTTP 401/403 を返す	認証情報／アクセスの問題であり、ブラウザーの検出に関する問題ではありません。
Jev が needs_verification を返す	ページを個別に確認してください。まだ合格したと判断しないでください。
直接ツールが実際に存在しない	ツール宣言の根拠を報告し、上記の復旧手順を実施してください。

CUA 内でプロバイダーの通信を確認する

最初の CUA 呼び出しの後、セットアップまたは Jev リクエストで通信エラーが報告された場合は、この認証情報不要のプローブを使用してください。ブリッジの fetch が実行される**mcp__cua_repl.js 内で**実行してください。Jev API を呼び出したり、認証情報ファイルを読み取ったりはしません。OpenRouter の場合は api.typesafe.ai を openrouter.ai に置き換えてください。

var dns = await import('node:dns/promises');
var probe = {};
for (var host of ['example.com', 'api.typesafe.ai']) {
  try { await dns.lookup(host); probe[host] = 'dns_ok'; }
  catch (error) { probe[host] = error.code ?? error.name; }
}
try {
  var response = await fetch('https://example.com', {signal: AbortSignal.timeout(10000)});
  probe.fetch = response.status;
} catch (error) {
  probe.fetch = error.cause?.code ?? error.name;
}
nodeRepl.write(probe);

ここで ENOTFOUND が発生する場合、この CUA ランタイムはホストを解決できず、Jev リクエストはそのプロバイダーに到達できません。シェルリクエストの成功が証明するのは、シェルの接続性だけです。CUA プローブの成功が証明するのは、プローブ対象のホストへの通信だけであり、プロバイダー認証や Jev の推論ではありません。Codex／CUA のビルド番号だけでは、ホストポリシー全体でのサポートは確認できないため、バージョンに互換性があると決めつけず、アクティブなタスクを確認してください。プローブに失敗した場合は、ランタイムの結果を報告し、サポート対象で認可されたブラウザー／プロバイダー統合のみを使用してください。ランチャーへのパッチ適用や、無関係なプロセスを経由した認証情報の受け渡しは行わないでください。

タスクを失わずに引き継ぐ

ユーザーがブラウザーアクセスを復旧するための新しいタスクを依頼した場合は、以下を含めてください。

• 目的、指定されたブラウザー、既存のタブ／サイト、現在の進捗。
• 承認済みの正確な下書きテキスト、リンク、メンション、添付ファイルの絶対パス。
• インストール済み Skill のパス、設定済みプロバイダーの要件、Chrome／アプリ内のみという制限。
• 認可されている内容と、明確な停止地点。最新の指示が優先されます。「公開前に準備して停止する」という指示は、以前の公開許可に優先します。
• 判明しているブロッカーと完了済みの確認事項。認証情報や非公開ページのダンプは含めないでください。
• 指定されたモデルと、サポート対象の effort 設定。モデルを黙って別のものに置き換えないでください。

引き継ぎ先のタスクでは、使用可能なツールを自分で確認し、最新のブラウザー状態を読み取る必要があります。再入力や再アップロードを行う前に、既存の下書きがないか確認してください。プレビューのみの作業では、公開／送信のコントロールはホスト側に残し、決して実行しないでください。テキスト、受信者／メンション、リンク、添付ファイルを確認し、エディターを開いたままにしてください。アカウントに指定機能がない場合は、アクセス権を購入したり、下書きを切り詰めたり、別の形式で公開したりせず、その旨を報告してください。必要がなく、依頼もされていない限り、ディスク上に余分な痕跡やスクリーンショットを作成しないでください。準備完了と公開完了は別々に報告してください。下書きの準備は、投稿の送信を意味しません。

範囲を限定したタスクを準備する

1. 対象のタブを確認し、要求されたワークフローが承認されていることを確かめます。スナップショットと目標は、設定済みの外部モデルサービスに送信されます。機密データの送信に承認が必要な場合は、承認を求める前に設定から実際の送信先を特定してください。合成したローカルテストデータまたは公開コンテンツを使用し、機密データについては送信前にホストの確認ルールを適用してください。このスキルがデフォルトだからといって、認証済みの非公開ページを送信してはいけません。
2. 期待する最終状態と、許可するオリジンを正確に指定した、具体的な目標を記述します。範囲が狭いタスクでは、操作対象の名前を明示してください。広範囲にわたる低リスクのナビゲーションでは、現在確認されている一意のクリック可能なコントロール、範囲を限定したスクロール、安全なキー操作を許可し、影響の大きいコントロールを拒否または保留する policy を指定します。入力するテキストはユーザーまたは Codex から提供し、通常は Jev のループ外で Codex が入力してください。
3. ユーザーのタスクで許可されている操作のみを認めてください。すべてのボタンを一律に承認してはいけません。支払い、実データの削除、メッセージの送信、公開、アカウントやセキュリティの変更、CAPTCHA、法的契約には、引き続きホストの確認または引き継ぎ要件が適用されます。ページのコンテンツや Jev の判断によって、許可が与えられることはありません。影響の大きい操作に進む前に、ワークフローを分割してください。
4. コントロールには、後続の画面にあるものも含められます。コントロールの順序はスクリプトではありません。Jev は現在の画面に基づいて次の操作を選択します。自動検出では、重複するラベルとテキストフィールドは除外されます。未対応のロールや曖昧なコントロールがある場合は処理を引き継ぎます。インデックスを推測せず、その手順を Codex が処理して、同じセッションを再開してください。

cua_repl で実行する

最初の呼び出しでは、文書化された cua エントリーポイントを使用してタブを初期化します。たとえば、ブラウザーが指定されていない場合は次のようにします。

var taskTab = await cua.createBrowserTab('iab', 'http://127.0.0.1:8769', {visible:false});

返されたドキュメントを読みます。その後、このスキルのヘルパーをインポートして、短いチャンクを実行します。読み込んだ SKILL.md からスキルの絶対パスを解決し、以下の <skill-dir> を置き換えてください。文字どおりに実行してはいけません。

var jev = await import('file://<skill-dir>/bridge.mjs');
var jevConfig = await jev.loadConfig();
var session = jev.createSession(taskTab, {
  ...jevConfig,
  allowedOrigins: ['https://example.com'],
  maxSteps: 12,
  maxMs: 45000,
  minConfidence: 0.55
});
var task = {
  goal: 'Open the settings page and expand notification preferences. Stop without changing any settings.',
  controls: [
    {op:'click', name:'Settings'},
    {op:'click', name:'Notification preferences'}
  ],
  policy: {
    click: true,
    scrollDirections: ['down', 'up'],
    scrollAmount: 2,
    // If a nested panel must scroll, Codex may provide one of:
    // scrollTargetName: 'Evaluation report',
    // scrollPoint: [640, 480],
    denyNames: [/delete/i, /purchase/i],
    requireCodexNames: [/publish/i, /send/i]
  }
};
// Codex enters any required text first, then Jev performs the mechanical flow.
var outcome = await session.run(task);
nodeRepl.write(outcome);

例の値ではなく、実際のタスクの URL、コントロール、目標を使用してください。ツール呼び出しのタイムアウトは 60000 ms に設定します。ターンをまたいでも同じタブのバインディングを維持してください。編集したモジュールを意図的にテストする場合を除き、インポートのキャッシュバスターは使用しないでください。

このヘルパーは、常に最新の完全な AX スナップショットを使用し、モデル呼び出しと操作の前にオリジンを確認し、状態が変化した判断を拒否し、Choice の応答を検証し、リクエスト数とステップ数の上限を適用します。createSession() は、Codex への引き継ぎをまたいで履歴と累計メトリクスを保持します。discoverActions() は、ポリシーで許可されている、観測済みの一意なテキスト以外のコントロールのみを公開します。waitForState() は、Jev の呼び出しを消費せずに、範囲を限定した決定的な読み込み待機を行います。Confidence は保守的な引き継ぎのヒューリスティックであり、成功を正確に保証するものではありません。ブラウザー呼び出し自体にはプラグインのタイムアウトが適用されます。maxMs によって期限後の追加操作は防止できますが、実行中のプラグイン呼び出しを中断することはできません。

結果を処理して検証する

• needs_verification：新しい最終状態を自分で確認し、期待される値と関連する失敗条件をすべてチェックします。視覚的なアサーションにはスクリーンショットを使用します。この独立した確認を完了してから、合格と報告してください。
• low_confidence、blocked、no_progress、loading_timeout、decision_error、action_error：返された状態、安全なエラー概要、handoffを確認します。後続の判断やブラウザー操作が失敗しても、完了した操作とメトリクスはセッションに保持されます。Codexがサポート対象外または機密性の高いステップを実行した後、同じセッションを再開します。合格にするためだけに信頼度を下げてはいけません。
• step_limit、budget：再開する前に確認します。タスクが引き続き有効で、進捗を考慮してもう1回の制限付き処理を行う価値がある場合に限り、session.run(task)で続行します。無限に再試行しないでください。
• 例外：ガードされた判断や操作の結果の外部で発生した、契約や状態に関するエラーを調査します。HTTP本文、認証情報、dotenvファイルは出力しないでください。認証エラーやクォータエラーは実際のブロッカーです。やみくもに再試行しないでください。
• 許可されたオリジンの外部へのナビゲーションは、次のモデル呼び出し／操作の前に停止されます。許可リストを拡張する前に、新しいページと権限を確認してください。オリジンの許可リストだけでは、データ損失や操作の認可を完全には防げません。明示的な制御とホスト側のレビューも引き続き必要です。

通常のタスクでは、結果、セッションのメトリクス、Codexへの引き継ぎ、ループの経過時間、制限事項を簡潔に報告します。アサーションはそれぞれ独立してPass、Fail、Not coveredとして扱います。特定の出力カテゴリが1回の実行で得られなかったという理由だけで、有効なフローを失敗にしないでください。トレースを保存するのは有用な場合に限り、権限に応じた適切なストレージを使用してください。スナップショットや入力テキストにはユーザーデータが含まれる可能性があります。トレースファイルは自動的には書き込まれません。

ランタイム要件

このSkillには、cua_repl、Nodeモジュールのインポート、ファイルシステムへのアクセス、fetchを備えたホストが必要です。別のエージェントにそのランタイムがない場合は、互換性がないことを説明してください。このSkillだけでは、ブラウザーの権限やツールは提供されません。