Barrel
EN GitHub

Donnez un espace à chaque agent, et partagez-le par jeton.

Un espace est une base dans laquelle un agent travaille. Vous le partagez en remettant un jeton de capacité en lecture, en écriture ou en admin ; vous le reprenez en révoquant le jeton. Les sessions gardent les messages et l’état de travail d’un agent, et une passation transmet une tâche à un autre agent avec son contexte en place.

Les agents accèdent à tout cela en MCP ou en REST. Les mêmes opérations existent en Erlang quand vos agents tournent dans le même nœud.

Espaces, sessions, passationsPoint d’accès MCP

Ce que c’est

Cinq pièces, chacune une fine couche au-dessus d’une base barrel. Les espaces s’ouvrent par le gestionnaire de cycle de vie des bases, donc les espaces inactifs se ferment d’eux-mêmes et des centaines d’espaces éphémères restent peu coûteux.

Espace
Une base barrel créée par barrel_spaces, avec un nom généré (sp_ et 16 caractères) et un document de registre. Documents, recherche et timeline y fonctionnent tous.
Jeton de capacité
Un jeton bsp_ qui accorde read, write ou admin sur un espace, avec une expiration en option. Il est affiché une seule fois ; seul son hachage SHA-256 est conservé.
Session
Un contexte de travail pour un agent dans un espace : messages dans l’ordre, données structurées, contexte épinglé. Son TTL glisse à chaque changement, ou elle n’expire jamais.
Passation
Une tâche transmise à un autre agent sous forme de jeton. Celui qui le détient l’accepte, obtient une session dans le même espace et lit sur place le contexte de l’expéditeur.
Point d’accès MCP
39 outils sur /mcp dans barrel_server : documents, BQL, recherche, branches, espaces, sessions, passations et contextes, avec le jeton vérifié outil par outil.

Comment un jeton est vérifié

barrel_server lit le jeton à chaque requête. Un jeton de capacité ne passe que sur les routes de son propre espace et sur les routes agents, avec le droit qui lui a été accordé : la lecture couvre les GET, les requêtes, la recherche et le côté pull de la synchronisation ; l’écriture y ajoute l’écriture de documents et le côté push.

  1. Agent client MCP ou HTTP

    Authorization: Bearer bsp_...

  2. barrel_server vérifie l’octroi : espace et droit

    autorisé : lecture, ou lecture et écriture

  3. Space sp_... documents, sessions, recherche

Comment une passation transmet une tâche

  1. Alice une session dans l’espace

    handoff_create : un jeton, une fois

  2. Jeton détenu par Bob

    handoff_accept : le premier gagne

  3. Bob sa propre session, même espace

    handoff_complete

  4. Terminé jeton révoqué
Rien n’est copié : Bob lit la session et les documents d’Alice dans l’espace partagé.

Ce qui tient, et ce qui le vérifie

En REST et en MCP. Dans votre propre nœud, lisez la première limite plus bas.

Un jeton ouvre un espace, avec un jeu de droits

Un jeton de lecture ne peut pas écrire, ne peut pas toucher un autre espace, ni créer, supprimer ou brancher des bases. Les routes non associées à un droit le refusent.

Vérifié par barrel_server_auth_SUITE : t_capability_read_scope, t_capability_wrong_space, t_capability_fail_closed ; barrel_caps_SUITE, t_rights_ladder.

La révocation prend effet à la requête suivante

Un jeton révoqué ou expiré reçoit 401. Supprimer un espace révoque tous ses octrois.

Vérifié par t_revoked_401 dans barrel_server_spaces_SUITE, t_revoke et t_drop_space_revokes dans barrel_caps_SUITE.

Une passation n’est acceptée qu’une fois

L’acceptation fait passer la passation de pending à accepted par un compare-and-set ; une seconde acceptation reçoit already_accepted. Terminer la passation révoque le jeton par défaut.

Vérifié par t_double_accept et t_complete_revokes dans barrel_handoff_SUITE.

Les sessions expirent d’elles-mêmes

Une session expirée est aussitôt lue comme introuvable ; le balayeur de TTL la marque supprimée et un processus de nettoyage ramasse ses messages. Une session avec ttl => infinity n’expire jamais.

Vérifié par barrel_session_SUITE : t_sliding_ttl, t_janitor_orphans, t_no_ttl_durable.

Les jetons ne sont jamais en clair sur le disque

