インターフェース

指針 #

1. データ面にはファイル、制御面にはツール。 バイトはマウント、Git、S3 を流れ、認可、承認、記憶、検索、説明は MCP、HTTP、CLI を通ります。
2. ゲートウェイは状態を持ちません。 認可は Trust 層のただ 1 つの地点でだけ行われます。
3. どのインターフェースも投影です。 意味の違いは、明示的なエラーのマッピングで表します（たとえば「ゲート待ち」は、説明ファイルを添えた EACCES に対応します）。S3 にブランチがあるようには装いません。
4. ツールの面は狭く。 エージェントに向けた MCP ツールは 10 個以内です。人間や運用者向けの操作は、別のオペレーター用インターフェースに置きます。
5. アダプターがプロトコルの変化を隔離します。 MCP や A2A のバージョンの変化が及ぶのは、アダプターだけです。

インターフェースの一覧 #

MCP のツール面 #

エージェントに向けたツールは 9 つだけです。

マウントの意味 #

• マウントは 1 つのブランチと 1 つのリース に結びつきます。リースの期限が切れると、マウントは読み取り専用になり、その後アンマウントされます。
• 自動コミット（デバウンス。たとえば静かな状態が 5 秒続いたあと）。fsync がコミットを起動します。
• リースの外のパスは、ディレクトリの一覧に現れません。これは情報の漏えいを減らし、プロンプトインジェクションの攻撃面も小さくします。
• サンドボックスにやさしい：root は不要。FUSE か NFS のどちらか一方で、カーネルモジュールは要らず、読み取り専用のマウントもできます。

Git #

• 実行のブランチは <role>/<run_id> と名づけます。main は保護されており、サーバー側の pre-receive フックが直接のプッシュを拒否します。
• nas propose が Agent PR を作ります。
• コミットには、Run:、Lease:、Principal: などのトレーラーが自動で付きます。

S3 #

• バケットは 1 つのツリーのブランチビューに対応し、オブジェクトのバージョン ID はコミットです。
• ブランチのように S3 にない意味は、バケットのプレフィックスかリクエストヘッダー（x-nas-branch）で表します。これは 縮退した投影 です。データパイプラインは読み書きできますが、ブランチの完全な体験は得られません。
• リースは、STS 形式の一時的な認証情報として渡されます。

A2A（任意） #

• 受け取ったタスクは、inbox/ にタスクファイルとして入り、成果物は outbox/ に置かれます。
• Agent Card が、ロールのスキルと、必要なリースを宣言します。
• NAS は A2A の参加者ではありません。 ロールのために動くランタイムが参加者です。NAS が担うのは、タスクと成果物の保管、ハンドオフバンドル、リースだけです。

HTTP API の規約 #

• **すべてのエンドポイントが POST を使い、パラメーターは JSON のボディに入れます。** レスポンスのフィールドは、常に snake_case です。
• パスにはバージョンを付けます：/v1/...。
• 冪等性：書き込み操作は idempotency_key を受け取ります。
• ページネーション：cursor と limit。
• 予算とレート制限は、レスポンスヘッダー（残りのバイト数、残りのリクエスト数）で返し、ランタイムが自分でペースを落とせるようにします。

予算つきの読み取りのリクエストとレスポンスは、おおよそ次のようになります。

POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }

エラーは、統一された構造を使います。

{
  "error": {
    "code": "gate_required",
    "message": "This merge requires human approval.",
    "retryable": false,
    "request_id": "req_01JB7W2X4N",
    "details": { "gate_id": "gt_2Mx4" }
  }
}

発見 #

• 機械が読める入口は、このサイトと同じです。/.well-known/ai-catalog.json、MCP の Server Card、llms.txt。
• nas:// の証拠ポインタを解決して検証するエンドポイント。
• MCP の server/discover。