Barrel
FR GitHub

Share a space between agents

This project runs three agents against one shared space. alice creates the space and starts a task. carol gets a read-only capability token. alice hands the task to bob: bob accepts the handoff, reads alice's notes, messages and pins in place, writes his result and completes the handoff, which revokes its token. At each step the program prints what each agent can and cannot do. Use it when several agents must share context without sharing everything.

Prerequisites

  • Erlang/OTP 26 or later (this run used OTP 29) and rebar3.
  • A C compiler and CMake for the native dependencies (first compile takes a few minutes).

Run

./run.sh

run.sh compiles the project, deletes ./data, then runs agents_handoff:main/0 once.

What it shows

  • barrel_caps:grant/2 issues a token for one space with given rights; barrel_caps:verify/3 answers ok or a reason: forbidden, wrong_space, invalid_token, revoked.
  • barrel_handoff:create/2 issues the handoff as a token (read and write by default, never admin). accept/2 works once: a second accept gets already_accepted.
  • The accepting agent reads the sender's session in place and gets a session of its own that points at the handoff.
  • barrel_handoff:complete/2 revokes the handoff token; barrel_caps:revoke/1 revokes carol's.

Notes

  • In-process, tokens are advisory: barrel_spaces:open_space/1 and the barrel_session functions take no token, so your code calls barrel_caps:verify/3 before it acts, as write_with/4 does here. barrel_server checks tokens on every REST and MCP request.
  • accept, complete and chain check only the read right of the handoff token.
  • Per-space encryption is the isolation boundary inside one node; see the spaces guide.

Expected output

One block per agent with can and cannot lines. The output of a real run is in expected.txt; space and handoff ids differ on every run.

Download The folder on GitHub, with every file below.

Source

src/agents_handoff.erl
%% Two agents share a space: alice owns it, carol gets a read
%% token, bob takes the work over through a handoff.
-module(agents_handoff).
-export([main/0]).

main() ->
    try run() of
        ok -> halt(0)
    catch C:R:S ->
        io:format(standard_error, "~p:~p~n~p~n", [C, R, S]),
        halt(1)
    end.

