Interfaces

Principios #

1. Archivos para el plano de datos, herramientas para el plano de control. Los bytes viajan por montajes, Git y S3; la autorización, la aprobación, la memoria, la búsqueda y las explicaciones pasan por MCP, HTTP y una CLI.
2. Las pasarelas no tienen estado. La autorización ocurre en un único punto de la capa Trust.
3. Cada interfaz es una proyección. Las diferencias de semántica se expresan con asignaciones de error explícitas (por ejemplo, “compuerta pendiente” se asigna a un EACCES con un archivo explicativo), y no se finge que S3 tenga ramas.
4. Una superficie de herramientas estrecha. No más de 10 herramientas MCP miran a los agentes; las acciones para personas y operadores viven en una interfaz de operador aparte.
5. Los adaptadores aíslan el cambio de protocolo. Los cambios de versión de MCP y A2A solo afectan a los adaptadores.

Matriz de interfaces #

La superficie de herramientas MCP #

Solo nueve herramientas miran a los agentes:

Semántica del montaje #

• Un montaje enlaza una rama y una concesión; cuando la concesión caduca, el montaje pasa a solo lectura y después se desmonta.
• Commits automáticos (con retardo, por ejemplo tras 5 segundos de calma); fsync activa un commit.
• Las rutas fuera de la concesión no aparecen en los listados de directorio: esto reduce la fuga de información y la superficie de ataque de la inyección de prompts.
• Apto para sandboxes: no hace falta root; FUSE o NFS, uno de los dos, sin módulo del kernel; son posibles los montajes de solo lectura.

Git #

• Las ramas de ejecución se llaman <role>/<run_id>; main está protegida y un hook pre-receive en el servidor rechaza los push directos.
• nas propose crea un Agent PR.
• Los commits llevan automáticamente trailers como Run:, Lease: y Principal:.

S3 #

• Un bucket corresponde a una vista de rama de un árbol; el ID de versión de un objeto es un commit.
• La semántica que S3 no tiene, como las ramas, se expresa con un prefijo de bucket o una cabecera de solicitud (x-nas-branch). Es una proyección degradada: las canalizaciones de datos pueden leer y escribir, pero no obtienen la experiencia completa de ramas.
• Las concesiones se pasan como credenciales temporales al estilo STS.

A2A (opcional) #

• Las tareas entrantes llegan como archivos de tarea en inbox/; los entregables van a outbox/.
• La Agent Card declara las habilidades del rol y las concesiones que necesita.
• El NAS no es un participante de A2A; lo es el runtime que actúa por el rol. El NAS solo almacena tareas y entregables, paquetes de traspaso y concesiones.

Convenciones de la API HTTP #

• **Todos los endpoints usan POST, con los parámetros en un cuerpo JSON;** los campos de respuesta son siempre snake_case.
• Las rutas llevan versión: /v1/....
• Idempotencia: las operaciones de escritura aceptan una idempotency_key.
• Paginación: cursor más limit.
• Los presupuestos y los límites de frecuencia se devuelven en las cabeceras de la respuesta (bytes restantes, solicitudes restantes) para que los runtimes puedan autolimitarse.

Una solicitud y una respuesta de lectura con presupuesto se ven más o menos así:

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

Los errores usan una estructura uniforme:

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

Descubrimiento #

• Los puntos de entrada legibles por máquinas son los mismos que en este sitio: /.well-known/ai-catalog.json, la Server Card de MCP y llms.txt.
• Un endpoint que resuelve y verifica los punteros de evidencia nas://.
• MCP server/discover.