Package io.agentscope.harness.agent.sandbox.snapshot

Interface SandboxSnapshot

All Known Implementing Classes:
LocalSandboxSnapshot, NoopSandboxSnapshot, RemoteSandboxSnapshot
public interface SandboxSnapshot
Represents a persisted snapshot of a sandbox workspace.

Snapshots allow workspace state to be preserved between session stops and restored on subsequent session starts. Implementations determine where and how the snapshot is stored: local disk (LocalSandboxSnapshot), remote storage (RemoteSandboxSnapshot), or not at all (NoopSandboxSnapshot).

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    getId()
    Returns the unique identifier for this snapshot.
    String
    getType()
    Returns the snapshot type discriminator used in JSON serialization.
    default boolean
    isPersistenceEnabled()
    Returns whether this snapshot actually persists data.
    boolean
    isRestorable()
    Returns whether this snapshot can currently be restored.
    void
    persist(InputStream workspaceArchive)
    Persists the workspace archive to this snapshot.
    InputStream
    restore()
    Restores the workspace archive from this snapshot.

  • Method Details

    • persist

      void persist(InputStream workspaceArchive) throws Exception
      Persists the workspace archive to this snapshot.
      Parameters:
      workspaceArchive - tar stream of the workspace to persist; caller is responsible for closing the stream after this call
      Throws:
      Exception - if the persist operation fails

    • restore

      InputStream restore() throws Exception
      Restores the workspace archive from this snapshot.
      Returns:
      tar stream of the workspace; caller is responsible for closing
      Throws:
      Exception - if the restore operation fails or the snapshot is not restorable

    • isRestorable

      boolean isRestorable() throws Exception
      Returns whether this snapshot can currently be restored.
      Returns:
      true if restore() would succeed
      Throws:
      Exception - if checking restorability fails

    • getId

      String getId()
      Returns the unique identifier for this snapshot.
      Returns:
      snapshot id

    • getType

      String getType()
      Returns the snapshot type discriminator used in JSON serialization.
      Returns:
      type string (e.g. "noop", "local", "remote")

    • isPersistenceEnabled

      default boolean isPersistenceEnabled()
      Returns whether this snapshot actually persists data.

      When false, AbstractBaseSandbox.stop() skips the potentially expensive workspace archive step entirely. Defaults to true.

      Returns:
      false only for no-op implementations that discard all archive data