Barrel
EN GitHub

barrel_spaces

Donnez à chaque agent, équipe ou tâche sa propre base de données, et partagez-la en remettant un jeton. Les sessions gardent pour un temps la mémoire de travail d’un agent ; une passation transmet une tâche, et les droits pour la terminer, à un autre agent.

Ce qu’elle résout

Plusieurs agents qui travaillent sur des données communes ont besoin de bases séparées, d’un moyen de donner à un agent l’accès en lecture et à un autre l’accès en écriture, d’une mémoire de travail de courte durée, et d’une façon propre de transmettre un travail inachevé. barrel_spaces ajoute ces pièces au-dessus des bases barrel.

Quand l’utiliser

  • Plusieurs agents travaillent sur les mêmes données et chacun ne doit lire ou écrire que ce qu’on lui a donné.
  • Un agent a besoin d’un journal de conversation, de données de travail et de notes épinglées qui expirent d’elles-mêmes.
  • Un agent commence une tâche et un autre la termine, avec ce qui a été fait et ce qui reste à faire.

Quand ne pas l’utiliser

  • Vous n’avez besoin que d’une base pour une application : utilisez directement barrel. Les espaces ajoutent par-dessus la couche de partage et de sessions.
  • Vous avez besoin d’isoler des processus Erlang sur le même nœud : les jetons ne le permettent pas (voir les limites) ; utilisez le chiffrement par espace.

Sa place dans Barrel

Utilisée par
barrel_server
Autres dépendances
aucune en dehors des bibliothèques Barrel
Seule
Non. Un espace est une base barrel, donc barrel et barrel_docdb viennent avec.

Comment une passation traverse un espace

Alice travaille dans un espace, transmet la tâche à Bob, et Bob la termine. Carol ne détient qu’un jeton de lecture. C’est l’exécution vérifiée ci-dessous, étape par étape.

  1. Créer un espace

    Une nouvelle base barrel, enregistrée sous un identifiant.

    barrel_spaces:create_space/1
  2. Accorder un jeton

    Carol reçoit des droits de lecture sur cet espace seulement.

    barrel_caps:grant/2
  3. Transmettre

    Alice transmet la tâche, sa session et ce qui reste à faire.

    barrel_handoff:create/2
  4. Accepter, puis terminer

    Bob lit les notes et les messages d’Alice, termine, et le jeton est révoqué.

    barrel_handoff:accept/2
Quireadwriteadmin
Carolokforbiddenforbidden*
Jeton de passationok*okforbidden
Tout jeton, autre espacewrong_spacewrong_space*wrong_space*

Résultats de barrel_caps:verify/3. Les cases marquées d’un astérisque n’ont pas été appelées pendant l’exécution ; elles découlent de l’échelle des droits read < write < admin dans barrel_caps.erl. Le jeton de passation est révoqué dès que Bob termine la tâche.

Installation

dépendances rebar.config
{barrel_spaces, "~> 2.0"}

Configuration

Options de create_space/1

CléDéfautRôle
label, purpose, owner aucun Enregistrés dans le document du registre
session_ttl 3600 s TTL par défaut des sessions de cet espace
ttl_sweep_interval 60000 ms Fréquence de purge des sessions expirées
vectordb un magasin de vecteurs none pour des documents seuls, ou une table de configuration du magasin
encryption désactivé default ou #{provider => Mod} ; la frontière d’isolation dans le processus
embedding aucune Politique du mode enregistrement pour la base de l’espace

Environnement de l’application (barrel_spaces)

CléDéfautRôle
registry_db _barrel_spaces Base qui contient les espaces, les autorisations et les passations
janitor_interval 300000 ms Intervalle de nettoyage du registre
embedder aucun Embedder utilisé pour rouvrir les espaces en mode enregistrement

Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.

L’API par tâche

Espaces

