barrel_handoff (barrel_spaces v1.0.0)
View SourceHandoffs: transfer work between agents as a shared space plus a capability. Creating a handoff issues a grant for the space and returns the token once; POSSESSION OF THE TOKEN IS THE RIGHT TO ACCEPT (barrel_memory's handoffs let any authenticated caller accept anything; this closes that hole). Accepting flips the handoff doc pending -> accepted with a rev CAS (double accepts lose), opens the shared space, and creates a session for the acceptor IN it: context is read in place, no snapshot copying.
Handoff docs live in the _barrel_spaces registry, so pending handoffs are discoverable with folds and the registry's changes feed. Completing revokes the grant by default; chaining mints a new handoff plus grant carrying parent/root lineage.
Summary
Functions
Accept a handoff by presenting its token. Opts: agent (the acceptor's name), open_opts (runtime open options for the space, e.g. its encryption spec), session (map passed to barrel_session:create). Returns the shared space handle and a fresh session in it; the from-agent's context is read in place.
Chain: hand the task on. Creates a new handoff (and grant) in the same space carrying the lineage; the presented token's handoff is marked completed (not revoked by default so the chainer can keep working; pass revoke => true to cut it).
Complete a handoff. Opts: result (term), notes (binary), revoke (revoke the grant, default true).
Create a handoff for a space. Opts: task_name (required), from_agent, to_agent (advisory routing labels), from_session, context (binary or map), completed/pending/blockers/files (lists), priority, rights (grant rights, default [read, write]), expires_at (grant expiry, unix ms). Returns the handoff id and the capability token, shown once.
One handoff by id.
Handoffs filtered by to_agent, from_agent, status, space (all optional).
Functions
-spec accept(binary(), map()) -> {ok, #{handoff := map(), space := barrel_spaces:space(), session := binary()}} | {error, term()}.
Accept a handoff by presenting its token. Opts: agent (the acceptor's name), open_opts (runtime open options for the space, e.g. its encryption spec), session (map passed to barrel_session:create). Returns the shared space handle and a fresh session in it; the from-agent's context is read in place.
-spec chain(binary(), map()) -> {ok, #{handoff_id := binary(), token := binary()}} | {error, term()}.
Chain: hand the task on. Creates a new handoff (and grant) in the same space carrying the lineage; the presented token's handoff is marked completed (not revoked by default so the chainer can keep working; pass revoke => true to cut it).
Complete a handoff. Opts: result (term), notes (binary), revoke (revoke the grant, default true).
-spec create(binary() | barrel_spaces:space(), map()) -> {ok, #{handoff_id := binary(), token := binary()}} | {error, term()}.
Create a handoff for a space. Opts: task_name (required), from_agent, to_agent (advisory routing labels), from_session, context (binary or map), completed/pending/blockers/files (lists), priority, rights (grant rights, default [read, write]), expires_at (grant expiry, unix ms). Returns the handoff id and the capability token, shown once.
One handoff by id.
Handoffs filtered by to_agent, from_agent, status, space (all optional).