Sato Kit

@satohub/kit

0.1.1 プレビュー。

Sato Kit は、エージェントがすでに使っているツール（viem、signers、x402）を、prepare -> execute の契約でラップします。アクションが署名されていないインテントを準備し、ポリシーの事前チェックで拒否の理由を説明し、 トランザクションをシミュレーションしてから、execute({ intent_id }) で署名者に渡し、ハッシュチェーン化された sato.receipt/v1 の行を追加します。

これは、ウォレットでもカストディアンでもエージェントフレームワークでもなく、保証でもありません。 資金を保有することはなく、鍵も同梱しません。

• デフォルトではフォークを使用します。 ポリシーの network はデフォルトで fork です。メインネットの使用には明示的なオプトインが必要です。
• 事前チェックと強制適用は別です。 キットのポリシーチェックはインテントが返される前に実行され、どのルールが拒否したか、その理由を示します。 鍵が使われた後に何かを強制適用するものではありません。強制適用は署名者側で行います（例：同じファイルからコンパイルした CDP ポリシー）。
• scan.payto_changed。 policy.json の scan ブロックには payto_changed（caution | refuse | off）が記録されますが、これを強制適用するのは実装しているホストに限られます。 satohub-core のオフラインガード（scanRecipient）は現在これを強制適用しません。変更された x402 の payTo を検知するには、支払先の以前の値が必要ですが、オフラインチェックには渡されないためです。
• スワップは特定の取引所に依存しません。 どの取引所も使用できます。Sato Swap はラベル付きのデフォルトで、すべてのレスポンスで手数料が開示され、Sato の手数料がかからない見積もりも併記されます。venue: "direct" を指定すると Sato を完全にスキップします。

契約（sato.action/v1、sato.policy/v1、sato.receipt/v1）は src/spec にあります（VENDORED.md を参照）。

インストール

npm install @satohub/kit viem
npx -y @satohub/[email protected] --help

Node 20 以降が必要です。viem はピア依存関係です。以下の各フレームワーク SDK はオプションのピア依存関係で、サブパスを使用する場合にのみインストールされます。

制限事項

• 事前チェックであり、強制適用ではありません。 evaluatePreflight はインテントが返される前に実行され、拒否された各ルールとその制限値、観測値を示します。鍵が使われた後、キットは何も強制適用しません。強制適用は署名者側で行います（同じ policy.json からコンパイルされた CDP、Privy、Turnkey のポリシー、OWS のポリシーエンジン、または Safe のオーナー）。viemLocalSigner が強制適用するのは、メインネットの拒否のみです。
• x402 の実行範囲。 x402.prepare は x402 リソースが支払いを求める内容を読み取り、価格を付けてポリシーチェック済みのインテントを返します。execute は x402 の支払いを送信しません。送信するのは EVM トランザクション、EIP-712 の型付きデータ（Safe の提案）、Solana トランザクションのみです。支払いにはお使いの x402 クライアントを利用してください。
• AgentKit 自身による分析情報の送信。 AgentKit の @CreateAction デコレーターは、呼び出しのたびに cca-lite.coinbase.com へ呼び出しイベントを送信します。fromAgentKitProvider 経由で利用するアクションもこの呼び出しを行います。キットはこれをブロックせず、追加もしません。
• 価格不明の場合は拒否します。 USD 価格を読み取れない場合、max_usd_* ルールは推測せずに unknown_price で拒否します。
• シミュレーションは結果を保証しません。 シミュレーションに合格した場合に示されるのは、そのブロックでチェーンが返した内容です。

アクションリファレンス

登録済みのディスクリプターから node scripts/gen-actions-doc.mjs で生成されます（npm run build の実行後）。このテーブルとレジストリに差異がある場合は test/readme-actions.test.ts が失敗します。 「custody」は、sato.custody/v1 の3つの質問に対するディスクリプター自身の回答です。toolset は、そのツールがデフォルトの MCP プロファイルに含まれるか、--toolsets all を指定した場合のみ含まれるかを示します。

登録済みアクション