TâcheAppelRenvoie
Créer un espace barrel_spaces:create_space/1 {ok, #{id, db}}
Ouvrir, fermer barrel_spaces:open_space/1,2, close_space/1 {ok, Space}, ou space_dropped, not_found, db_is_encrypted
Supprimer (révoque toutes les autorisations) barrel_spaces:drop_space/1,2 ok
Lister, décrire barrel_spaces:list_spaces/0, space_info/1 documents du registre

Jetons de capacité

TâcheAppelRenvoie
Émettre un jeton barrel_caps:grant/2 {ok, Token, Grant} ; le jeton n’est montré qu’une fois
Vérifier un droit barrel_caps:verify/3 {ok, Grant} ou invalid_token, revoked, expired, wrong_space, forbidden
Révoquer barrel_caps:revoke/1, revoke_all/1 ok
Qui le détient barrel_caps:auth_context/1, list/1 {ok, #{space, subject, rights, scopes}}

Sessions

TâcheAppelRenvoie
Démarrer une session barrel_session:create/1,2 {ok, Sid}
La garder active barrel_session:touch/2 {ok, _}
Enregistrer un message barrel_session:add_message/3 {ok, _}
Lire les messages barrel_session:get_messages/2,3 {ok, [Msg]} ; options limit, order, since, before
Données de travail, épingles set_data/4, get_data/3, pin_context/3, list_pinned/2 {ok, _}

Passations

TâcheAppelRenvoie
Transmettre une tâche barrel_handoff:create/2 {ok, #{handoff_id, token}}
L’accepter barrel_handoff:accept/2 {ok, #{handoff, space, session}}
La terminer barrel_handoff:complete/2 {ok, Handoff} ; révoque le jeton par défaut
La transmettre à nouveau barrel_handoff:chain/2 une nouvelle passation, au lieu de terminer
Trouver des passations barrel_handoff:list/1, get/1 documents de passation

Le déroulé, en code

À lancer avec l’application barrel_spaces démarrée et le data_dir de barrel_docdb défini.

spaces_demo.erl (abrégé)
%% p(L, V) -> io:format("~s: ~p~n", [L, V]).

{ok, #{id := SpaceId} = Space} =
    barrel_spaces:create_space(#{
        label => <<"joint research">>,
        owner => <<"alice">>, vectordb => none}),
{ok, _} = barrel:put_doc(maps:get(db, Space),
    #{<<"id">> => <<"notes">>, <<"text">> => <<"draft v1">>}),
{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, ReadTok, _Grant} = barrel_caps:grant(SpaceId,
    #{rights => [read], subject => <<"carol">>}),
p("carol verify write",
  barrel_caps:verify(ReadTok, SpaceId, write)),
p("carol on another scope",
  barrel_caps:verify(ReadTok, <<"sp_other">>, read)),
p("tampered token",
  barrel_caps:verify(<<ReadTok/binary, "x">>,
                     SpaceId, read)),

{ok, #{token := HTok}} = barrel_handoff:create(Space, #{
    task_name  => <<"finish the draft">>,
    from_agent => <<"alice">>, to_agent => <<"bob">>,
    from_session => Sid,
    pending    => [<<"polish conclusion">>]}),
p("handoff token verify write",
  element(1, barrel_caps:verify(HTok, SpaceId, write))),
p("handoff token verify admin",
  barrel_caps:verify(HTok, SpaceId, admin)),

{ok, #{handoff := H, space := BobSpace}} =
    barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
p("accepted", {maps:get(<<"status">>, H),
               maps:get(<<"accepted_by">>, H)}),
p("second accept",
  barrel_handoff:accept(HTok, #{agent => <<"mallory">>})),
{ok, Notes} = barrel:get_doc(maps:get(db, BobSpace),
                             <<"notes">>),
p("bob reads notes", maps:get(<<"text">>, Notes)),
{ok, Msgs} = barrel_session:get_messages(BobSpace, Sid),
p("bob reads alice's messages",
  [maps:get(<<"content">>, M) || M <- Msgs]),

{ok, Done} = barrel_handoff:complete(HTok,
    #{result => <<"shipped">>}),
p("completed", maps:get(<<"status">>, Done)),
p("handoff token after complete",
  barrel_caps:verify(HTok, SpaceId, read)),
ok = barrel_caps:revoke(ReadTok),
p("carol after revoke",
  barrel_caps:verify(ReadTok, SpaceId, read)).
Sortie d’une exécution sur barrel_spaces 1.3.1 (lignes des appels montrés)
carol verify write: {error,forbidden}
carol on another scope: {error,wrong_space}
tampered token: {error,invalid_token}
handoff token verify write: ok
handoff token verify admin: {error,forbidden}
accepted: {<<"accepted">>,<<"bob">>}
second accept: {error,already_accepted}
bob reads notes: <<"draft v1">>
bob reads alice's messages: [<<"draft is half done">>]
completed: <<"completed">>
handoff token after complete: {error,revoked}
carol after revoke: {error,revoked}

Les mêmes étapes en REST et en MCP

Appels seulement, sur un serveur ouvert. Les appels de création et d’autorisation ont été exécutés en direct avec ces réponses ; les appels de passation sont écrits d’après les gestionnaires de routes et les schémas d’outils enregistrés.

# open server (no auth configured)
curl -X POST $B/spaces \
  -H 'content-type: application/json' \
  -d '{"label":"joint research","owner":"alice"}'
# 201 {"ok":true,"space":"sp_..."}

curl -X POST $B/spaces/$SPACE/grants \
  -H 'content-type: application/json' \
  -d '{"rights":["read"],"subject":"carol"}'
# 201 {"token":"bsp_...","grant":{...}}

curl -X POST $B/handoffs \
  -H 'content-type: application/json' \
  -d '{"space":"'$SPACE'",
       "task_name":"finish the draft",
       "from_agent":"alice","to_agent":"bob"}'

curl -X POST $B/handoffs/accept \
  -H 'content-type: application/json' \
  -d '{"token":"'$HTOK'","agent":"bob"}'

curl -X POST $B/handoffs/complete \
  -H 'content-type: application/json' \
  -d '{"token":"'$HTOK'","result":"shipped"}'

Limites à connaître

  • Les jetons sont vérifiés par le serveur, en REST et en MCP. Dans votre propre nœud Erlang, open_space/1 et tous les appels barrel_session ne prennent aucun jeton : n’importe quel code peut ouvrir n’importe quel espace (vérifié). Utilisez le chiffrement par espace si des processus ne doivent pas lire les données les uns des autres.
  • Accepter, terminer ou retransmettre une passation ne vérifie que le droit de lecture de son jeton.
  • Le magasin de vecteurs d’un espace vit sur un seul nœud, dans <data_dir>/<id>_vec, et n’est pas répliqué.
  • Les espaces chiffrés ne s’ouvrent que par l’API Erlang, pas en REST ni en MCP.
  • chain/2 et complete/2 s’excluent : après complete, le jeton est révoqué et chain échoue.

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