agent-q

Agent-Q

開発状況：Agent-Q は開発中のプロジェクトで、CLI、MCP、およびサポート対象のプロバイダーフロー向けの Sui 署名経路は、ハードウェアでテスト済みです。 現在の StackChan CoreS3 Firmware 経路では、開発やデモ向けの DEV_PROFILE 素材を使用しており、実際の資産の保管には適していません。ストレージとプロファイルの制限については「現在の状況」をご覧ください。

コンセプト

Agent-Q は実行面と署名権限を分離します。

実行機能は署名権限ではありません。Agent-Q は、エージェント主導およびローカルの Sui 署名フローにおいて、この境界を明確に保ちます。

この README では、ローカルの Sui 署名フローにおける Agent-Q の権限境界アーキテクチャについて説明します。現在の実装状況とプロファイルの制限については、docs/IMPLEMENTATION_STATUS.md で管理しています。

MCP クライアント、Sui CLI、およびサポート対象の Sui アプリ用アダプターは、ローカルの agent-q ホストプロセスを介して、制約付きリクエストを送信します。AI エージェントのランタイムは通常、MCP クライアントを通じて Agent-Q にアクセスします。ホストはリクエストを中継しますが、署名素材を保存したり、ポリシーを決定したり、署名を承認したりすることはありません。

Agent-Q Firmware は独立した署名デバイス上で動作します。実装済みの素材プロファイルに対応する署名素材とポリシーを保持し、デバイスの状態とリクエストの内容を確認します。実装済みのポリシーまたはデバイスローカルの承認ゲートを適用し、署名済みの結果または明示的な失敗を返します。

署名リクエストの転送はローカルにとどまります。署名権限はデバイス上にとどまります。リクエスト元は署名を要求できますが、署名素材を保持したり、承認モードを選択したり、自身のリクエストを承認したりすることはできません。

構成

Agent-Q は次の 3 つの役割で構成されます。

• リクエスト元は、署名、アカウント、ポリシーの読み取り、ポリシー提案の送信、またはステータスのリクエストを作成します。MCP クライアント、Sui CLI、Sui アプリ用アダプター、および Admin Page はリクエストの窓口であり、署名権限ではありません。
• ホストプロセスは、ローカルの agent-q プロセスです。MCP stdio ツール、ローカル HTTP API、Admin Page、およびアダプター向けのリクエスト窓口を提供し、制約付きリクエストを Firmware に中継します。
• Agent-Q Firmwareは、署名デバイス上で動作するソフトウェアです。Firmware はポリシーチェック、デバイスローカルの承認ゲート、署名、永続化、クリーンアップを担い、実装済みの素材プロファイルに対応する署名素材を保持します。

Agent-Q はシンプルな権限モデルを採用しています。

• リクエスト元はリクエストを作成します。
• ホストプロセスはリクエストを中継します。
• Firmware は、デバイスローカルの状態に応じて、実装済みの各リクエストタイプを処理します。

署名リクエストについては、実装済みのポリシーまたはデバイスローカルの承認ゲートで署名が許可されるかどうかを Firmware が判断します。

サポート対象外のチェーンとメソッドでは、明示的に失敗します。

Agent-Q の使用

• Sui ユーザーは agent-q-sui-signer を Sui CLI の外部署名ツールとして登録できます。packages/agent-q/README.md をご覧ください。
• MCP クライアントはローカルサーバーを実行し、Agent-Q の MCP ツールを呼び出すことができます。packages/agent-q/README.md をご覧ください。
• Sui アプリの開発者は、サポート対象の Wallet Standard アダプターフロー向けに Sui プロバイダーパッケージを使用できます。packages/provider-sui/README.md と packages/sample-sui-dapp-kit/README.md をご覧ください。
• Sui zkLogin のブラウザー設定と、署名のみのトランザクションチェックは、非本番用テスト Web サンプルにあります。packages/sample-zklogin-test-web/README.md をご覧ください。
• デバイスが所有する署名ポリシー、ローカル承認、および制約付き署名フローに取り組む Firmware およびハードウェアの開発者は、firmware/README.md から始めてください。

パッケージ

パッケージ	次の用途に使用します…
@stelis/agent-q-core	デバイスの検出、セッションの開始、Agent-Q プロトコルの呼び出し、Firmware の結果の解析。
@stelis/agent-q	ローカル MCP サーバー、Admin Page、agent-q-sui-signer の実行。
@stelis/agent-q-provider-sui	プロバイダー／Wallet Standard アダプターを介して、Sui アプリを Agent-Q デバイスに接続。
packages/sample-sui-dapp-kit	Agent-Q 経由で署名する、小規模な dapp-kit サンプルの実行。
packages/sample-zklogin-test-web	Agent-Q ブラウザープロバイダーを介して Web Serial で行う、Sui zkLogin の証明の準備／提案と署名のみのトランザクション確認用の、本番環境では使用しないブラウザーテストツールの実行。