アクション ID	ツール名	種類	効果	カストディ	チェーン	ツールセット
chain.read	chain_read	読み取り	read	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, sepolia, base, base-sepolia, arbitrum, arbitrum-sepolia, optimism, optimism-sepolia, polygon	default, all
swap.quote	swap_quote	読み取り	quote	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, base, arbitrum, optimism, polygon	default, all
swap.prepare	swap_prepare	準備	quote, sign, broadcast	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	ethereum, base, arbitrum, optimism, polygon	default, all
x402.prepare	x402_prepare	準備	sign, pay	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	base, base-sepolia, ethereum, sepolia, polygon, arbitrum, optimism, solana, solana-devnet	default, all
erc8004.lookup	erc8004_lookup	読み取り	read	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, base, arbitrum, optimism, polygon	all
tx.simulate	tx_simulate	読み取り	simulate	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, sepolia, base, base-sepolia, arbitrum, arbitrum-sepolia, optimism, optimism-sepolia, polygon	all
token.approvals.list	token_approvals_list	読み取り	read	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, sepolia, base, base-sepolia, arbitrum, arbitrum-sepolia, optimism, optimism-sepolia, polygon	all
token.approvals.revoke	token_approvals_revoke	準備	sign, broadcast	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	ethereum, sepolia, base, base-sepolia, arbitrum, arbitrum-sepolia, optimism, optimism-sepolia, polygon	all
erc8004.register	erc8004_register	準備	sign, broadcast	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	ethereum, base, arbitrum, optimism, polygon	all
bridge.quote	bridge_quote	読み取り	quote	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, base, arbitrum, optimism, polygon	all
bridge.prepare	bridge_prepare	準備	quote, sign, broadcast	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	ethereum, base, arbitrum, optimism, polygon	all
safe.info	safe_info	読み取り	read	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	ethereum, sepolia, base, base-sepolia, arbitrum, optimism, polygon	all
safe.propose	safe_propose	準備	sign	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	ethereum, sepolia, base, base-sepolia, arbitrum, optimism, polygon	all
solana.read	solana_read	読み取り	read	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	solana, solana-devnet	all
solana.transfer	solana_transfer	準備	sign, broadcast	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	solana, solana-devnet	all
solana.swap.quote	solana_swap_quote	読み取り	quote	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：決してない	solana	all
solana.swap.prepare	solana_swap_prepare	準備	quote, sign, broadcast	キーを読み取る：いいえ；キーが外部に出る：いいえ；資金を移動する：承認がある場合	solana	all

メタツール

ツール名	種類	効果	ツールセット
execute	実行	sign, broadcast	default, all
status	メタ	read	default, all
actions_search	メタ	read	default, all
actions_describe	メタ	read	default, all

デフォルトの MCP プロファイル（順序どおり）：chain_read、swap_quote、swap_prepare、x402_prepare、execute、status、actions_search、actions_describe。

AgentKit プロバイダー（fromAgentKitProvider）から使用されるアクションは、この表には含まれていません。渡したプロバイダーから実行時に生成され、ツールセット all に表示されます。

エントリーポイント

import	提供するもの
@satohub/kit	createKit、coreActions、ツール群、設定ローダー、以下のすべての再エクスポート
@satohub/kit/spec	同梱されたコントラクト：sato.action/v1、sato.policy/v1、sato.receipt/v1、ID ルール、記述子のリント
@satohub/kit/policy	evaluatePreflight、コンパイラー compileCdpPolicy、compilePrivyPolicy、compileTurnkeyPolicy
@satohub/kit/signers	viemLocalSigner、owsSigner、cdpSigner、solanaLocalSigner、humanApprove
@satohub/kit/intent	インテントストア、HMAC インテント ID（loadOrCreateIntentSecret、verifyIntentId）
@satohub/kit/receipts	ハッシュチェーン形式の sato.receipt/v1 ログ
@satohub/kit/actions	すべてのコアアクション、記述子、ビルダー
@satohub/kit/ai-sdk	Vercel AI SDK 向けの satoKitTools(kit, opts)
@satohub/kit/agentkit	satoKitActionProvider(kit, opts) と fromAgentKitProvider(provider, { chain })
@satohub/kit/claude-agent-sdk	createSatoKitSdkServer(kit, opts) + requireApprovalHook()
@satohub/kit/openai-agents	satoKitOpenAITools(kit, opts)
@satohub/kit/langchain	satoKitLangChainTools(kit, opts)
@satohub/kit/eliza	satoKitElizaPlugin(kit, opts)（互換性アダプター。以下を参照）
@satohub/kit/mcp	ローカル MCP サーバー（stdio）
@satohub/kit/cli	関数としての sato-kit CLI
@satohub/kit/sato-os	attachToSatoOs、proposeIntent
@satohub/kit/goat	fromGoatPlugin(plugin, { chain }) — 既存の GOAT プラグインをキットの保証付きで利用

