Espaces, sessions et passations
La couche agents : un espace est une base barrel créée via barrel_spaces,
partagée en détenant un jeton de capacité pour elle. Les sessions donnent aux
agents un contexte de travail avec un TTL glissant dans un espace ; une
passation transfère un travail à un autre agent sous forme d’un jeton dont la
possession donne le droit d’accepter. Lisez ce guide si vous coordonnez
plusieurs agents sur un contexte partagé.
Quand l’utiliser
- Plusieurs agents doivent lire et écrire le même contexte sans le copier.
- Vous voulez un accès révocable, par espace, plutôt qu’un seul identifiant global.
- Des agents se passent des tâches et celui qui reçoit doit voir le contexte de l’émetteur sur place.
Espaces et jetons de capacité
Un espace est une base avec un nom généré (sp_ + 16 caractères) plus un
document de registre dans la base système _barrel_spaces. Les bases d’espace
s’ouvrent via le gestionnaire de cycle de vie des bases de Barrel : les espaces
inactifs se ferment d’eux-mêmes et des centaines d’espaces éphémères restent peu
coûteux.
{ok, _} = application:ensure_all_started(barrel_spaces),
{ok, #{id := SpaceId, db := Db}} = barrel_spaces:create_space(#{
label => <<"joint research">>,
session_ttl => 3600 %% TTL de session par défaut, en secondes
}),
%% Db est un handle barrel ordinaire : documents, recherche, timeline fonctionnent
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"notes">>}),
%% accorder l'accès : le jeton n'est montré qu'une fois, seul son hash est stocké
{ok, Token, _Grant} = barrel_caps:grant(SpaceId, #{
rights => [read, write], %% read < write < admin
subject => <<"agent-bob">>}),
%% le détenteur vérifie (ou résout un contexte d'authentification)
{ok, _} = barrel_caps:verify(Token, SpaceId, write),
{ok, #{space := SpaceId, rights := _}} = barrel_caps:auth_context(Token),
%% révoquer un accès, ou supprimer l'espace (révoque tout)
ok = barrel_caps:revoke(Token),
ok = barrel_spaces:drop_space(SpaceId).
open_space/2 rouvre un espace existant ; les options d’exécution (une
spécification encryption, une configuration de stockage supplémentaire)
doivent être repassées à chaque ouverture, exactement comme pour toute base
barrel.
Un espace en mode enregistrement
Donnez à create_space/1 une politique embedding et l’espace indexe les
champs que vous nommez, comme toute base en mode enregistrement (voir
embedding) :
Embedder = {ollama, #{model => <<"nomic-embed-text">>}},
{ok, #{id := SpaceId}} = barrel_spaces:create_space(#{
embedding => #{fields => [<<"text">>], mode => sync,
embedder => Embedder}}).
Le document d’espace enregistre les champs de la politique et l’identité de l’embedder (fournisseur, modèle, dimensions, distance, empreinte), pas la configuration de l’embedder : le registre est répliqué, et une configuration peut contenir des chemins et des clés d’API. Chaque nœud qui ouvre l’espace fournit sa propre configuration pour le même modèle :
application:set_env(barrel_spaces, embedder, Embedder),
{ok, #{db := Db}} = barrel_spaces:open_space(SpaceId).
L’ouverture vérifie d’abord l’empreinte. Un autre modèle répond
{error, {embedder_mismatch, _}} ; l’absence d’env embedder répond
{error, {embedder_required, Fingerprint}}. Un espace atteint via barrel_server
(ses routes /db et de synchronisation) s’ouvre de la même façon, donc la
première route qui le touche ne décide pas de son mode. L’isolation repose sur
des clés de chiffrement par espace : voir encryption.
Sessions
Une session est un document d’en-tête de la base d’espace écrit avec un TTL ; chaque modification le fait glisser. Chaque clé de données, chaque épingle, le résumé et les compteurs de chaque réplique sont des documents à part, et les messages sont des documents dont les ids se trient chronologiquement. Une session expirée disparaît immédiatement des lectures et son en-tête reçoit une pierre tombale du balayeur TTL de l’espace ; un janitor collecte ensuite ses documents orphelins.
{ok, Space} = barrel_spaces:open_space(SpaceId),
{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, Messages} = barrel_session:get_messages(Space, Sid,
#{limit => 50, order => desc}),
{ok, _ExpiresAt} = barrel_session:touch(Space, Sid),
%% état de travail structuré et contexte épinglé
{ok, _} = barrel_session:set_data(Space, Sid, <<"cursor">>, 42),
{ok, _} = barrel_session:delete_data(Space, Sid, <<"cursor">>),
{ok, PinId} = barrel_session:pin_context(Space, Sid,
#{content => <<"key fact">>,
priority => 0}),
{ok, Pinned} = barrel_session:list_pinned(Space, Sid),
{ok, _} = barrel_session:unpin_context(Space, Sid, PinId),
%% compteurs : aucun incrément n'est perdu quand deux nœuds comptent en même temps
{ok, 21} = barrel_session:incr_counter(Space, Sid, <<"messages">>, 1),
{ok, #{<<"messages">> := 21}} = barrel_session:get_counters(Space, Sid),
ok = barrel_session:delete(Space, Sid). %% supprime aussi tous les documents
Un compteur ne monte ou ne descend que des quantités que vous ajoutez. Pour compter « les messages depuis la dernière extraction », gardez le compteur de messages et stockez son total au moment de la dernière extraction dans une clé de données : la différence donne le nombre depuis.
Sessions durables
Passez ttl => infinity (ou 0) pour créer une session qui n’expire jamais : un
enregistrement, pas un cache. Les modifications renvoient alors {ok, 0} au lieu
d’une heure d’expiration, et le balayeur TTL l’ignore.
{ok, Rec} = barrel_session:create(Space, #{agent => <<"alice">>,
ttl => infinity}),
{ok, 0} = barrel_session:touch(Space, Rec).
Listage filtré
list/2 filtre via les index de chemins de la base d’espace : un espace qui
contient des milliers de sessions ne paie pas un parcours complet.
{ok, Mine} = barrel_session:list(Space, #{
match => #{<<"data.user_id">> => <<"u1">>}, %% n'importe quel chemin de champ
agent => <<"alice">>, %% se combine avec match
limit => 50}).
Importer un corpus existant
Les sessions et les messages arrivent avec leurs propres ids et horodatages ; le module reste maître du schéma des documents :
{ok, _} = barrel_session:create(Space, #{id => <<"legacy-1">>}),
{ok, _} = barrel_session:import_session(Space, #{
id => <<"legacy-2">>, agent => <<"old-bot">>,
data => #{<<"user_id">> => <<"u1">>},
created_at => 1750000000000, updated_at => 1750000100000}),
%% pour les imports, le ttl vaut jamais par défaut ; ttl > 0 démarre à updated_at
{ok, _} = barrel_session:import_message(Space, <<"legacy-2">>, #{
role => <<"user">>, content => <<"hello">>,
ts => 1750000050000, id => <<"msg-legacy-1">>}), %% pas de glissement du TTL
%% les épingles gardent aussi leur id, leur horodatage et leurs métadonnées
{ok, _} = barrel_session:pin_context(Space, <<"legacy-2">>, #{
id => <<"pin-legacy-1">>, content => <<"key fact">>,
pinned_at => 1750000060000, metadata => #{<<"src">> => <<"v1">>}}).
Un id d’appelant en double échoue avec {error, conflict} (un id de session à
la création, un id de message à l’import, un id d’épingle à l’épinglage),
jamais en silence.
TTL des documents (le mécanisme sous-jacent)
Les sessions reposent sur une primitive générale qui fonctionne sur toute base
barrel : l’option d’écriture expires_at (ms unix). Les documents expirés se
lisent immédiatement comme introuvables ; un balayeur optionnel par base les
transforme en vraies pierres tombales (pour que la réplication et les branches
restent correctes).
{ok, _} = barrel:put_doc(Db, Doc, #{expires_at => Now + 60000}),
%% absent = conserver l'expiration actuelle, 0 = l'effacer
{ok, Swept} = barrel_docdb:sweep_ttl(DbName).
Activez le balayeur avec ttl_sweep_interval (ms) dans la configuration docdb
de la base ; les espaces le règlent à 60000 par défaut.
Passations
Une passation est un espace partagé plus une capacité. En créer une émet un accès et renvoie le jeton une seule fois ; quiconque détient le jeton accepte. Accepter enregistre celui qui accepte (une deuxième acceptation est refusée), ouvre l’espace et y crée une session pour celui qui accepte : le contexte est lu sur place, rien n’est copié.
{ok, #{handoff_id := Hid, token := HandoffToken}} =
barrel_handoff:create(Space, #{
task_name => <<"finish the draft">>,
from_agent => <<"alice">>, to_agent => <<"bob">>,
from_session => Sid,
pending => [<<"polish conclusion">>]}),
%% bob, qui ne détient que le jeton :
{ok, #{handoff := H, space := BobSpace, session := BobSid}} =
barrel_handoff:accept(HandoffToken, #{agent => <<"bob">>}),
%% ou accepter sur la seule discipline du jeton (aucun espace ouvert, aucune
%% session créée), pour les consommateurs qui ont leur propre modèle de session :
%% {ok, #{handoff := H2}} =
%% barrel_handoff:accept(HandoffToken, #{agent => <<"bob">>,
%% session => false}),
%% le travail se fait dans l'espace partagé, puis :
{ok, _} = barrel_handoff:complete(HandoffToken,
#{result => <<"shipped">>}),
%% la complétion révoque le jeton par défaut
%% ou la transmettre, en gardant la lignée (parent/root/depth)
{ok, #{token := NextToken}} = barrel_handoff:chain(HandoffToken, #{
task_name => <<"review the draft">>, to_agent => <<"carol">>}).
Les documents de passation vivent dans la base de registre : les passations en
attente se découvrent avec barrel_handoff:list/1 (filtres : space, status,
to_agent, from_agent) ou en s’abonnant au flux de changements du registre.
Chaque étape est un document écrit une seule fois : la passation à la création,
une acceptation par agent, la complétion. Le statut est l’étape la plus avancée
présente.
Répliquer un espace et son registre
Répliquez le registre et une base d’espace entre nœuds comme n’importe quelle
base barrel. Chaque fait d’accès, de session et de passation est un document
écrit une seule fois ou remplacé en entier : la version que montre chaque nœud
est donc déjà la réponse. barrel_spaces ouvre le registre et ses espaces avec
barrel_spaces_resolver, qui clôt chaque conflit sur ces documents en
choisissant cette version, de la même façon sur chaque nœud :
- Une révocation est un document
revoke:à part. Un accès modifié ailleurs ne peut pas l’annuler, et deux nœuds qui révoquent le même jeton sont d’accord. - Deux nœuds qui écrivent des clés, des épingles ou le résumé différents d’une même session gardent les deux écritures. La même clé écrite sur deux nœuds garde l’écriture la plus récente.
- Retirer une clé de données ou une épingle se réplique comme une suppression : un nœud qui détient encore l’ancienne copie ne peut pas la faire revenir.
- Une passation ne revient jamais de completed à accepted, ni de accepted à
pending. Quand deux agents l’acceptent sur des nœuds qui ne se voient pas,
les deux acceptations sont gardées et chaque nœud désigne le même
propriétaire : le
accepted_atle plus ancien, puis le nom de l’agent. - Les compteurs sont par réplique et additionnés : aucun incrément n’est perdu.
%% nœud A
ok = barrel_caps:revoke(TokenId, #{by => <<"ops">>}),
%% nœud B, après réplication
{error, revoked} = barrel_caps:verify(Token, SpaceId, read),
{ok, [#{<<"revoked_by">> := <<"ops">>}]} = barrel_caps:list(SpaceId).
Votre propre résolveur de conflits
Une base d’espace contient aussi vos documents. Passez votre résolveur avec
docdb => #{conflict_resolver => {M, F}} à create_space/1 ou
open_space/2 : barrel_spaces l’enveloppe, traite les documents session: et
confie tous les autres documents au vôtre. Si vous ouvrez vous-même le registre
ou une base d’espace, définissez {barrel_spaces_resolver, registry} sur le
registre, et barrel_spaces_resolver:with({M, F}) (ou {barrel_spaces_resolver, space}) sur un espace. Comme pour tout résolveur, chaque nœud doit exécuter le
même.
Mettre à jour depuis 1.x
2.0 stocke les accès, les sessions et les passations autrement, et demande barrel_docdb 3.1. Des nœuds qui exécutent les deux versions ne s’accordent pas. Mettez donc à jour tous les nœuds du maillage dans cet ordre :
- Mettez à jour barrel_docdb en 3.1 sur chaque nœud. Vous pouvez le faire un nœud à la fois : le protocole de réplication ne change pas, et un nœud 3.1 refuse les versions mélangées qu’un nœud 3.0 envoie encore. Chaque base convertit son historique de versions la première fois que 3.1 l’ouvre, en un seul passage, et journalise combien de lignes elle a déplacées et combien de documents elle a réparés.
- Arrêtez d’écrire via barrel_spaces, ou arrêtez de répliquer le registre et les bases d’espace.
- Mettez à jour barrel_spaces en 2.0 (et barrel_server en 1.15.1) sur chaque nœud.
- Sur un nœud, lancez
barrel_spaces:migrate/0. Il convertit le registre et chaque espace qui s’ouvre sans options d’exécution, et liste les autres dansskipped. Ouvrez chaque espace ignoré (un espace chiffré avec sa clé) et lancezbarrel_session:migrate/1. - Reprenez la réplication. Les autres nœuds reçoivent les documents convertis.
- Reprenez les écritures.
{ok, #{grants := G, handoffs := H, sessions := S, skipped := Skipped}} =
barrel_spaces:migrate(),
[begin
{ok, Space} = barrel_spaces:open_space(Id, #{encryption => Spec}),
{ok, _} = barrel_session:migrate(Space)
end || Id <- Skipped].
Les documents que vous ne convertissez pas se lisent de la même façon, et se convertissent à leur prochaine écriture.
Ce qui se passe mal si vous sautez l’étape 2 et qu’un nœud 1.x continue d’écrire :
| Sur un nœud 1.x | Effet |
|---|---|
| Vérifier un jeton | Il ignore les documents revoke: et accepte un jeton révoqué sur un nœud 2.0. |
| Lire une session | Il ne trouve aucune donnée, épingle ni résumé écrits par 2.0. |
set_data/4 sur une clé existante | 2.0 continue d’afficher sa propre valeur ; seules les nouvelles clés apparaissent. |
unpin_context/3 | L’épingle revient sur les nœuds 2.0. |
| Accepter une passation | Une passation acceptée sur 2.0 paraît en attente : une deuxième acceptation réussit et le propriétaire peut changer. |
Une révocation 1.x tient toujours sur les nœuds 2.0, qui lisent les deux formats.
Il n’y a pas de retour en arrière : 1.x ne sait pas lire les sessions converties, et une base ouverte par barrel_docdb 3.1 perd ses conflits et ses versions passées sous 3.0.
Sur REST et MCP
barrel_server expose tout cela sous /spaces et /handoffs ; les jetons de
capacité y fonctionnent comme bearers (et seulement là). Voir
rest-server. Les mêmes opérations existent comme
outils MCP (space_*, session_*, handoff_*) ; voir mcp.
Notes
- Échelle des droits :
read < write < admin. Admin couvre l’octroi, la révocation et l’émission de passations. La vérification est locale (le registre est une base sur le même nœud) ; les jetons sont aléatoires, stockés hachés, comparés en temps constant. - Le nom de la base de registre vient de l’env
registry_dbde l’applicationbarrel_spaces(par défaut_barrel_spaces) ; définissez-le avant la première utilisation. Le registre est une base barrel ordinaire : l’ouvrir viabarrel_dbsà côté de cette couche est pris en charge. - Répliquer le registre est voulu. Les documents d’accès sont un état d’autorisation : c’est la réplication qui permet à un jeton émis sur un nœud d’être vérifié sur un autre ; en contrepartie, la révocation se propage à la vitesse de la réplication. Gardez une réplication du registre serrée si la latence de révocation compte pour vous.
- Le stockage vectoriel d’un espace est propre à chaque nœud. Il vit dans
<data_dir>/<space id>_vec, résolu à chaque ouverture depuis ledata_dirlocal debarrel_docdb, donc un document d’espace répliqué s’ouvre sur n’importe quel nœud. Répliquer le registre transporte les métadonnées et les accès, pas la mémoire : les vecteurs restent sur le nœud qui les a écrits. Unvectordb => #{db_path => ...}personnalisé donné à la création est conservé tel quel et doit exister sur chaque nœud qui ouvre l’espace. barrel_caps:grant/2n’exige pas que l’espace existe. Accorder sur une portée purement logique (un id de tenant, un id de passation) est pris en charge : des jetons révocables, hachés au repos, avec échelle de droits, sans base d’espace derrière eux.- Le registre (
_barrel_spaces) contient les documents d’espace, d’accès, de révocation et de passation comme des documents ordinaires : les folds et le flux de changements les voient. - Un espace chiffré a besoin de sa spécification de chiffrement à chaque
ouverture, y compris dans
barrel_handoff:accept/2(passezopen_opts). Sur REST et MCP, les espaces s’ouvrent avec les options par défaut : les espaces chiffrés ne sont donc accessibles que par l’API Erlang en v1. barrel_spaces_janitorbalaie périodiquement les documents de session orphelins des espaces ouverts (janitor_interval, 5 minutes par défaut) ;barrel_spaces_janitor:sweep/0lance un passage immédiatement.