Le registre conserve un hachage de chaque jeton. Lister les octrois ne renvoie jamais les hachages.

Vérifié par t_hash_stored_as_hex et t_list_strips_hashes dans barrel_caps_SUITE.

Les refus MCP reviennent comme résultats d’outil

Un appel d’outil hors de l’octroi renvoie isError: true avec une raison que l’agent peut lire, pas une erreur de protocole.

Vérifié par t_capability_denies dans barrel_server_mcp_agent_SUITE.

L’utiliser

Créer un espace et accorder un jeton de lecture

{ok, #{id := SpaceId, db := Db}} =
    barrel_spaces:create_space(#{label => <<"joint research">>,
                                 vectordb => none}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"notes">>,
                               <<"text">> => <<"draft v1">>}),
{ok, ReadTok, _Grant} = barrel_caps:grant(SpaceId,
    #{rights => [read], subject => <<"carol">>}),
barrel_caps:verify(ReadTok, SpaceId, write).
Sortie du dernier appel Erlang (un jeton de lecture qui demande l’écriture), enregistrée sur barrel_spaces 1.3.1
{error,forbidden}

Tenir une session

{ok, Sid} = barrel_session:create(Space,
    #{agent => <<"alice">>, ttl => 1800}),
{ok, _} = barrel_session:add_message(Space, Sid,
    #{role => <<"user">>, content => <<"draft is half done">>}),
{ok, _} = barrel_session:set_data(Space, Sid, <<"cursor">>, 42),
{ok, _} = barrel_session:pin_context(Space, Sid,
    #{content => <<"deadline friday">>, priority => 0}),
{ok, Msgs} = barrel_session:get_messages(Space, Sid,
    #{limit => 50, order => desc}).

Passer la tâche à un autre agent

{ok, #{token := HTok}} = barrel_handoff:create(Space, #{
    task_name => <<"finish the draft">>,
    from_agent => <<"alice">>, to_agent => <<"bob">>,
    from_session => Sid,
    pending => [<<"polish conclusion">>]}),

%% bob, holding only the token
{ok, #{space := BobSpace, session := BobSid}} =
    barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
{ok, _} = barrel_handoff:complete(HTok,
                                  #{result => <<"shipped">>}).
Lignes affichées par le déroulé Erlang enregistré (abrégé)
accepted: {<<"accepted">>,<<"bob">>}
second accept: {error,already_accepted}
bob reads alice's messages: [<<"draft is half done">>]
handoff token after complete: {error,revoked}

Activer le point d’accès MCP

Il est actif par défaut dans le build du serveur. Un jeton serveur a un accès complet ; un jeton de capacité est limité à son espace et à ses droits.

sys.config
{barrel_server, [
    {auth, #{tokens => [<<"server-token">>]}},
    {mcp, #{enabled => true,
            allowed_origins => any,
            resources => full}}
]}

Limites

  • Dans votre propre nœud Erlang, les jetons ne sont vérifiés que là où le code appelle barrel_caps:verify/3. barrel_spaces:open_space/1 et les appels barrel_session ne prennent pas de jeton, donc tout code de la VM peut ouvrir n’importe quel espace. barrel_server et /mcp appliquent les jetons ; dans le processus, le chiffrement par espace est la frontière d’isolation.
  • Dans barrel_handoff, accept, complete et chain ne vérifient que le droit read, donc un jeton de passation en lecture seule peut terminer ou enchaîner.
  • Accorder, révoquer et créer des passations depuis Erlang ne demande aucun jeton : le droit admin n’est appliqué que par les routes du serveur.
  • Les espaces chiffrés ne sont accessibles que par l’API Erlang, pas en REST ni en MCP.
  • Le magasin de vecteurs d’un espace vit sur chaque nœud et n’est pas répliqué. Les octrois vivent dans la base de registre, donc une révocation atteint les autres nœuds au rythme de la réplication.
  • /mcp n’accepte que des jetons bearer, serveur ou de capacité ; les requêtes signées et mTLS ne s’y appliquent pas. Les réponses à tools/call arrivent en server-sent events.
  • Les contextes sur plusieurs bases demandent un LIMIT (1000 au plus) et ne fusionnent pas les scores BM25 ou hybrides entre contextes ; la fédération en direct est prévue.

Les bibliothèques derrière

Haut et bas pour se déplacerEntrée pour ouvrir