署名者

• viemLocalSigner — このプロセス内のキーです。デフォルトではフォーク／テストネットを使用し、allowMainnet: true（推奨されません）でない限り、メインネットのチェーン ID を拒否します。generate: true を指定すると、使い捨てのインメモリーキーを生成します。
• owsSigner — Open Wallet Standard アカウント上の構造的アダプターです。ポリシーの適用は OWS のポリシーエンジンが行います。src/signers/OWS.md を参照してください。
• cdpSigner — Coinbase CDP サーバーアカウント上の構造的アダプターです。CDP がポリシーを適用します。コンパイル済みポリシーを nativePolicy として渡すと、署名者に関連付けられます（アダプターは登録しません）。
• solanaLocalSigner — devnet とテスト専用のローカル Solana 署名です。メインネットへの切り替え手段はなく、devnet 以外のペイロードと mainnet-beta RPC を拒否します。
• humanApprove(signer, approve) — 任意の署名者をラップし、署名の前に各要約を人が承認するようにします。

ポリシーコンパイラー

compileCdpPolicy、compilePrivyPolicy、compileTurnkeyPolicy は、1 つの sato.policy/v1 をプロバイダー固有のポリシードキュメントに変換します。各結果には、コンパイルできなかった内容（not_compiled）とその理由が記載されるため、プロバイダーが表現できないルールが暗黙のうちに破棄されることはありません。

CLI

sato-kit read <action> --input '<json>'      run a read-only action
sato-kit prepare <action> --input '<json>'   build an intent; nothing is signed
sato-kit execute --intent <intent_id>        hand one prepared intent to the signer
sato-kit mcp [--toolsets default|all]        local MCP server over stdio
sato-kit doctor                              check config, Sato Status and template drift

設定は作業ディレクトリから読み込まれます：policy.json（ない場合はデフォルトポリシー、ネットワークは fork）、.sato/（インテント、インテントシークレット、レシート）、チェーンごとの SATO_RPC_URL_<CHAIN>、およびローカル署名者用の SATO_SIGNER=viem-local-fork（フォークネットワークのみ）。

MCP サーバー

npx -y @satohub/[email protected] mcp を実行すると、stdio MCP サーバー（レジストリ名 ai.satohub/kit）が起動します。デフォルトのプロファイルには上記の 8 つのツールが含まれます。--toolsets all を指定すると、登録済みのその他のすべてのアクションが追加されます。署名を行うツールには _meta に anthropic/requiresUserInteraction が含まれます。

Sato Status

status と sato-kit doctor は、templates リポジトリが公開するアクションごとの夜間実行結果（sato.action-status/v1）を読み取ります。そのファイルを読み取れない場合は、その旨が回答に示され、値が補完されることはありません。

推奨する .gitignore

ファイルベースのインテントストアとインテント HMAC シークレットは、デフォルトで .sato/ の下に保存されます（intents/、intent.key、モード 0600）。バージョン管理の対象にしないでください：

.sato/

ライセンス：MIT。同梱の Onchain Action Descriptor コード（dist/spec）は Apache-2.0 で、著作権は 2026 Prime Signal LLC に帰属します。LICENSE-ODA と NOTICE を参照してください。

sato-kit doctor：テンプレートの差分

create-sato-agent で作成されたリポジトリ（sato.create.json があるリポジトリ）では、doctor は sato.create.json と sato.lock.json も https://satohub.ai/api/create/drift に送信し（タイムアウトは 3 秒）、返された変更を表示します。変更には、チェックに合格した新しいテンプレートバージョン、ピン留めされたパッケージの保存済み Sato Check プロファイルにおける管理責任者の変更、または上流でテンプレートチェックに失敗するピン留めされたパッケージバージョンが含まれます。読み取り専用で、Issue は作成しません（生成された sato-drift.yml ワークフローが作成します）。--json を指定すると、結果は result.drift に含まれ、state は checked、unavailable（reason を含む）、または not_applicable になります。チェックから応答がない場合、値は設定されません。

ホストアダプター：エンベロープとエラーコード

