wehub-resource-sync
71 lines
6.3 KiB
Markdown
71 lines
6.3 KiB
Markdown
# Sandbox Runtime Boundary
|
|
|
|
Use this reference for changes to sandbox session ownership, `SandboxAgent` preparation, manifests, capabilities, host-path materialization, snapshots, resume state, agent transitions, or cleanup.
|
|
|
|
## Runtime Ownership
|
|
|
|
The outer `Runner` owns agent turns, approvals, handoffs, tracing, session history, and `RunState`. A sandbox session owns the execution environment, workspace, processes, mounts, and provider-specific connection state. Do not move one layer's lifecycle into the other without defining resume and cleanup behavior for both.
|
|
|
|
- A live `SandboxRunConfig.session` is caller-owned. The runner may configure and use it but must not delete or fully tear it down.
|
|
- A session created or resumed through `SandboxRunConfig.client` is runner-owned. Cleanup runs pre-stop hooks, persists snapshot-backed workspace state, stops and shuts down the session, deletes provider resources when required, and closes dependencies.
|
|
- Session cleanup must be idempotent and release acquired `SandboxAgent` concurrency guards even when persistence or provider cleanup fails.
|
|
- A `SandboxAgent` instance cannot be reused concurrently across runs because prepared capability tools and session state are bound to one live run. Clone or construct separate agents for concurrent work.
|
|
|
|
## Session Source and Saved State
|
|
|
|
Resolve the session source in this order: injected live session, resumable sandbox state carried by `RunState`, explicit `SandboxRunConfig.session_state`, then a newly created session. Manifest and snapshot inputs seed only a fresh session; they do not overwrite an injected or resumed workspace.
|
|
|
|
- `RunState` sandbox data and explicit `session_state` represent provider connection or session state used to reconnect to existing work.
|
|
- A snapshot represents saved workspace contents used to seed a new session. It is not interchangeable with provider session state.
|
|
- Preserve stable per-agent resume identity across handoffs, including graphs with duplicate agent names. Object identity is process-local, so serialized state needs stable keys and explicit current-agent selection.
|
|
- Serialize runner-owned sessions after stop-time persistence has completed so a later resume can reattach when the backend survives or reconstruct the workspace from the saved snapshot when it does not.
|
|
|
|
## Agent Preparation
|
|
|
|
- Clone capability instances per run before binding them to a live session. Reusing mutable capability objects can leak tools, sampling settings, or session references across runs.
|
|
- Validate capability dependencies before exposing tools. Capability tool construction, instruction fragments, input processing, and sampling adjustments must use the same effective capability set.
|
|
- Build instructions in the documented order: SDK sandbox base prompt or explicit replacement, agent instructions, capability instructions, remote-mount policy, then the rendered filesystem description.
|
|
- Bind capability tools to the live session and preserve a link from the prepared clone to the public `SandboxAgent`. Dynamic instructions and hooks should observe the public agent rather than an internal clone with implementation-only state.
|
|
- Handoffs stay in the outer run loop and select another agent-bound sandbox session. A nested `Agent.as_tool()` run owns its own nested runner and sandbox lifecycle.
|
|
|
|
## Filesystem Trust Boundary
|
|
|
|
- Manifest entry destinations are workspace-relative and must not escape the workspace. The workspace root itself must be absolute where the backend requires an absolute runtime root.
|
|
- `LocalFile` and `LocalDir` sources are host-side inputs. Resolve them against a trusted base directory, require explicit application-controlled `extra_path_grants` outside that base, and reject untrusted manifests that try to authorize their own host access.
|
|
- Validate local sources at use time, not only when parsing the manifest. Defend against symlinked sources, parent-directory swaps, platform path aliases, and archive members that change meaning between validation and extraction.
|
|
- Archive extraction must reject traversal, unsafe links, and unsupported member types before writing, and enforce entry, byte, and expansion limits without materializing an unbounded member list.
|
|
- Extra path grants are runtime access, not durable workspace content. Snapshots and `persist_workspace()` include the workspace root, not arbitrary granted paths.
|
|
- Credentials for mounts or providers must remain in the owning adapter and must not appear in generated shell commands, model-visible errors, logs, or serialized sandbox state.
|
|
|
|
## Provider and Error Boundary
|
|
|
|
- Normalize backend failures to sandbox errors without discarding provider details needed for diagnosis. Preserve explicit retryability instead of inferring it later from a message string.
|
|
- Keep portable sandbox paths separate from host filesystem paths and provider identifiers. Conversion belongs in the backend or materialization boundary, not in agent-facing tools.
|
|
- Temporary clones, mounts, sinks, and dependency resources need failure cleanup during partial startup as well as normal shutdown.
|
|
- Capability tools should report bounded output and preserve provider exit status or structured error data without exposing private runtime metadata to the model.
|
|
|
|
## Review Checklist
|
|
|
|
1. Name the owner of every live session, provider client, mount, process, capability, and temporary resource.
|
|
2. Test injected, resumed, explicit-state, snapshot-seeded, and fresh-session paths separately.
|
|
3. Verify handoffs, duplicate agent names, interruption resume, and cleanup failure preserve the intended session mapping.
|
|
4. Test host-path, symlink, traversal, archive-limit, and credential-redaction boundaries on applicable platforms.
|
|
5. Exercise the public `Runner` path so agent preparation, capability binding, persistence, and cleanup run together.
|
|
|
|
## Sources
|
|
|
|
- `docs/sandbox/guide.md`
|
|
- `docs/sandbox/clients.md`
|
|
- `src/agents/sandbox/runtime.py`
|
|
- `src/agents/sandbox/runtime_session_manager.py`
|
|
- `src/agents/sandbox/runtime_agent_preparation.py`
|
|
- `src/agents/sandbox/manifest.py`
|
|
- `src/agents/sandbox/materialization.py`
|
|
- `src/agents/sandbox/workspace_paths.py`
|
|
- `src/agents/sandbox/session/archive_extraction.py`
|
|
- `tests/sandbox/test_runtime.py`
|
|
- `tests/sandbox/test_runtime_agent_preparation.py`
|
|
- `tests/sandbox/test_session_state_roundtrip.py`
|
|
- `tests/sandbox/test_materialization.py`
|
|
- `tests/sandbox/test_extract.py`
|