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
- Repose sur
barrel,barrel_docdb,barrel_crypto- 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.
-
Créer un espace
Une nouvelle base barrel, enregistrée sous un identifiant.
barrel_spaces:create_space /1 -
Accorder un jeton
Carol reçoit des droits de lecture sur cet espace seulement.
barrel_caps:grant /2 -
Transmettre
Alice transmet la tâche, sa session et ce qui reste à faire.
barrel_handoff:create /2 -
Accepter, puis terminer
Bob lit les notes et les messages d’Alice, termine, et le jeton est révoqué.
barrel_handoff:accept /2
| Qui | read | write | admin |
|---|---|---|---|
| Carol | ok | forbidden | forbidden* |
| Jeton de passation | ok* | ok | forbidden |
| Tout jeton, autre espace | wrong_space | wrong_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
{barrel_spaces, "~> 2.0"} Configuration
Options de create_space/1
| Clé | Défaut | Rô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éfaut | Rô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âche | Appel | Renvoie |
|---|---|---|
| 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âche | Appel | Renvoie |
|---|---|---|
| É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âche | Appel | Renvoie |
|---|---|---|
| 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âche | Appel | Renvoie |
|---|---|---|
| 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.
%% 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)). 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"}' {"name": "space_create",
"arguments": {"label": "joint research",
"owner": "alice"}}
{"name": "space_grant",
"arguments": {"space": "sp_...", "rights": ["read"],
"subject": "carol"}}
{"name": "handoff_create",
"arguments": {"space": "sp_...",
"task_name": "finish the draft",
"from_agent": "alice", "to_agent": "bob"}}
{"name": "handoff_accept",
"arguments": {"token": "bsp_...", "agent": "bob"}}
{"name": "handoff_complete",
"arguments": {"token": "bsp_...", "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/1et tous les appelsbarrel_sessionne 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/2etcomplete/2s’excluent : aprèscomplete, le jeton est révoqué etchainéchoue.