Raxol.Agent.Sandbox protocol (Raxol Agent v2.6.0)

Multi-dimensional isolation protocol for agent operations.

Each Sandbox struct is a declarative statement about what an agent may do along one dimension (Shell, SendAgent, Async, ...). Implementations return :ok to allow, {:deny, reason} to block, or :ok as an abstention when the action is outside the sandbox's dimension. Walking a list of sandboxes (via Raxol.Agent.Sandbox.authorize_chain/4) and short-circuiting on the first :deny is the canonical composition.

Built-in dimensions

Raxol.Agent.Sandbox.Shell -- gates Raxol.Agent.Directive.Shell via allowlist / denylist / deny_all.
Raxol.Agent.Sandbox.SendAgent -- gates Raxol.Agent.Directive.SendAgent via allow_only / deny.
Raxol.Agent.Sandbox.Async -- gates Raxol.Agent.Directive.Async (wholesale allow / deny).

Filesystem, Network, and Resource dimensions are planned but deferred to a follow-up because their enforcement layer is different (Action integration for filesystem / network; OS-level quotas for Resource).

Action atoms

The protocol's action argument identifies what's being authorized. Built-in atoms:

:shell -- Directive.Shell (payload: %{command, opts})
:send_agent -- Directive.SendAgent (payload: %{target_id, message})
:async -- Directive.Async (payload: %{fun})

A sandbox's authorize/4 returns :ok for any action that doesn't match its dimension; that's the abstention case.

Context

ctx is a map opaquely passed through. The integration layer populates it with at least:

:agent_id -- the calling agent
:agent_module -- the agent's module

Dimension implementations may inspect or ignore ctx as they see fit.

Summary

Types

decision()

Authorization decision.

t()

All the types that implement this protocol.

Functions

authorize(sandbox, action, payload, ctx)

Decide whether the agent may perform action with the given payload. Return :ok to allow or abstain (when action is outside the sandbox's dimension), {:deny, reason} to block.