run() ->
    {ok, _} = application:ensure_all_started(barrel_spaces),

    %% alice creates the space and starts the work.
    {ok, #{id := SpaceId, db := Db} = Space} =
        barrel_spaces:create_space(
            #{label => <<"joint research">>, owner => <<"alice">>,
              vectordb => none}),
    io:format("alice created space ~s~n", [SpaceId]),
    {ok, _} = barrel:put_doc(Db, #{<<"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, _} = barrel_session:pin_context(
        Space, Sid, #{content => <<"deadline friday">>}),

    %% carol gets a read token.
    {ok, ReadTok, _} = barrel_caps:grant(
        SpaceId, #{rights => [read], subject => <<"carol">>}),
    io:format("~ncarol holds a read token~n"),
    can("read the space", barrel_caps:verify(ReadTok, SpaceId, read)),
    can("use it on another space",
        barrel_caps:verify(ReadTok, <<"sp_other">>, read)),
    can("use a tampered token",
        barrel_caps:verify(<<ReadTok/binary, "x">>, SpaceId, read)),
    can("write notes",
        write_with(ReadTok, Space, <<"carol">>, <<"carol was here">>)),

    %% alice hands the task to bob: the token is the handoff.
    {ok, #{token := HTok}} = barrel_handoff:create(Space, #{
        task_name => <<"finish the draft">>,
        from_agent => <<"alice">>, to_agent => <<"bob">>,
        from_session => Sid,
        pending => [<<"polish conclusion">>]}),
    io:format("~nalice handed off \"finish the draft\" to bob~n"),
    {ok, [Pending]} = barrel_handoff:list(
        #{to_agent => <<"bob">>, status => <<"pending">>}),
    io:format("bob's pending handoffs: ~s~n",
              [maps:get(<<"task_name">>, Pending)]),
    can("write with the handoff token",
        barrel_caps:verify(HTok, SpaceId, write)),
    can("administer the space",
        barrel_caps:verify(HTok, SpaceId, admin)),

    %% bob accepts: he gets the space and a session of his own.
    {ok, #{handoff := H, space := BobSpace, session := BobSid}} =
        barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
    io:format("~nbob accepted: ~s by ~s~n",
              [maps:get(<<"status">>, H),
               maps:get(<<"accepted_by">>, H)]),
    can("accept the same handoff again (mallory)",
        barrel_handoff:accept(HTok, #{agent => <<"mallory">>})),

    %% bob reads alice's context in place.
    {ok, Notes} = barrel:get_doc(maps:get(db, BobSpace), <<"notes">>),
    io:format("bob reads notes: ~s~n", [maps:get(<<"text">>, Notes)]),
    {ok, Msgs} = barrel_session:get_messages(BobSpace, Sid),
    io:format("bob reads alice's messages: ~p~n",
              [[maps:get(<<"content">>, M) || M <- Msgs]]),
    {ok, Pins} = barrel_session:list_pinned(BobSpace, Sid),
    io:format("bob reads alice's pins: ~p~n",
              [[maps:get(<<"content">>, P) || P <- Pins]]),
    {ok, BobSession} = barrel_session:get(BobSpace, BobSid),
    io:format("bob's session points at handoff: ~s~n",
              [maps:get(<<"handoff_id">>,
                        maps:get(<<"data">>, BobSession))]),
    can("write notes",
        write_with(HTok, BobSpace, <<"bob">>, <<"draft v2">>)),

    %% bob completes: the token is revoked.
    {ok, Done} = barrel_handoff:complete(
        HTok, #{result => <<"draft v2 ready">>}),
    io:format("~nbob completed: ~s, result ~s~n",
              [maps:get(<<"status">>, Done),
               maps:get(<<"result">>, Done)]),
    can("use the handoff token after completion",
        barrel_caps:verify(HTok, SpaceId, read)),

    %% alice revokes carol.
    ok = barrel_caps:revoke(ReadTok),
    io:format("~nalice revoked carol's token~n"),
    can("read the space (carol)",
        barrel_caps:verify(ReadTok, SpaceId, read)),

    {ok, Final} = barrel:get_doc(Db, <<"notes">>),
    io:format("~nnotes now: ~s (~s)~n",
              [maps:get(<<"text">>, Final),
               maps:get(<<"author">>, Final)]),
    ok = barrel_spaces:close_space(SpaceId),
    ok.

%% Tokens are checked by the code that holds them: in-process, the
%% Erlang API takes no token, so verify before acting. barrel_server
%% does this for every REST and MCP request.
write_with(Token, #{id := SpaceId, db := Db}, Who, Text) ->
    case barrel_caps:verify(Token, SpaceId, write) of
        {ok, _Grant} ->
            {ok, Cur} = barrel:get_doc(Db, <<"notes">>),
            {ok, _} = barrel:put_doc(Db, Cur#{<<"text">> => Text,
                                              <<"author">> => Who}),
            ok;
        {error, _} = Err ->
            Err
    end.

can(What, ok) -> io:format("  can    ~s~n", [What]);
can(What, {ok, _}) -> io:format("  can    ~s~n", [What]);
can(What, {error, Reason}) ->
    io:format("  cannot ~s: ~p~n", [What, Reason]).
rebar.config
{erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"},
        {barrel_spaces, "~> 1.3"}]}.
run.sh
#!/bin/sh
# Build, then run main/0 once on a fresh data directory.
set -e
cd "$(dirname "$0")"
rebar3 compile >&2
rm -rf data
exec erl -noshell -config config/sys \
  -pa _build/default/lib/*/ebin _build/default/checkouts/*/ebin \
  -eval 'agents_handoff:main()'

Expected output

The expected.txt of the example, from a real run. Revisions, ids, tokens and timestamps differ on every run; scripts/verify-examples.sh masks them before it compares.

expected.txt
alice created space sp_rhcq5uxrts6igoq4

carol holds a read token
  can    read the space
  cannot use it on another space: wrong_space
  cannot use a tampered token: invalid_token
  cannot write notes: forbidden

alice handed off "finish the draft" to bob
bob's pending handoffs: finish the draft
  can    write with the handoff token
  cannot administer the space: forbidden

bob accepted: accepted by bob
  cannot accept the same handoff again (mallory): already_accepted
bob reads notes: draft v1
bob reads alice's messages: [<<"draft is half done">>]
bob reads alice's pins: [<<"deadline friday">>]
bob's session points at handoff: ho_26p5x345g6o2f64j
  can    write notes

bob completed: completed, result draft v2 ready
  cannot use the handoff token after completion: revoked

alice revoked carol's token
  cannot read the space (carol): revoked

notes now: draft v2 (bob)

Up and down to moveEnter to open