인터페이스

원칙 #

1. 데이터 플레인에는 파일, 컨트롤 플레인에는 도구. 바이트는 마운트, Git, S3로 오가고, 인가, 승인, 메모리, 검색, 설명은 MCP, HTTP, CLI를 거칩니다.
2. 게이트웨이는 상태를 갖지 않습니다. 인가는 Trust 계층의 단 한 곳에서만 이루어집니다.
3. 모든 인터페이스는 투영입니다. 의미의 차이는 명시적인 오류 매핑으로 드러냅니다(예를 들어 “게이트 대기 중”은 설명 파일이 딸린 EACCES로 매핑됩니다). S3에 브랜치가 있는 척하지 않습니다.
4. 좁은 도구 표면. 에이전트에게 노출되는 MCP 도구는 10개를 넘지 않으며, 사람과 운영자를 위한 동작은 별도의 운영자 인터페이스에 둡니다.
5. 어댑터가 프로토콜 변화를 격리합니다. MCP와 A2A의 버전 변경은 어댑터에만 영향을 줍니다.

인터페이스 매트릭스 #

MCP 도구 표면 #

에이전트에게 노출되는 도구는 아홉 개뿐입니다.

마운트 의미론 #

• 마운트는 브랜치 하나와 리스 하나에 묶입니다. 리스가 만료되면 마운트는 읽기 전용이 되었다가 해제됩니다.
• 자동 커밋(디바운스, 예를 들어 5초 동안 조용하면 커밋). fsync는 커밋을 일으킵니다.
• 리스 밖의 경로는 디렉터리 목록에 나타나지 않습니다. 정보 유출을 줄이고 프롬프트 인젝션의 공격 표면을 줄여 줍니다.
• 샌드박스 친화적: 루트 권한이 필요 없고, FUSE와 NFS 중 하나를 쓰며 커널 모듈이 필요 없고, 읽기 전용 마운트도 가능합니다.

Git #

• 실행 브랜치의 이름은 <role>/<run_id>이며, main은 보호되고 서버 측 pre-receive 훅이 직접 푸시를 거부합니다.
• nas propose가 Agent PR을 만듭니다.
• 커밋에는 Run:, Lease:, Principal: 같은 트레일러가 자동으로 붙습니다.

S3 #

• 버킷은 한 트리의 브랜치 뷰에 대응하고, 오브젝트 버전 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.