@satohub/kit/ai-sdk（satoKitTools(kit, opts)）、@satohub/kit/agentkit（satoKitActionProvider(kit, opts)）、@satohub/kit/claude-agent-sdk（createSatoKitSdkServer(kit, opts) + requireApprovalHook()）、@satohub/kit/openai-agents（satoKitOpenAITools(kit, opts)、needsApproval を備えた OpenAI Agents SDK の関数ツール）、@satohub/kit/langchain（satoKitLangChainTools(kit, opts)、関数がエンベロープを JSON 文字列として返す LangChain JS の DynamicStructuredTool）、および @satohub/kit/eliza（satoKitElizaPlugin(kit, opts)）は、ローカル MCP サーバー（sato-kit mcp）と同じツール群から構築されています。オプションは { toolsets?, actions?, policy?, signerKind?, fetch?, statusTimeoutMs? } です（AgentKit、LangChain、elizaOS では approve も指定します。これらのホストには承認ステップがないため、指定しないと execute は拒否されます）。

@satohub/kit/eliza は、既存の elizaOS 1.x エージェント向けの薄い互換アダプターであり、サポート対象のフレームワークではありません。elizaOS に依存する Sato テンプレートはなく、elizaOS のリリースによって動作しなくなった場合、このサブパスは修正されずに削除されます。そのアクションは options.parameters（次に message.content.parameters）から引数を読み取ります。各アダプターツールは、次のいずれかのエンベロープを返します。

• { ok: true, tool, result }
• { ok: false, tool, error: { code, message, refusals? }, intent? }

エラーコード：unknown_tool、invalid_input、policy_refused、approval_required、approval_denied、not_configured、error。ポリシーによる拒否では、各 { rule, limit, observed } が列挙されます。execute が受け取るのは { intent_id } のみで、それ以外は受け取りません。どのホストでも、実行前に人の承認を求めます。

MCP サーバーでは、拒否された準備は通常の結果となり、structuredContent.policy.refusals に各ルールが示されます。呼び出しに失敗すると isError が設定され、詳細は _meta["ai.satohub/error"] に含まれます。

既存の AgentKit プロバイダー（@satohub/kit/agentkit）の利用

fromAgentKitProvider(provider, { chain }) は、AgentKit の ActionProvider の各アクションをキットのアクションに変換します。読み取りアクション（get_／check_／list_…という名前のもの、または reads として渡した名前）は読み取りとして扱われます。それ以外のアクションはすべて、トランザクションを送信する代わりに記録するキャプチャ用ウォレットに対してプロバイダー独自の invoke() を実行します。その1件のトランザクションは通常のインテントになります。シミュレーションされ、ポリシーの事前チェックを受け、あなたの署名者を使って execute(intent_id) で1回だけ送信されます。

import { erc20ActionProvider } from "@coinbase/agentkit";
import { fromAgentKitProvider } from "@satohub/kit/agentkit";

const { actions, not_consumable } = fromAgentKitProvider(erc20ActionProvider(), { chain: "base" });
const kit = createKit({ ...opts, actions: [...coreActions(), ...actions] });

• 2件以上のトランザクションの送信、またはメッセージ、型付きデータ、未加工トランザクションへの署名を試みるアクションは、その理由とともに拒否されます。何も送信されていないため、一部だけが実行されることもありません。
• ポータブルな形式にできないスキーマは、ツールに変換されず、lint の理由とともに not_consumable に一覧表示されます。パターンのない、金額を表す名前の文字列は10進数パターンに制限され、consumed[].tightened に一覧表示されます。
• 取り込まれたアクションの USD 価値は不明なため、max_usd_* の上限は unknown_price によって拒否します。max_per_trade は、キャプチャされたトランザクションから ERC-20 の金額またはネイティブトークンの値を読み取ります。
• AgentKit 独自の @CreateAction デコレーターは、呼び出しのたびに cca-lite.coinbase.com に呼び出し分析イベントを送信します。キットはこれをブロックしたり、追加のイベントを送信したりしません。
• 取り込まれたアクションは、ツールセット "all" と actions_search／actions_describe から利用できます。デフォルトの MCP プロファイルに変更はありません。

既存の GOAT プラグイン（@satohub/kit/goat）の利用

