Documentation
¶
Overview ¶
Package dabackend defines virtual file and optional shell capabilities used by deep agent filesystem middleware.
Index ¶
- Constants
- Variables
- func AppendGrepError(existing, next string) string
- func ApproveSandboxExecution(ctx context.Context, sandbox Sandbox) (context.Context, bool)
- func ArtifactPath(value Backend, directory string) string
- func ArtifactsRootOf(value Backend) string
- func BindRuntime(ctx context.Context, value Backend, reader StateReader, runtime ...Runtime) (context.Context, error)
- func DepsAs[T any](runtime *Runtime) (T, bool)
- func IsBinaryReadPath(name string) bool
- func IsVideoReadPath(name string) bool
- func NormalizeNewlines(value string) string
- func ReplaceText(name, content, old, replacement string, replaceAll bool) (string, int, error)
- func RuntimeUpdates(ctx context.Context, value Backend) map[string]any
- func SandboxExecutionApproved(ctx context.Context, sandbox Sandbox) bool
- func ValidateGrepOptions(options GrepOptions) error
- type Backend
- type BaseSandbox
- func (sandbox *BaseSandbox) Delete(ctx context.Context, name string) (DeleteResult, error)
- func (sandbox *BaseSandbox) Download(ctx context.Context, names []string) []DownloadResult
- func (sandbox *BaseSandbox) Edit(ctx context.Context, name, old, replacement string, replaceAll bool) (EditResult, error)
- func (sandbox *BaseSandbox) Execute(ctx context.Context, command string, timeout time.Duration) (ExecuteResult, error)
- func (sandbox *BaseSandbox) ExecuteWithOffload(ctx context.Context, command, capturePath string, ...) (ExecuteOffloadResult, error)
- func (sandbox *BaseSandbox) ExecuteWithOptions(ctx context.Context, command string, options ExecuteOptions) (ExecuteResult, error)
- func (sandbox *BaseSandbox) Glob(ctx context.Context, pattern, base string) (GlobResult, error)
- func (sandbox *BaseSandbox) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
- func (sandbox *BaseSandbox) ID() string
- func (sandbox *BaseSandbox) List(ctx context.Context, directory string) (ListResult, error)
- func (sandbox *BaseSandbox) Read(ctx context.Context, name string, offset, limit int) (ReadResult, error)
- func (sandbox *BaseSandbox) ReadBinary(ctx context.Context, name string, maxBytes int64) (ReadResult, error)
- func (sandbox *BaseSandbox) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (sandbox *BaseSandbox) Write(ctx context.Context, name, content string) (WriteResult, error)
- type BaseSandboxOptions
- type BoundedBinaryReader
- type Capabilities
- type CaptureOffloader
- type Composite
- func (composite *Composite) BindRuntime(ctx context.Context, reader StateReader) (context.Context, error)
- func (composite *Composite) Delete(ctx context.Context, value string) (DeleteResult, error)
- func (composite *Composite) Download(ctx context.Context, paths []string) []DownloadResult
- func (composite *Composite) Edit(ctx context.Context, value, old, replacement string, all bool) (EditResult, error)
- func (composite *Composite) Glob(ctx context.Context, pattern, base string) (GlobResult, error)
- func (composite *Composite) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
- func (composite *Composite) IsSymlink(ctx context.Context, value string) (bool, error)
- func (composite *Composite) List(ctx context.Context, value string) (ListResult, error)
- func (composite *Composite) Read(ctx context.Context, value string, offset, limit int) (ReadResult, error)
- func (composite *Composite) ReadBinary(ctx context.Context, value string, maxBytes int64) (ReadResult, error)
- func (composite *Composite) RuntimeUpdates(ctx context.Context) map[string]any
- func (composite *Composite) StateFields() []StateField
- func (composite *Composite) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (composite *Composite) Write(ctx context.Context, value, content string) (WriteResult, error)
- func (composite *Composite) WriteDurable(ctx context.Context, value, content string) (WriteResult, error)
- type CompositeOptions
- type ConfigurableSandbox
- type ContextLine
- type DeleteResult
- type DownloadResult
- type DurableWriter
- type EditResult
- type Encoding
- type ExecuteOffloadOptions
- type ExecuteOffloadResult
- type ExecuteOptions
- type ExecuteResult
- type FileData
- type FileInfo
- type Filesystem
- func (backend *Filesystem) Delete(ctx context.Context, path string) (DeleteResult, error)
- func (backend *Filesystem) Download(ctx context.Context, paths []string) []DownloadResult
- func (backend *Filesystem) Edit(ctx context.Context, path, old, replacement string, replaceAll bool) (EditResult, error)
- func (backend *Filesystem) Glob(ctx context.Context, pattern, base string) (GlobResult, error)
- func (backend *Filesystem) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
- func (backend *Filesystem) IsSymlink(ctx context.Context, path string) (bool, error)
- func (backend *Filesystem) List(ctx context.Context, path string) (ListResult, error)
- func (backend *Filesystem) Read(ctx context.Context, path string, offset, limit int) (ReadResult, error)
- func (backend *Filesystem) ReadBinary(ctx context.Context, name string, maxBytes int64) (ReadResult, error)
- func (backend *Filesystem) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (backend *Filesystem) Write(ctx context.Context, path, content string) (WriteResult, error)
- func (backend *Filesystem) WriteDurable(ctx context.Context, path, content string) (WriteResult, error)
- type FilesystemOptions
- type GlobResult
- type GrepMatch
- type GrepOptions
- type GrepResult
- type ListResult
- type LocalSandboxMode
- type LocalShell
- type LocalShellOptions
- type MacOSSandbox
- func (sandbox *MacOSSandbox) ApprovedContext(ctx context.Context) (context.Context, bool)
- func (sandbox *MacOSSandbox) Delete(ctx context.Context, name string) (DeleteResult, error)
- func (sandbox *MacOSSandbox) Edit(ctx context.Context, name, old, replacement string, replaceAll bool) (EditResult, error)
- func (sandbox *MacOSSandbox) Execute(ctx context.Context, command string, timeout time.Duration) (ExecuteResult, error)
- func (sandbox *MacOSSandbox) ExecuteWithOptions(ctx context.Context, command string, options ExecuteOptions) (ExecuteResult, error)
- func (sandbox *MacOSSandbox) ExecutionApproved(ctx context.Context) bool
- func (sandbox *MacOSSandbox) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (sandbox *MacOSSandbox) Write(ctx context.Context, name, content string) (WriteResult, error)
- func (sandbox *MacOSSandbox) WriteDurable(ctx context.Context, name, content string) (WriteResult, error)
- type MacOSSandboxOptions
- type Memory
- func (memory *Memory) Delete(ctx context.Context, name string) (DeleteResult, error)
- func (memory *Memory) Download(ctx context.Context, names []string) []DownloadResult
- func (memory *Memory) Edit(ctx context.Context, name, old, replacement string, replaceAll bool) (EditResult, error)
- func (memory *Memory) Glob(ctx context.Context, pattern, base string) (GlobResult, error)
- func (memory *Memory) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
- func (memory *Memory) List(ctx context.Context, directory string) (ListResult, error)
- func (memory *Memory) Read(ctx context.Context, name string, offset, limit int) (ReadResult, error)
- func (memory *Memory) Snapshot() map[string]FileData
- func (memory *Memory) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (memory *Memory) Write(ctx context.Context, name, content string) (WriteResult, error)
- type NamespaceFactory
- type ReadResult
- type Runtime
- type RuntimeBackend
- type Sandbox
- type SandboxBackendProtocol
- type SandboxViolation
- type ShellPathRoute
- type State
- func (backend *State) BindRuntime(ctx context.Context, reader StateReader) (context.Context, error)
- func (backend *State) Delete(ctx context.Context, path string) (DeleteResult, error)
- func (backend *State) Download(ctx context.Context, paths []string) []DownloadResult
- func (backend *State) Edit(ctx context.Context, path, old, replacement string, all bool) (EditResult, error)
- func (backend *State) Glob(ctx context.Context, pattern, path string) (GlobResult, error)
- func (backend *State) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
- func (backend *State) List(ctx context.Context, path string) (ListResult, error)
- func (backend *State) Read(ctx context.Context, path string, offset, limit int) (ReadResult, error)
- func (backend *State) RuntimeUpdates(ctx context.Context) map[string]any
- func (backend *State) StateFields() []StateField
- func (backend *State) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (backend *State) Write(ctx context.Context, path, content string) (WriteResult, error)
- type StateField
- type StateReader
- type Store
- func (backend *Store) BindRuntime(ctx context.Context, _ StateReader) (context.Context, error)
- func (backend *Store) Delete(ctx context.Context, path string) (DeleteResult, error)
- func (backend *Store) Download(ctx context.Context, paths []string) []DownloadResult
- func (backend *Store) Edit(ctx context.Context, path, old, replacement string, all bool) (EditResult, error)
- func (backend *Store) Glob(ctx context.Context, pattern, path string) (GlobResult, error)
- func (backend *Store) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
- func (backend *Store) List(ctx context.Context, path string) (ListResult, error)
- func (backend *Store) Read(ctx context.Context, path string, offset, limit int) (ReadResult, error)
- func (backend *Store) RuntimeUpdates(context.Context) map[string]any
- func (backend *Store) StateFields() []StateField
- func (backend *Store) Upload(ctx context.Context, uploads []Upload) []UploadResult
- func (backend *Store) Write(ctx context.Context, path, content string) (WriteResult, error)
- type StoreOptions
- type Upload
- type UploadResult
- type WriteResult
Constants ¶
const ( EncodingUTF8 Encoding = "utf-8" EncodingBase64 Encoding = "base64" // MaxSandboxBinaryPreviewBytes bounds binary data returned inline by a // transport-backed sandbox read. MaxSandboxBinaryPreviewBytes = 500 * 1024 // MaxSandboxReadOutputBytes bounds one rendered text page returned by a // transport-backed sandbox read. MaxSandboxReadOutputBytes = 500 * 1024 )
const MaxGrepErrorBytes = 8_000
const SandboxReadTruncationMessage = "" /* 196-byte string literal not displayed */
Variables ¶
var ErrLocalSandboxUnsupported = errors.New("local process sandbox is unsupported on this platform")
var ErrPayloadTooLarge = errors.New("payload too large")
ErrPayloadTooLarge identifies a bounded read rejected before its payload was allocated or returned.
var ErrSandboxProtectedPath = errors.New("sandbox workspace metadata is protected")
Functions ¶
func AppendGrepError ¶
AppendGrepError joins diagnostics while enforcing the backend wire bound.
func ApproveSandboxExecution ¶
ApproveSandboxExecution returns a context that authorizes one call path to cross a local sandbox boundary. It succeeds only for a backend that owns an approval-aware sandbox; remote and unrestricted backends are unchanged.
func ArtifactPath ¶
ArtifactPath joins a generated-artifact directory to a backend's root.
func ArtifactsRootOf ¶
ArtifactsRootOf returns the backend-selected virtual root for generated conversation history, media, and large tool outputs.
func BindRuntime ¶
func BindRuntime(ctx context.Context, value Backend, reader StateReader, runtime ...Runtime) (context.Context, error)
BindRuntime binds every runtime-backed component reachable through value.
func IsBinaryReadPath ¶
IsBinaryReadPath reports paths that are always routed as media or binary data, even when their bytes happen to be valid UTF-8.
func IsVideoReadPath ¶
IsVideoReadPath reports paths whose payload must be size-checked before a video extractor receives it.
func NormalizeNewlines ¶
NormalizeNewlines applies Python universal-newline semantics.
func ReplaceText ¶
ReplaceText performs the backend edit contract consistently across storage implementations, including newline normalization and actionable EOF errors.
func RuntimeUpdates ¶
RuntimeUpdates collects state writes emitted by a runtime-backed backend.
func SandboxExecutionApproved ¶
SandboxExecutionApproved reports whether ctx already carries authority to cross this sandbox instance's execution boundary.
func ValidateGrepOptions ¶
func ValidateGrepOptions(options GrepOptions) error
ValidateGrepOptions rejects ambiguous negative limits. Uncapped is the only supported way to disable result limiting.
Types ¶
type Backend ¶
type Backend interface {
List(context.Context, string) (ListResult, error)
Read(context.Context, string, int, int) (ReadResult, error)
Write(context.Context, string, string) (WriteResult, error)
Edit(context.Context, string, string, string, bool) (EditResult, error)
Delete(context.Context, string) (DeleteResult, error)
Glob(context.Context, string, string) (GlobResult, error)
Grep(context.Context, string, GrepOptions) (GrepResult, error)
Upload(context.Context, []Upload) []UploadResult
Download(context.Context, []string) []DownloadResult
}
Backend is the uniform synchronous-by-contract, context-aware file API.
type BaseSandbox ¶
type BaseSandbox struct {
// contains filtered or unexported fields
}
BaseSandbox derives Backend operations from a small sandbox transport. File helpers require python3 in the sandbox image. They do not add isolation: every path reachable by the supplied shell is reachable by these operations.
func NewBaseSandbox ¶
func NewBaseSandbox(transport SandboxBackendProtocol, options BaseSandboxOptions) *BaseSandbox
NewBaseSandbox constructs a complete Sandbox from a minimal transport.
func (*BaseSandbox) Delete ¶
func (sandbox *BaseSandbox) Delete(ctx context.Context, name string) (DeleteResult, error)
func (*BaseSandbox) Download ¶
func (sandbox *BaseSandbox) Download(ctx context.Context, names []string) []DownloadResult
func (*BaseSandbox) Edit ¶
func (sandbox *BaseSandbox) Edit(ctx context.Context, name, old, replacement string, replaceAll bool) (EditResult, error)
func (*BaseSandbox) Execute ¶
func (sandbox *BaseSandbox) Execute(ctx context.Context, command string, timeout time.Duration) (ExecuteResult, error)
func (*BaseSandbox) ExecuteWithOffload ¶
func (sandbox *BaseSandbox) ExecuteWithOffload(ctx context.Context, command, capturePath string, options ExecuteOffloadOptions) (ExecuteOffloadResult, error)
ExecuteWithOffload executes command normally unless capture was explicitly enabled at construction. With capture enabled, a POSIX wrapper retains large output at capturePath and returns only a preview while preserving exit status.
func (*BaseSandbox) ExecuteWithOptions ¶
func (sandbox *BaseSandbox) ExecuteWithOptions(ctx context.Context, command string, options ExecuteOptions) (ExecuteResult, error)
func (*BaseSandbox) Glob ¶
func (sandbox *BaseSandbox) Glob(ctx context.Context, pattern, base string) (GlobResult, error)
func (*BaseSandbox) Grep ¶
func (sandbox *BaseSandbox) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
func (*BaseSandbox) ID ¶
func (sandbox *BaseSandbox) ID() string
func (*BaseSandbox) List ¶
func (sandbox *BaseSandbox) List(ctx context.Context, directory string) (ListResult, error)
func (*BaseSandbox) Read ¶
func (sandbox *BaseSandbox) Read(ctx context.Context, name string, offset, limit int) (ReadResult, error)
func (*BaseSandbox) ReadBinary ¶
func (sandbox *BaseSandbox) ReadBinary(ctx context.Context, name string, maxBytes int64) (ReadResult, error)
func (*BaseSandbox) Upload ¶
func (sandbox *BaseSandbox) Upload(ctx context.Context, uploads []Upload) []UploadResult
func (*BaseSandbox) Write ¶
func (sandbox *BaseSandbox) Write(ctx context.Context, name, content string) (WriteResult, error)
type BaseSandboxOptions ¶
type BaseSandboxOptions struct {
// EnableCaptureOffload opts into the POSIX shell and coreutils capture
// wrapper used by ExecuteWithOffload. It is disabled by default because not
// every sandbox image provides those commands.
EnableCaptureOffload bool
// MaxCaptureBytes bounds a captured command stream on the sandbox. Zero
// selects 10 MiB.
MaxCaptureBytes int
// MaxResults bounds Glob results, and Grep results when its caller does not
// provide a cap. Zero selects 1,000.
MaxResults int
}
BaseSandboxOptions configures a BaseSandbox.
type BoundedBinaryReader ¶
type BoundedBinaryReader interface {
ReadBinary(context.Context, string, int64) (ReadResult, error)
}
BoundedBinaryReader is an optional extension used for video reads. It must reject a payload larger than maxBytes before allocating or returning it.
type Capabilities ¶
func CapabilitiesOf ¶
func CapabilitiesOf(value Backend) Capabilities
type CaptureOffloader ¶
type CaptureOffloader interface {
Sandbox
ExecuteWithOffload(context.Context, string, string, ExecuteOffloadOptions) (ExecuteOffloadResult, error)
}
CaptureOffloader is the optional extension used by filesystem middleware to avoid transporting large command output through the agent process.
func CaptureOffloaderOf ¶
func CaptureOffloaderOf(value Backend, capturePath string) (CaptureOffloader, bool)
CaptureOffloaderOf resolves capture-at-source only when capturePath belongs to the same backend that owns command execution. Composite routed mounts are rejected because their files are not necessarily visible to the default backend's shell.
type Composite ¶
type Composite struct {
// contains filtered or unexported fields
}
Composite routes virtual paths by normalized longest prefix.
func NewComposite ¶
func NewComposite(defaultBackend Backend, routes map[string]Backend, optionValues ...CompositeOptions) *Composite
NewComposite constructs a routed backend. The default backend and routes are positional data; invalid static routes or options panic.
func (*Composite) BindRuntime ¶
func (*Composite) Download ¶
func (composite *Composite) Download(ctx context.Context, paths []string) []DownloadResult
func (*Composite) Grep ¶
func (composite *Composite) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
func (*Composite) ReadBinary ¶
func (*Composite) RuntimeUpdates ¶
func (*Composite) StateFields ¶
func (composite *Composite) StateFields() []StateField
func (*Composite) Upload ¶
func (composite *Composite) Upload(ctx context.Context, uploads []Upload) []UploadResult
func (*Composite) WriteDurable ¶
type CompositeOptions ¶
type CompositeOptions struct {
ArtifactsRoot string
}
CompositeOptions configures composite backend routing behavior.
type ConfigurableSandbox ¶
type ConfigurableSandbox interface {
Sandbox
ExecuteWithOptions(context.Context, string, ExecuteOptions) (ExecuteResult, error)
}
ConfigurableSandbox is an optional Sandbox extension for execution options whose omission is semantically meaningful. Existing Sandbox implementations remain valid and receive the legacy duration form through ExecuteSandbox.
type ContextLine ¶
type DeleteResult ¶
type DeleteResult struct {
Path string `json:"path"`
}
type DownloadResult ¶
type DurableWriter ¶
DurableWriter is an optional backend extension for atomic, crash-resistant file replacement. Backends without a durable storage boundary need not implement it.
type EditResult ¶
type ExecuteOffloadOptions ¶
ExecuteOffloadOptions controls capture-at-source command execution.
type ExecuteOffloadResult ¶
type ExecuteOffloadResult struct {
Offloaded bool
Response ExecuteResult
}
ExecuteOffloadResult reports whether the complete output was retained at the requested sandbox path. When Offloaded is true, Response.Output is a bounded head/tail preview.
type ExecuteOptions ¶
ExecuteOptions preserves the distinction between an omitted timeout and an explicitly supplied zero timeout. A nil Timeout uses the backend default; zero disables the command timeout when the backend supports that behavior.
type ExecuteResult ¶
type ExecuteResult struct {
Output string `json:"output"`
ExitCode *int `json:"exit_code,omitempty"`
Truncated bool `json:"truncated,omitempty"`
Violation *SandboxViolation `json:"violation,omitempty"`
}
func ExecuteSandbox ¶
func ExecuteSandbox(ctx context.Context, sandbox Sandbox, command string, options ExecuteOptions) (ExecuteResult, error)
ExecuteSandbox uses the richer execution contract when available and falls back to the legacy Sandbox method otherwise.
type Filesystem ¶
type Filesystem struct {
// contains filtered or unexported fields
}
Filesystem confines virtual paths to an explicit root by default.
func NewFilesystem ¶
func NewFilesystem(options FilesystemOptions) (*Filesystem, error)
func (*Filesystem) Delete ¶
func (backend *Filesystem) Delete(ctx context.Context, path string) (DeleteResult, error)
func (*Filesystem) Download ¶
func (backend *Filesystem) Download(ctx context.Context, paths []string) []DownloadResult
func (*Filesystem) Edit ¶
func (backend *Filesystem) Edit(ctx context.Context, path, old, replacement string, replaceAll bool) (EditResult, error)
func (*Filesystem) Glob ¶
func (backend *Filesystem) Glob(ctx context.Context, pattern, base string) (GlobResult, error)
func (*Filesystem) Grep ¶
func (backend *Filesystem) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
func (*Filesystem) IsSymlink ¶
IsSymlink reports whether the final confined path component is a symbolic link without following it. A missing path reports false without an error.
func (*Filesystem) List ¶
func (backend *Filesystem) List(ctx context.Context, path string) (ListResult, error)
func (*Filesystem) Read ¶
func (backend *Filesystem) Read(ctx context.Context, path string, offset, limit int) (ReadResult, error)
func (*Filesystem) ReadBinary ¶
func (backend *Filesystem) ReadBinary(ctx context.Context, name string, maxBytes int64) (ReadResult, error)
ReadBinary reads one binary value with a caller-selected allocation bound.
func (*Filesystem) Upload ¶
func (backend *Filesystem) Upload(ctx context.Context, uploads []Upload) []UploadResult
func (*Filesystem) Write ¶
func (backend *Filesystem) Write(ctx context.Context, path, content string) (WriteResult, error)
func (*Filesystem) WriteDurable ¶
func (backend *Filesystem) WriteDurable(ctx context.Context, path, content string) (WriteResult, error)
WriteDurable atomically replaces one confined file, flushes its contents, and flushes the containing directory before returning success.
type FilesystemOptions ¶
type FilesystemOptions struct {
Root string
// GetRoot optionally supplies the current root for each operation. It is
// useful for applications with an explicit change-directory tool.
GetRoot func() string
// AllowHostPaths disables virtual-root confinement. It is intended only for
// trusted local development and must be opted into explicitly.
AllowHostPaths bool
// MaxFileSize limits files scanned by Grep. It does not limit paginated
// text reads.
MaxFileSize int64
// MaxVideoSize limits video values returned by a direct Read. Middleware can
// impose a lower per-invocation limit through ReadBinary.
MaxVideoSize int64
MaxResults int
}
type GlobResult ¶
type GrepMatch ¶
type GrepMatch struct {
Path string `json:"path"`
Line int `json:"line"`
Text string `json:"text"`
ContextBefore []ContextLine `json:"context_before,omitempty"`
ContextAfter []ContextLine `json:"context_after,omitempty"`
}
type GrepOptions ¶
type GrepResult ¶
type ListResult ¶
type ListResult struct {
Entries []FileInfo `json:"entries"`
}
type LocalSandboxMode ¶
type LocalSandboxMode string
LocalSandboxMode controls the filesystem authority granted to commands.
const ( LocalSandboxReadOnly LocalSandboxMode = "read-only" LocalSandboxWorkspaceWrite LocalSandboxMode = "workspace-write" )
type LocalShell ¶
type LocalShell struct {
*Filesystem
// contains filtered or unexported fields
}
LocalShell is an explicitly constructed host process capability rooted at a Filesystem working directory. It is not a security sandbox.
func NewLocalShell ¶
func NewLocalShell(options LocalShellOptions) (*LocalShell, error)
func (*LocalShell) Execute ¶
func (shell *LocalShell) Execute(ctx context.Context, command string, timeout time.Duration) (ExecuteResult, error)
func (*LocalShell) ExecuteWithOptions ¶
func (shell *LocalShell) ExecuteWithOptions(ctx context.Context, command string, options ExecuteOptions) (ExecuteResult, error)
func (*LocalShell) ID ¶
func (shell *LocalShell) ID() string
type LocalShellOptions ¶
type LocalShellOptions struct {
Filesystem FilesystemOptions
ID string
Shell string
DefaultTimeout time.Duration
MaxOutput int
// Env is the complete command environment unless InheritEnv is true, in
// which case these values override a snapshot of the process environment.
Env map[string]string
InheritEnv bool
}
type MacOSSandbox ¶
type MacOSSandbox struct {
*LocalShell
// contains filtered or unexported fields
}
MacOSSandbox runs commands under the native macOS process sandbox and uses a workspace-confined Filesystem for in-process file operations.
func NewMacOSSandbox ¶
func NewMacOSSandbox(workspace string, options ...MacOSSandboxOptions) (*MacOSSandbox, error)
NewMacOSSandbox constructs a sandbox rooted at workspace. The required workspace is positional; options are an optional zero-or-one tail value.
func (*MacOSSandbox) ApprovedContext ¶
ApprovedContext marks a call path as authorized for this sandbox instance. Prefer ApproveSandboxExecution when the concrete sandbox type is unknown.
func (*MacOSSandbox) Delete ¶
func (sandbox *MacOSSandbox) Delete(ctx context.Context, name string) (DeleteResult, error)
func (*MacOSSandbox) Edit ¶
func (sandbox *MacOSSandbox) Edit(ctx context.Context, name, old, replacement string, replaceAll bool) (EditResult, error)
func (*MacOSSandbox) Execute ¶
func (sandbox *MacOSSandbox) Execute(ctx context.Context, command string, timeout time.Duration) (ExecuteResult, error)
func (*MacOSSandbox) ExecuteWithOptions ¶
func (sandbox *MacOSSandbox) ExecuteWithOptions(ctx context.Context, command string, options ExecuteOptions) (ExecuteResult, error)
func (*MacOSSandbox) ExecutionApproved ¶
func (sandbox *MacOSSandbox) ExecutionApproved(ctx context.Context) bool
ExecutionApproved reports whether ctx was approved for this sandbox.
func (*MacOSSandbox) Upload ¶
func (sandbox *MacOSSandbox) Upload(ctx context.Context, uploads []Upload) []UploadResult
func (*MacOSSandbox) Write ¶
func (sandbox *MacOSSandbox) Write(ctx context.Context, name, content string) (WriteResult, error)
func (*MacOSSandbox) WriteDurable ¶
func (sandbox *MacOSSandbox) WriteDurable(ctx context.Context, name, content string) (WriteResult, error)
type MacOSSandboxOptions ¶
type MacOSSandboxOptions struct {
Mode LocalSandboxMode
WritableRoots []string
UnreadableRoots []string
NetworkAccess bool
ID string
Shell string
DefaultTimeout time.Duration
MaxOutput int
Env map[string]string
InheritEnv bool
}
MacOSSandboxOptions configures the local macOS process sandbox. Commands may read the host filesystem except for UnreadableRoots. Workspace-write mode may write the active checkout, its validated Git administration directories, standard temporary directories, and WritableRoots. Network access is denied unless explicitly enabled.
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory stores virtual files in process memory. It is also the behavioral core used by state-backed agent files.
func LoadMemory ¶
LoadMemory validates an externally supplied snapshot before constructing an in-process backend. Prefer NewMemory for static application configuration.
func NewMemory ¶
NewMemory constructs an in-process backend. Invalid initial virtual paths are static construction mistakes and panic; operation failures remain errors.
func (*Memory) Download ¶
func (memory *Memory) Download(ctx context.Context, names []string) []DownloadResult
func (*Memory) Grep ¶
func (memory *Memory) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
func (*Memory) Snapshot ¶
Snapshot returns an independent copy of every virtual file. The result is plain data suitable for durable stores such as IndexedDB.
type NamespaceFactory ¶
NamespaceFactory resolves the persistent namespace for one invocation. The runtime is nil when the backend is used directly outside an agent run.
func FixedNamespace ¶
func FixedNamespace(namespace dastore.Namespace) NamespaceFactory
FixedNamespace returns a namespace factory for a fixed namespace.
type ReadResult ¶
type ReadResult struct {
Data *FileData `json:"file_data,omitempty"`
TotalLines *int `json:"total_lines,omitempty"`
StartLine *int `json:"start_line,omitempty"`
EndLine *int `json:"end_line,omitempty"`
NextOffset *int `json:"next_offset,omitempty"`
NoLinesRequested bool `json:"no_lines_requested,omitempty"`
}
type Runtime ¶
type Runtime struct {
Deps any
ThreadID string
Namespace string
CheckpointID string
TaskID string
Store dastore.Store
}
Runtime contains the invocation values a backend may use to select durable resources. Deps is application-defined and is the usual source for a per-user or per-assistant namespace.
type RuntimeBackend ¶
type RuntimeBackend interface {
Backend
BindRuntime(context.Context, StateReader) (context.Context, error)
RuntimeUpdates(context.Context) map[string]any
StateFields() []StateField
}
RuntimeBackend is a backend whose storage is supplied by the current graph state. BindRuntime creates an invocation-local view; RuntimeUpdates returns the partial field writes produced through that view.
type Sandbox ¶
type Sandbox interface {
Backend
ID() string
Execute(context.Context, string, time.Duration) (ExecuteResult, error)
}
Sandbox is an explicitly granted extension; a Backend can never gain shell authority implicitly.
type SandboxBackendProtocol ¶
type SandboxBackendProtocol interface {
ID() string
Execute(context.Context, string, time.Duration) (ExecuteResult, error)
Upload(context.Context, []Upload) []UploadResult
}
SandboxBackendProtocol is the minimal transport contract required by BaseSandbox. Implementations provide identity, command execution, and file upload; BaseSandbox derives the complete Backend file API from those primitives.
Execute may use duration zero as its transport-defined default. Transports that distinguish an omitted timeout from an explicit zero may additionally implement ExecuteWithOptions.
type SandboxViolation ¶
type SandboxViolation struct {
Resource string `json:"resource"`
Backend string `json:"backend"`
Reason string `json:"reason"`
Path string `json:"path,omitempty"`
OutputSnippet string `json:"output_snippet,omitempty"`
}
SandboxViolation is a normalized policy denial observed while executing a command. It is intentionally part of the execution result: a denied command completed normally from the process runner's perspective, while callers may use the structured denial as an approval boundary.
type ShellPathRoute ¶
ShellPathRoute describes whether a composite virtual mount is reachable by the default backend's shell and, when it is, which host prefix replaces it.
func ShellPathRoutes ¶
func ShellPathRoutes(value Backend) []ShellPathRoute
ShellPathRoutes reports composite mount mappings without exposing backend internals. Local mappings are valid only when the default shell and routed filesystem share the host.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State stores files in a required delta channel. It can only be used while bound to graph state by filesystem middleware; direct calls fail clearly.
func LoadState ¶
LoadState validates externally supplied initial checkpoint data. Prefer NewState for static application configuration.
func NewState ¶
NewState constructs a thread-scoped state backend. An empty key selects the standard "files" field. Initial values use the same plain-data records that are persisted in checkpoints.
func (*State) BindRuntime ¶
func (*State) Download ¶
func (backend *State) Download(ctx context.Context, paths []string) []DownloadResult
func (*State) Grep ¶
func (backend *State) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
func (*State) RuntimeUpdates ¶
func (*State) StateFields ¶
func (backend *State) StateFields() []StateField
type StateField ¶
type StateField struct {
Key string
Contract string
SnapshotFrequency uint64
Initial func() any
Reduce func(any, []any) (any, error)
Clone func(any) any
}
StateField describes a delta-backed virtual filesystem field. Consumers use these declarations to register the field with their graph runtime.
func RuntimeStateFields ¶
func RuntimeStateFields(value Backend) []StateField
RuntimeStateFields returns all graph fields required by a backend.
type StateReader ¶
StateReader is the minimal graph-state view required by a runtime-bound backend. It intentionally matches the state view exposed to tools.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists virtual files in a namespaced runtime Store.
func NewStore ¶
func NewStore(namespace NamespaceFactory, optionValues ...StoreOptions) *Store
NewStore constructs a persistent backend whose namespace and, optionally, store are resolved from each agent invocation.
func (*Store) BindRuntime ¶
func (*Store) Download ¶
func (backend *Store) Download(ctx context.Context, paths []string) []DownloadResult
func (*Store) Grep ¶
func (backend *Store) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)
func (*Store) StateFields ¶
func (backend *Store) StateFields() []StateField
type StoreOptions ¶
type StoreOptions struct {
// Store may be omitted when the agent runtime supplies one.
Store dastore.Store
}
StoreOptions configures a persistent store backend.
type UploadResult ¶
type WriteResult ¶
type WriteResult struct {
Path string `json:"path"`
}
func WriteDurable ¶
WriteDurable uses a backend's durable replacement boundary when available and otherwise falls back to the ordinary write contract.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agentcore adapts a caller-authenticated AgentCore Code Interpreter transport to dago's sandbox contracts.
|
Package agentcore adapts a caller-authenticated AgentCore Code Interpreter transport to dago's sandbox contracts. |
|
Package contexthub stores a dago virtual file tree in a persistent Context Hub agent repository.
|
Package contexthub stores a dago virtual file tree in a persistent Context Hub agent repository. |
|
Package daytona adapts caller-supplied Daytona transports to dago's sandbox backend.
|
Package daytona adapts caller-supplied Daytona transports to dago's sandbox backend. |
|
Package docker provides an explicitly constructed sandbox backed by a local Docker Engine.
|
Package docker provides an explicitly constructed sandbox backed by a local Docker Engine. |
|
Package langsmith adapts a LangSmith remote sandbox to dago's backend contracts.
|
Package langsmith adapts a LangSmith remote sandbox to dago's backend contracts. |
|
Package modal adapts a caller-supplied Modal sandbox transport to dago's sandbox backend.
|
Package modal adapts a caller-supplied Modal sandbox transport to dago's sandbox backend. |
|
Package runloop adapts caller-supplied Runloop devbox transports to dago's sandbox backend.
|
Package runloop adapts caller-supplied Runloop devbox transports to dago's sandbox backend. |
|
Package vercel adapts a caller-supplied Vercel Sandbox transport to dago's sandbox backend.
|
Package vercel adapts a caller-supplied Vercel Sandbox transport to dago's sandbox backend. |