現在の実装の主な機能

現在の実装には、次のデバイス内で完結する機能が含まれています。これらは 開発／デモ用の機能です。DEV_PROFILE と製品で有効な機能の制限については、 以下の「現在のステータス」を参照してください。

• デバイス内で完結する BIP-39 のセットアップ：Firmware はデバイス上で新しい 12 単語の BIP-39 バックアップフレーズを生成し、バックアップ用に表示できます。また、ローカルでのバックアップ確認と PIN の再入力後にのみ、 DEV_PROFILE のルートエントロピーを保存できます。
• デバイス内で完結するニーモニックの復元：Firmware はデバイスの UI を通じて 12 単語の BIP-39 インポートを受け付け、チェックサムを検証し、同じローカル PIN セットアップの手順に進めます。USB、ホストプロセス、および MCP によるニーモニックのインポートは実装されていません。
• Sui zkLogin のアクティブ ID：ブラウザーテストのフローでは、プロバイダー／Web Serial 経由で制限付きの zkLogin 証明素材を準備し、提案できます。Firmware はデバイス上で提案を確認し、ローカル PIN による承認を必須とし、制限付きの証明レコードを 1 件保存して、アクティブな zkLogin Sui アカウントを反映します。zkLogin がアクティブな場合、通常の Firmware 認可ゲートを通過した後、同じ署名リクエスト経路で zkLogin 署名エンベロープを生成します。Firmware は生の JWT を保存しません。
• 大容量の Sui トランザクションペイロード：sign_transaction はインラインの txBytes と、同一セッション内でステージングされたペイロードの送信に対応し、Sui のシリアライズ済みトランザクションの最大サイズまで処理できます。これはペイロードとアダプター入力の容量であり、すべての Sui トランザクション形式が意味的に署名可能であることを示すものではありません。未対応またはバインドできない形式は、署名前に失敗します。
• Sui スポンサードトランザクションの受信経路：Firmware には、解析された送信者がアクティブなアカウントで、解析されたガス所有者が別のスポンサーであるトランザクションを受け入れるかどうかを制御する、デバイス内の Sui アカウント設定があります。受け入れた場合でも、Agent-Q が返すのはアクティブな送信者の署名のみです。スポンサーの署名収集とトランザクション実行用の組み立ては Agent-Q の対象外です。

リクエストのフロー

flowchart LR
  Agent[AI agent] --> MCP[MCP API]
  Admin[Admin Page] --> HTTP[HTTP API]
  SuiCLI[Sui CLI] --> Signer[agent-q-sui-signer]
  App[Sui app] --> Provider[Sui provider]

  MCP --> Server[agent-q local server]
  HTTP --> Server
  Signer --> Server
  Provider --> Server

  Server --> Core[Agent-Q core]
  Core --> Firmware[Firmware]

現在の署名ルートを以下にまとめます。この README では、product-active とは、対応するソース、ドキュメント、テスト、ビルド、現行ツリーを対象としたハードウェアのエビデンス、および視覚的なエビデンスが docs/IMPLEMENTATION_STATUS.md で揃っていることを意味します。ルートは実装済みでハードウェアテスト済みでも、product-active のエビデンスが未完成の場合があります。

チェーン	メソッド	現在の動作
sui	sign_transaction	現在の実装では、インラインまたは同一セッション内でステージングされた Sui トランザクションバイト列に対応しています。リクエストを検証し、利用可能な場合は範囲が制限されたオフラインのトランザクション情報を解析して、デバイスローカルのポリシーまたはユーザー認証ゲートを適用します。ゲートが署名を許可した後にのみ、署名レスポンスを生成します。解析された送信者はアクティブアカウントと一致する必要があります。また、アクティブアカウントのデバイスローカルの Sui アカウント設定でガススポンサーが許可されていない限り、解析されたガス所有者も一致する必要があります。ポリシーモードでは、必要なポリシーの適用範囲が不足、不完全、不一致、または拒否判定となる場合、フェイルクローズします。ユーザーモードでは、ファームウェアが必要な意味的な情報を導出でき、必要な確認詳細を範囲が制限された表示サマリーに収められる場合にのみ、対象のオフライン情報を表示します。解析に成功しただけでは、明確な内容確認が保証されるわけではありません。それ以外の場合、有効なトランザクションがアクティブアカウントに紐づいていれば、デバイスローカルのブラインド署名警告を表示します。ブラインド署名とは、オフライン情報では詳細を十分に確認できない署名対象バイト列を承認することです。
sui	sign_personal_message	現在の実装では、ユーザー認証モードで範囲が制限された Sui 個人メッセージの署名に対応しています。ポリシー認証モードでは、このメソッドはフェイルクローズします。