await fromGoatPlugin(plugin, { chain }) は fromAgentKitProvider と同様に動作します。読み取りは読み取りとして実行され、書き込みは、トランザクションを送信する代わりに1件のトランザクションを記録するキャプチャ用ウォレットに対して、プラグイン独自のツールを実行します。そのトランザクションは通常のインテントになります（シミュレーション、事前チェック、そしてあなたの署名者を使った execute(intent_id) を1回）。メッセージまたは型付きデータへの署名、ペイマスターリクエスト、または2件以上のトランザクションは、その理由とともに拒否されます。GOAT は上流での更新がしばらくありません。インストール環境に @goat-sdk/core が2つ含まれている場合、GOAT 独自のウォレット検索でウォレットが見つからないことがあります。1つだけを使ってください。

Safe の提案

safe.propose は、Safe のオーナーが署名する SafeTx を構築します。ポリシーの事前チェックは、その中の呼び出しに適用されます。インテントに Safe Transaction Service の送信先が設定されている場合、execute は署名して送信し、レシートには safe_tx_hash が含まれます。設定されていない場合、レシートには署名が typed_data_signature として含まれます。Safe のホスト型ゲートウェイを利用するには、createKit に safeTxService: { apiKey } を渡すか、SAFE_API_KEY の読み取りを有効にしてください。このキーは api.safe.global または設定したオリジンにのみ Authorization: Bearer … として送信され、ログやレシートに記録されることはありません。

Solana

Solana のアクションには Solana RPC（createKit の solanaRpc）が必要です。solanaLocalSigner は devnet 専用で、キットと同じ場所に @solana/kit 8 以降がインストールされている必要があります（npm i @solana/kit@^8）。古い @solana/kit が含まれるインストール環境（AgentKit 経由など）でも解決できるよう、peer dependency としては宣言されていません。

Base MCP（Coinbase Wallet MCP）との併用

Base MCP は現在 https://wallet-mcp.coinbase.com で提供されており、Base Account で署名します。キットの Base MCP プラグインは、まずシェル内でポリシーの事前チェックとシミュレーションを実行し、その後、 未署名の呼び出しを Base MCP に渡して、Base Account で承認できるようにします。これはカスタム プラグインです。Base はこれを掲載、保守、推奨していません。

シェルを使えるハーネスの場合（Claude Code の例。Base のインストール手順には Codex と Cursor も記載されています）：

claude mcp add --transport http base-mcp https://wallet-mcp.coinbase.com
npx skills add base/skills --skill base-mcp
curl -fsSL -o .claude/skills/base-mcp/plugins/sato-kit.md \
  https://raw.githubusercontent.com/satohubai/sato-hub-integrations/main/channels/base-mcp/sato-kit.md

次に、独自の policy.json を作成します（プラグインファイルにひな型があります。設定しない場合、デフォルトの ポリシーはすべてのメインネットリクエストを拒否します）。SATO_RPC_URL_BASE を設定し、プラグイン名を指定して 依頼します：「Sato Kit プラグインを使って、Base で 5 USDC を WETH にスワップしてください。」Base は、 プラグイン名を指定した場合にのみ、そのプラグインに処理を振り分けます。チャットのみの環境（Claude.ai、ChatGPT）では キットを実行できません。その場合、プラグインはその旨を伝えて停止します。

対応対象外：Stripe MPP

mpp.prepare は実装されていません。そのクライアント（mppx）は 1.0 より前の段階で、マイナーリリースでも破壊的変更が発生します。また、その決済方法は、キットの署名者が実行する単一の未署名トランザクションには対応しません。理由と情報源については、docs/mpp-research.md をご覧ください。

Sato OS への引き継ぎ（@satohub/kit/sato-os）

ライブモードでは、エージェントは準備済みのインテントをセルフホスト可能な Sato OS に送信し、ローカルで署名する代わりに、そこで本人の承認と署名を受けられます。attachToSatoOs({ baseUrl, name, goal, walletAddresses, chains }) はエージェントを接続し、スコープが設定されたトークンを .sato/sato-os.json に保存します（モード 0600、Git の追跡対象外。返却も出力もされません）。proposeIntent(prepared, { baseUrl, token }) は、Sato OS の sato_os_create_action_proposal ツールを通じてインテント（未署名のペイロード、概要、ポリシー判定、シミュレーション、手数料の開示）を提出し、{ proposal_id, status } を返します。拒否されたインテントや期限切れのインテントは送信されません。この経路では署名もブロードキャストも行われません。