Package io.agentscope.harness.agent.sandbox

Interface SandboxExecutionGuard

All Known Implementing Classes:
SandboxExecutionGuard.NoopSandboxExecutionGuard
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface SandboxExecutionGuard
Pluggable concurrency guard for sandbox execution slots.

A guard controls how many concurrent executions are allowed for a given SandboxIsolationKey. The default noop() imposes no restriction, preserving existing behaviour.

This extension point is primarily useful for IsolationScope.USER, IsolationScope.AGENT and IsolationScope.GLOBAL scopes, where multiple concurrent callers could otherwise race on the same persistent state slot (last write wins). Providing a guard serialises such callers without requiring changes to the surrounding infrastructure.

Implementations may use any backend — JVM semaphores, Redis SET NX leases, ZooKeeper, database advisory locks, etc. — and must be thread-safe.

Usage


 SandboxExecutionGuard guard = key -> {
     redisClient.set(key.toString(), token, SetArgs.Builder.nx().px(30_000));
     return () -> redisClient.eval(LUA_RELEASE_SCRIPT, key.toString(), token);
 };

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

Lifecycle

The harness calls tryEnter(io.agentscope.harness.agent.sandbox.SandboxIsolationKey) before sandbox acquire/resume and closes the returned SandboxLease after SandboxManager.release(io.agentscope.harness.agent.sandbox.SandboxAcquireResult) completes, so the guard covers the full call window: acquire → start → (call) → stop → release → lease.close().

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    SandboxExecutionGuard.NoopSandboxExecutionGuard
    Singleton no-op implementation.

  • Method Summary

    Modifier and Type
    Method
    Description
    static SandboxExecutionGuard
    noop()
    Returns the default no-op guard: execution is always allowed immediately and the returned SandboxLease is a no-op.
    SandboxLease
    tryEnter(SandboxIsolationKey key)
    Acquires the execution right for the given isolation key, blocking until the slot becomes available or the calling thread is interrupted.

  • Method Details

    • tryEnter

      SandboxLease tryEnter(SandboxIsolationKey key) throws InterruptedException
      Acquires the execution right for the given isolation key, blocking until the slot becomes available or the calling thread is interrupted.

      The returned SandboxLease must be closed to release the slot. The harness handles this automatically; callers do not need to close the lease explicitly.

      Parameters:
      key - the isolation key that identifies the sandbox slot to protect
      Returns:
      a lease that releases the execution right when closed
      Throws:
      InterruptedException - if interrupted while waiting for the slot

    • noop

      static SandboxExecutionGuard noop()
      Returns the default no-op guard: execution is always allowed immediately and the returned SandboxLease is a no-op. This is the built-in default — no configuration required.