現在の実装には Sui zkLogin のアクティブ ID パスが含まれていますが、docs/IMPLEMENTATION_STATUS.md では product-active としてマークされていません。サンプルのテスト用ウェブアプリは、Web Serial 経由でブラウザーとデバイス間のプルーフ設定、および署名専用のトランザクションチェックを実行します。Enoki、OAuth、プローバーの処理、Google OAuth のテストネット設定はブラウザーのテストレイヤー内にとどまり、Agent-Q が受け取るのは範囲が制限されたプルーフ提案のみです。サンプルでは JWT やプルーフ JSON を表示せず、ブラウザーのストレージにも書き込みません。

未対応のチェーンやメソッドは明示的に失敗します。チェーンは共有プロトコルを通じて公開されます。Agent-Q はチェーンごとに個別のプロダクト API を作成しません。

権限境界の基本

このセクションでは、誰が処理をリクエストでき、誰が決定を下せるのかを説明します。DEV_PROFILE のストレージと product-active のステータスについては、「現在のステータス」で説明します。

• ホストプロセス、MCP、Sui CLI ツール、プロバイダー、アプリ、エージェントはリクエスト元であり、署名権限を持つ主体ではありません。
• ホストプロセスは署名マテリアルを保存せず、署名やポリシーに関する決定も行いません。
• ファームウェアは、実装済みのマテリアルプロファイルに関する署名マテリアルとポリシーを保持し、署名に関する決定を担います。
• ファームウェアはデバイスローカルの状態に基づいて署名認証ゲートを選択します。リクエストからポリシー認証モードまたはユーザー認証モードを選択することはできません。
• Agent-Q は、署名リクエストの作成前にエージェント、アプリ、ウォレット UI、またはホストプロセス内で何が行われたかを検証できません。
• すべての外部リクエストは信頼できない入力です。署名前に、ファームウェアが範囲を制限したリクエスト内容を解析する必要があります。

現在の状況

詳細な状況は docs/IMPLEMENTATION_STATUS.md に記載されています。

現在の実装には、上記の Sui 署名ルート、MCP ツール、provider-sui、StackChan CoreS3 Firmware のパスが含まれています。ハードウェアでのスモークテストの範囲は docs/IMPLEMENTATION_STATUS.md に記録されています。製品で有効な署名サポートとして扱うのは、対応するステータス行でソース、ドキュメント、テスト、ビルド、ハードウェア、視覚的な証拠がすべて揃っている場合に限ります。

現在の制限事項：

• 現在の StackChan CoreS3 Firmware のパスでは、実資産のカストディではなく、開発やデモを目的とした DEV_PROFILE のマテリアルを使用しています。
• DEV_PROFILE では、ルートエントロピー、アクティブなポリシーレコード、ローカルの PIN 検証情報は通常の NVS に保存されます。Secure Boot、Flash Encryption、NVS Encryption は設定されていません。
• 実装されているマテリアルプロファイルは DEV_PROFILE のみです。
• 実行可能なチェーンは Sui のみです。
• Sui トランザクションの解析は、範囲が制限されたオフライン処理です。Agent-Q は Sui の実行をシミュレートせず、チェーンの状態も取得しません。
• Sui のスポンサー付きトランザクションのサポートは、上記の送信者に紐づく受信パスに限られます。Agent-Q はスポンサー署名を生成、収集、組み立てせず、Sui トランザクションを実行または送信することもありません。
• ポリシーで許可された個人メッセージへの署名は実装されていません。
• Sui zkLogin のブラウザーからデバイスへのセットアップ、クリア、再接続、署名の各パスは、製品で有効になっていません。
• ブラウザーの dapp 署名には、Node ローカルのプロバイダーファクトリーではなく、プロバイダー／ブラウザーのランタイムパスが必要です。

上級者向け

• プロトコル仕様：specs/PROTOCOL.md
• セキュリティモデル：docs/SECURITY_MODEL.md
• 状態モデル：docs/STATE_MODEL.md
• 現在のポリシースキーマと Sui ポリシーの詳細：docs/POLICY_SCHEMA.md
• 実装状況：docs/IMPLEMENTATION_STATUS.md
• ファームウェアの概要：firmware/README.md
• StackChan CoreS3 ターゲット：firmware/src/stackchan-cores3/README.md

開発

ワークスペースの依存関係をインストールします：

npm install

すべてのパッケージをビルドします：

npm run build

ルートのテストスイートを実行します：

npm test

ファームウェアのビルド手順はターゲットごとに異なります。まず firmware/README.md と、firmware/src/<hardware-id>/ 内のターゲット README を確認してください。

.WORK/ は、ローカルでの計画、作業用ファイル、調査資料のためのディレクトリです。Git では追跡されないため、ユーザー向けのビルド手順や実行手順で必要としてはなりません。