mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-09-14 16:08:41 +00:00
cc6a2657e7
Sandbox is an execution environment, not a named resource: multiple tools
(bash, read_file, write_file, glob, grep, ...) depend on it, all funneled
through ensure_sandbox_initialized / ensure_sandbox_initialized_async. Gate
the single acquisition entry point (single source of truth) instead of
maintaining a sandbox-tool-name set in middleware:
- authorize_sandbox_execution helper (authz/sandbox_authz.py) checks
authorize("sandbox", "execute", target="*") — a binary judgment
(can this role use the sandbox at all); RBAC allow:"*"/true permits,
allow:[]/false denies.
- lazy path: ensure_sandbox_initialized (+ async) calls the gate before
provider.acquire.
- eager path: SandboxMiddleware.before_agent / abefore_agent call the gate
before _acquire_sandbox.
- deny raises SandboxAuthorizationError (SandboxError subclass) which
propagates through tool execution as a friendly ToolMessage (RFC §9:
'not a crash').
- authorization.enabled: false is a no-op everywhere; provider errors
follow fail_closed (deny) / fail_open (allow).
12 tests in tests/test_sandbox_authorization.py cover disabled/allow/deny/
deny-via-bool/no-policy-unrestricted/provider-error-fail-closed/open/
internal-caller + ensure_sandbox_initialized deny (never acquires) and
allow (acquires) integration paths.
135 lines
4.2 KiB
Python
135 lines
4.2 KiB
Python
"""Sandbox-related exceptions with structured error information."""
|
|
|
|
|
|
class SandboxError(Exception):
|
|
"""Base exception for all sandbox-related errors."""
|
|
|
|
def __init__(self, message: str, details: dict | None = None):
|
|
super().__init__(message)
|
|
self.message = message
|
|
self.details = details or {}
|
|
|
|
def __str__(self) -> str:
|
|
if self.details:
|
|
detail_str = ", ".join(f"{k}={v}" for k, v in self.details.items())
|
|
return f"{self.message} ({detail_str})"
|
|
return self.message
|
|
|
|
|
|
class SandboxNotFoundError(SandboxError):
|
|
"""Raised when a sandbox cannot be found or is not available."""
|
|
|
|
def __init__(self, message: str = "Sandbox not found", sandbox_id: str | None = None):
|
|
details = {"sandbox_id": sandbox_id} if sandbox_id else None
|
|
super().__init__(message, details)
|
|
self.sandbox_id = sandbox_id
|
|
|
|
|
|
class SandboxRuntimeError(SandboxError):
|
|
"""Raised when sandbox runtime is not available or misconfigured."""
|
|
|
|
pass
|
|
|
|
|
|
class SandboxCommandError(SandboxError):
|
|
"""Raised when a command execution fails in the sandbox."""
|
|
|
|
def __init__(self, message: str, command: str | None = None, exit_code: int | None = None):
|
|
details = {}
|
|
if command:
|
|
details["command"] = command[:100] + "..." if len(command) > 100 else command
|
|
if exit_code is not None:
|
|
details["exit_code"] = exit_code
|
|
super().__init__(message, details)
|
|
self.command = command
|
|
self.exit_code = exit_code
|
|
|
|
|
|
class SandboxFileError(SandboxError):
|
|
"""Raised when a file operation fails in the sandbox."""
|
|
|
|
def __init__(self, message: str, path: str | None = None, operation: str | None = None):
|
|
details = {}
|
|
if path:
|
|
details["path"] = path
|
|
if operation:
|
|
details["operation"] = operation
|
|
super().__init__(message, details)
|
|
self.path = path
|
|
self.operation = operation
|
|
|
|
|
|
class SandboxPermissionError(SandboxFileError):
|
|
"""Raised when a permission error occurs during file operations."""
|
|
|
|
pass
|
|
|
|
|
|
class SandboxFileNotFoundError(SandboxFileError):
|
|
"""Raised when a file or directory is not found."""
|
|
|
|
pass
|
|
|
|
|
|
class SandboxCapacityExceededError(SandboxError):
|
|
"""Raised when the sandbox provider has no available capacity.
|
|
|
|
The reason distinguishes occupied capacity from provider shutdown.
|
|
The caller controls retry scheduling. DeerFlow does not retry automatically.
|
|
"""
|
|
|
|
CODE = "SANDBOX_CAPACITY_EXCEEDED"
|
|
|
|
def __init__(
|
|
self,
|
|
message: str = "All sandbox replica slots are in use",
|
|
*,
|
|
active: int = 0,
|
|
warm: int = 0,
|
|
reserved: int = 0,
|
|
replicas: int = 0,
|
|
retry_after_seconds: float = 5.0,
|
|
reason: str = "capacity",
|
|
) -> None:
|
|
details: dict[str, object] = {
|
|
"code": self.CODE,
|
|
"reason": reason,
|
|
"replicas": replicas,
|
|
"retryable": True,
|
|
"retry_after_seconds": retry_after_seconds,
|
|
}
|
|
if active:
|
|
details["active"] = active
|
|
if warm:
|
|
details["warm"] = warm
|
|
if reserved:
|
|
details["reserved"] = reserved
|
|
super().__init__(message, details)
|
|
self.active = active
|
|
self.warm = warm
|
|
self.reserved = reserved
|
|
self.replicas = replicas
|
|
self.retry_after_seconds = retry_after_seconds
|
|
self.reason = reason
|
|
|
|
|
|
class SandboxAuthorizationError(SandboxError):
|
|
"""Raised when the caller's role is denied sandbox execution.
|
|
|
|
Phase 3 pluggable authorization: ``authorize("sandbox", "execute")`` is
|
|
checked before sandbox acquisition. On deny this error propagates up
|
|
through the tool's execution so the agent's tool-error handling converts
|
|
it to a friendly ``ToolMessage`` ("sandbox not permitted for your role"),
|
|
rather than crashing the run (RFC §9).
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
message: str = "Sandbox execution is not permitted for your role",
|
|
*,
|
|
role: str | None = None,
|
|
) -> None:
|
|
details = {"role": role} if role else None
|
|
super().__init__(message, details)
|
|
self.role = role
|