Barrel
FR GitHub

barrel_spaces

Give each agent, team or task its own database, and share it by handing out a token. Sessions hold an agent's working memory for a while; a handoff passes a task, and the rights to finish it, to another agent.

What it solves

Several agents working on shared data need separate databases, a way to give one agent read access and another write access, short-lived working memory, and a clean way to pass unfinished work along. barrel_spaces adds those pieces on top of barrel databases.

When to use it

  • Several agents work on the same data and each should only read or write what it was given.
  • An agent needs a conversation log, scratch data and pinned notes that expire on their own.
  • One agent starts a task and another finishes it, with what was done and what is left.

When not to

  • You only need one database for one application: use barrel directly. Spaces add the sharing and session layer on top of it.
  • You need isolation between Erlang processes on the same node: tokens do not give you that (see limits); use per-space encryption.

How it fits into Barrel

Other dependencies
none beyond the Barrel libraries
On its own
No. A space is a barrel database, so barrel and barrel_docdb come with it.

How a handoff moves through a space

Alice works in a space, hands the task to Bob, and Bob finishes it. Carol only holds a read token. This is the verified run below, step by step.

  1. Create a space

    A new barrel database, registered under an id.

    barrel_spaces:create_space/1
  2. Grant a token

    Carol gets read rights on this space only.

    barrel_caps:grant/2
  3. Hand off

    Alice passes the task, her session and what is pending.

    barrel_handoff:create/2
  4. Accept, then complete

    Bob reads Alice's notes and messages, finishes, and the token is revoked.

    barrel_handoff:accept/2
Whoreadwriteadmin
Carolokforbiddenforbidden*
Handoff tokenok*okforbidden
Any token, other spacewrong_spacewrong_space*wrong_space*

Results of barrel_caps:verify/3. Cells marked with an asterisk were not called in the run; they follow from the rights ladder read < write < admin in barrel_caps.erl. The handoff token is revoked once Bob completes the task.

Install

rebar.config deps
{barrel_spaces, "~> 2.0"}

Configuration

create_space/1 options

KeyDefaultWhat it does
label, purpose, owner none Stored in the registry document
session_ttl 3600 s Default TTL of sessions in this space
ttl_sweep_interval 60000 ms How often expired sessions are swept
vectordb a vector store none for documents only, or a store config map
encryption disabled default or #{provider => Mod}; the in-process isolation boundary
embedding none Record-mode policy for the space database

App env (barrel_spaces)

KeyDefaultWhat it does
registry_db _barrel_spaces Database holding spaces, grants and handoffs
janitor_interval 300000 ms Registry cleanup interval
embedder none Embedder used to reopen record-mode spaces

The most used keys only. For every option, see the configuration reference and the API reference.

The API by task

Spaces

TaskCallReturns
Create a space barrel_spaces:create_space/1 {ok, #{id, db}}
Open, close barrel_spaces:open_space/1,2, close_space/1 {ok, Space}, or space_dropped, not_found, db_is_encrypted
Drop (revokes every grant) barrel_spaces:drop_space/1,2 ok
List, describe barrel_spaces:list_spaces/0, space_info/1 registry documents

Capability tokens

TaskCallReturns
Issue a token barrel_caps:grant/2 {ok, Token, Grant}; the token is shown once
Check a right barrel_caps:verify/3 {ok, Grant} or invalid_token, revoked, expired, wrong_space, forbidden
Revoke barrel_caps:revoke/1, revoke_all/1 ok
Who holds it barrel_caps:auth_context/1, list/1 {ok, #{space, subject, rights, scopes}}

Sessions

TaskCallReturns
Start a session barrel_session:create/1,2 {ok, Sid}
Keep it alive barrel_session:touch/2 {ok, _}
Log a message barrel_session:add_message/3 {ok, _}
Read messages barrel_session:get_messages/2,3 {ok, [Msg]}; options limit, order, since, before
Scratch data, pins set_data/4, get_data/3, pin_context/3, list_pinned/2 {ok, _}

Handoffs

TaskCallReturns
Hand off a task barrel_handoff:create/2 {ok, #{handoff_id, token}}
Accept it barrel_handoff:accept/2 {ok, #{handoff, space, session}}
Finish it barrel_handoff:complete/2 {ok, Handoff}; revokes the token by default
Pass it on barrel_handoff:chain/2 a new handoff, instead of completing
Find handoffs barrel_handoff:list/1, get/1 handoff documents

The flow, in code

Run with the barrel_spaces application started and barrel_docdb data_dir set.

spaces_demo.erl (abridged)
%% 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)).
Output, from a run on barrel_spaces 1.3.1 (lines for the calls shown)
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}

The same steps over REST and MCP

Calls only, against an open server. The create and grant calls were run live with these answers; the handoff calls are written from the route handlers and the registered tool schemas.

# 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"}'

Limits to know

  • Tokens are checked by the server, over REST and MCP. Inside your own Erlang node, open_space/1 and every barrel_session call take no token, so any code can open any space (verified). Use per-space encryption if processes must not read each other's data.
  • Accepting, completing or chaining a handoff only checks the read right on its token.
  • A space's vector store lives on one node, at <data_dir>/<id>_vec, and is not replicated.
  • Encrypted spaces can be opened through the Erlang API only, not over REST or MCP.
  • chain/2 and complete/2 are alternatives: after complete, the token is revoked and chain fails.

Up and down to moveEnter to open