RedisSandboxExecutionGuard

Redis-backed SandboxExecutionGuard that serialises concurrent access to a sandbox isolation slot using a Redis SET NX PX lease.

Mechanism

• #tryEnter writes a unique token to a Redis key with SET NX PX <ttlMs>. If the key is already held by another caller, it retries at retryInterval intervals until the slot becomes free or the thread is interrupted.

• The returned SandboxLease#close() executes a Lua CAS script that deletes the key only when the stored value equals the caller's token, preventing another holder's lock from being released by mistake.

Key format

`<keyPrefix><scope_lower>:<value>`

Examples (with default prefix agentscope:sandbox:lock:):

• agentscope:sandbox:lock:agent:code-agent

• agentscope:sandbox:lock:global:__global__

Usage

`UnifiedJedis jedis = new JedisPooled("localhost", 6379);

SandboxExecutionGuard guard = RedisSandboxExecutionGuard.builder(jedis)
.leaseTtl(Duration.ofMinutes(30)) // must exceed worst-case call duration
.retryInterval(Duration.ofMillis(500))
.build();

HarnessAgent.builder()
.filesystem(new DockerFilesystemSpec()
.isolationScope(IsolationScope.AGENT)
.executionGuard(guard))
...
.build();
`

TTL guidance

Set leaseTtl to comfortably exceed the worst-case agent call duration (including retries and LLM latency). If a call outlasts the TTL, Redis will evict the key and a concurrent caller may enter — this is a safety valve to prevent permanent deadlock, not an indication that two callers will safely share state. Monitor call durations and size the TTL accordingly.

Extending this guard

This class serves as the canonical reference implementation for SandboxExecutionGuard. Alternative stores (ZooKeeper, etcd, database advisory locks, …) should follow the same contract:

• #tryEnter blocks until the slot is acquired or the thread is interrupted.

• The returned SandboxLease releases the slot idempotently on SandboxLease#close().

• Release failures must be logged and swallowed — never thrown — so the harness post-call path always completes.