Interfaces

Principes #

1. Des fichiers pour le plan de données, des outils pour le plan de contrôle. Les octets circulent par montage, Git et S3 ; l’autorisation, l’approbation, la mémoire, la recherche et l’explication passent par MCP, HTTP et une CLI.
2. Les passerelles sont sans état. L’autorisation a lieu en un seul point de la couche Trust.
3. Chaque interface est une projection. Les différences de sémantique s’expriment par des correspondances d’erreurs explicites (par exemple, « validation en attente » devient un EACCES accompagné d’un fichier explicatif), et S3 ne fait pas semblant d’avoir des branches.
4. Une surface d’outils étroite. Pas plus de 10 outils MCP face aux agents ; les actions pour les personnes et les opérateurs vivent dans une interface d’opérateur distincte.
5. Les adaptateurs isolent l’évolution des protocoles. Les changements de version de MCP et d’A2A n’affectent que les adaptateurs.

Matrice des interfaces #

La surface d’outils MCP #

Seuls neuf outils s’adressent aux agents :

Sémantique du montage #

• Un montage lie une branche et une habilitation ; à l’expiration de l’habilitation, le montage passe en lecture seule puis est démonté.
• Commits automatiques (avec temporisation, par exemple après 5 secondes de calme) ; fsync déclenche un commit.
• Les chemins hors de l’habilitation n’apparaissent pas dans les listings de répertoires : cela réduit les fuites d’information et la surface d’attaque de l’injection de prompt.
• Adapté au sandbox : pas de root nécessaire ; FUSE ou NFS, l’un des deux, sans module noyau ; les montages en lecture seule sont possibles.

Git #

• Les branches d’exécution se nomment <role>/<run_id> ; main est protégée, et un hook pre-receive côté serveur rejette les pushs directs.
• nas propose crée une Agent PR.
• Les commits portent automatiquement des trailers tels que Run:, Lease: et Principal:.

S3 #

• Un bucket correspond à la vue de branche d’un arbre ; l’identifiant de version d’un objet est un commit.
• Les sémantiques qui manquent à S3, comme les branches, s’expriment par un préfixe de bucket ou un en-tête de requête (x-nas-branch). C’est une projection dégradée : les pipelines de données peuvent lire et écrire, mais n’ont pas l’expérience complète des branches.
• Les habilitations sont transmises sous forme d’identifiants temporaires de type STS.

A2A (optionnel) #

• Les tâches entrantes arrivent sous forme de fichiers de tâche dans inbox/ ; les livrables vont dans outbox/.
• L’Agent Card déclare les compétences du rôle et les habilitations dont il a besoin.
• Le NAS n’est pas un participant A2A ; c’est le runtime qui agit pour le rôle qui l’est. Le NAS ne fait que stocker les tâches et les livrables, les paquets de passation et les habilitations.

Conventions de l’API HTTP #

• **Chaque endpoint utilise POST, avec les paramètres dans un corps JSON ;** les champs des réponses sont toujours en snake_case.
• Les chemins sont versionnés : /v1/....
• Idempotence : les opérations d’écriture acceptent une idempotency_key.
• Pagination : cursor plus limit.
• Les budgets et les limites de débit sont renvoyés dans les en-têtes de réponse (octets restants, requêtes restantes) pour que les runtimes puissent s’autolimiter.

Une requête de lecture avec budget et sa réponse ressemblent à peu près à ceci :

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" }
  ] }

Les erreurs utilisent une structure uniforme :

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

Découverte #

• Les points d’entrée lisibles par les machines sont les mêmes que sur ce site : /.well-known/ai-catalog.json, la fiche de serveur MCP et llms.txt.
• Un point d’accès qui résout et vérifie les pointeurs de preuve nas://.
• MCP server/discover.