dabackend

package
v0.0.0-...-94a2dde Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 24, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package dabackend defines virtual file and optional shell capabilities used by deep agent filesystem middleware.

Index

Constants

View Source
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
)
View Source
const MaxGrepErrorBytes = 8_000
View Source
const SandboxReadTruncationMessage = "" /* 196-byte string literal not displayed */

Variables

View Source
var ErrLocalSandboxUnsupported = errors.New("local process sandbox is unsupported on this platform")
View Source
var ErrPayloadTooLarge = errors.New("payload too large")

ErrPayloadTooLarge identifies a bounded read rejected before its payload was allocated or returned.

View Source
var ErrSandboxProtectedPath = errors.New("sandbox workspace metadata is protected")

Functions

func AppendGrepError

func AppendGrepError(existing, next string) string

AppendGrepError joins diagnostics while enforcing the backend wire bound.

func ApproveSandboxExecution

func ApproveSandboxExecution(ctx context.Context, sandbox Sandbox) (context.Context, bool)

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

func ArtifactPath(value Backend, directory string) string

ArtifactPath joins a generated-artifact directory to a backend's root.

func ArtifactsRootOf

func ArtifactsRootOf(value Backend) string

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 DepsAs

func DepsAs[T any](runtime *Runtime) (T, bool)

DepsAs returns typed application dependencies.

func IsBinaryReadPath

func IsBinaryReadPath(name string) bool

IsBinaryReadPath reports paths that are always routed as media or binary data, even when their bytes happen to be valid UTF-8.

func IsVideoReadPath

func IsVideoReadPath(name string) bool

IsVideoReadPath reports paths whose payload must be size-checked before a video extractor receives it.

func NormalizeNewlines

func NormalizeNewlines(value string) string

NormalizeNewlines applies Python universal-newline semantics.

func ReplaceText

func ReplaceText(name, content, old, replacement string, replaceAll bool) (string, int, error)

ReplaceText performs the backend edit contract consistently across storage implementations, including newline normalization and actionable EOF errors.

func RuntimeUpdates

func RuntimeUpdates(ctx context.Context, value Backend) map[string]any

RuntimeUpdates collects state writes emitted by a runtime-backed backend.

func SandboxExecutionApproved

func SandboxExecutionApproved(ctx context.Context, sandbox Sandbox) bool

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

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

type Capabilities struct {
	Delete  bool
	Execute bool
}

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 *Composite) BindRuntime(ctx context.Context, reader StateReader) (context.Context, error)

func (*Composite) Delete

func (composite *Composite) Delete(ctx context.Context, value string) (DeleteResult, error)

func (*Composite) Download

func (composite *Composite) Download(ctx context.Context, paths []string) []DownloadResult

func (*Composite) Edit

func (composite *Composite) Edit(ctx context.Context, value, old, replacement string, all bool) (EditResult, error)

func (*Composite) Glob

func (composite *Composite) Glob(ctx context.Context, pattern, base string) (GlobResult, error)

func (*Composite) Grep

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) List

func (composite *Composite) List(ctx context.Context, value string) (ListResult, error)

func (*Composite) Read

func (composite *Composite) Read(ctx context.Context, value string, offset, limit int) (ReadResult, error)

func (*Composite) ReadBinary

func (composite *Composite) ReadBinary(ctx context.Context, value string, maxBytes int64) (ReadResult, error)

func (*Composite) RuntimeUpdates

func (composite *Composite) RuntimeUpdates(ctx context.Context) map[string]any

func (*Composite) StateFields

func (composite *Composite) StateFields() []StateField

func (*Composite) Upload

func (composite *Composite) Upload(ctx context.Context, uploads []Upload) []UploadResult

func (*Composite) Write

func (composite *Composite) Write(ctx context.Context, value, content string) (WriteResult, error)

func (*Composite) WriteDurable

func (composite *Composite) WriteDurable(ctx context.Context, value, content string) (WriteResult, error)

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 ContextLine struct {
	Line int    `json:"line"`
	Text string `json:"text"`
}

type DeleteResult

type DeleteResult struct {
	Path string `json:"path"`
}

type DownloadResult

type DownloadResult struct {
	Path    string `json:"path"`
	Content []byte `json:"content,omitempty"`
	Error   string `json:"error,omitempty"`
}

type DurableWriter

type DurableWriter interface {
	WriteDurable(context.Context, string, string) (WriteResult, error)
}

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 EditResult struct {
	Path        string `json:"path"`
	Occurrences int    `json:"occurrences"`
}

type Encoding

type Encoding string

type ExecuteOffloadOptions

type ExecuteOffloadOptions struct {
	MaxInlineBytes  int
	MaxCaptureBytes int
	Timeout         *time.Duration
}

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

type ExecuteOptions struct {
	Timeout *time.Duration
}

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 FileData

type FileData struct {
	Content    string    `json:"content"`
	Encoding   Encoding  `json:"encoding"`
	CreatedAt  time.Time `json:"created_at,omitzero"`
	ModifiedAt time.Time `json:"modified_at,omitzero"`
}

type FileInfo

type FileInfo struct {
	Path       string    `json:"path"`
	IsDir      bool      `json:"is_dir,omitempty"`
	Size       int64     `json:"size,omitempty"`
	ModifiedAt time.Time `json:"modified_at,omitzero"`
}

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 (backend *Filesystem) IsSymlink(ctx context.Context, path string) (bool, error)

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 GlobResult struct {
	Matches   []FileInfo `json:"matches"`
	Truncated bool       `json:"truncated,omitempty"`
}

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 GrepOptions struct {
	Path         string
	Glob         string
	MaxCount     int
	ContextLines int
	// Uncapped disables both MaxCount and a backend's default result cap.
	Uncapped bool
}

type GrepResult

type GrepResult struct {
	Matches   []GrepMatch `json:"matches"`
	Truncated bool        `json:"truncated,omitempty"`
	// Error reports a bounded or partial-search failure without discarding
	// matches collected before the failure.
	Error string `json:"error,omitempty"`
}

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

func (sandbox *MacOSSandbox) ApprovedContext(ctx context.Context) (context.Context, bool)

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

func LoadMemory(initial map[string]FileData) (*Memory, error)

LoadMemory validates an externally supplied snapshot before constructing an in-process backend. Prefer NewMemory for static application configuration.

func NewMemory

func NewMemory(initial map[string]FileData) *Memory

NewMemory constructs an in-process backend. Invalid initial virtual paths are static construction mistakes and panic; operation failures remain errors.

func (*Memory) Delete

func (memory *Memory) Delete(ctx context.Context, name string) (DeleteResult, error)

func (*Memory) Download

func (memory *Memory) Download(ctx context.Context, names []string) []DownloadResult

func (*Memory) Edit

func (memory *Memory) Edit(ctx context.Context, name, old, replacement string, replaceAll bool) (EditResult, error)

func (*Memory) Glob

func (memory *Memory) Glob(ctx context.Context, pattern, base string) (GlobResult, error)

func (*Memory) Grep

func (memory *Memory) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)

func (*Memory) List

func (memory *Memory) List(ctx context.Context, directory string) (ListResult, error)

func (*Memory) Read

func (memory *Memory) Read(ctx context.Context, name string, offset, limit int) (ReadResult, error)

func (*Memory) Snapshot

func (memory *Memory) Snapshot() map[string]FileData

Snapshot returns an independent copy of every virtual file. The result is plain data suitable for durable stores such as IndexedDB.

func (*Memory) Upload

func (memory *Memory) Upload(ctx context.Context, uploads []Upload) []UploadResult

func (*Memory) Write

func (memory *Memory) Write(ctx context.Context, name, content string) (WriteResult, error)

type NamespaceFactory

type NamespaceFactory func(*Runtime) (dastore.Namespace, error)

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"`
}

func SliceRead

func SliceRead(data FileData, offset, limit int) (ReadResult, error)

SliceRead applies the canonical text pagination contract shared by every backend. Binary data must be returned by the caller without pagination.

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.

func SandboxOf

func SandboxOf(value Backend) (Sandbox, bool)

SandboxOf resolves command execution through direct and composite backends. Composite execution always belongs to its default backend; routed mounts are file-only views and do not change the shell environment.

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

type ShellPathRoute struct {
	VirtualPrefix string
	HostPrefix    string
	Accessible    bool
}

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

func LoadState(key string, initial map[string]any) (*State, error)

LoadState validates externally supplied initial checkpoint data. Prefer NewState for static application configuration.

func NewState

func NewState(key string, initial map[string]any) *State

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 (backend *State) BindRuntime(ctx context.Context, reader StateReader) (context.Context, error)

func (*State) Delete

func (backend *State) Delete(ctx context.Context, path string) (DeleteResult, error)

func (*State) Download

func (backend *State) Download(ctx context.Context, paths []string) []DownloadResult

func (*State) Edit

func (backend *State) Edit(ctx context.Context, path, old, replacement string, all bool) (EditResult, error)

func (*State) Glob

func (backend *State) Glob(ctx context.Context, pattern, path string) (GlobResult, error)

func (*State) Grep

func (backend *State) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)

func (*State) List

func (backend *State) List(ctx context.Context, path string) (ListResult, error)

func (*State) Read

func (backend *State) Read(ctx context.Context, path string, offset, limit int) (ReadResult, error)

func (*State) RuntimeUpdates

func (backend *State) RuntimeUpdates(ctx context.Context) map[string]any

func (*State) StateFields

func (backend *State) StateFields() []StateField

func (*State) Upload

func (backend *State) Upload(ctx context.Context, uploads []Upload) []UploadResult

func (*State) Write

func (backend *State) Write(ctx context.Context, path, content string) (WriteResult, error)

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

type StateReader interface {
	Get(string) (any, bool)
}

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 (backend *Store) BindRuntime(ctx context.Context, _ StateReader) (context.Context, error)

func (*Store) Delete

func (backend *Store) Delete(ctx context.Context, path string) (DeleteResult, error)

func (*Store) Download

func (backend *Store) Download(ctx context.Context, paths []string) []DownloadResult

func (*Store) Edit

func (backend *Store) Edit(ctx context.Context, path, old, replacement string, all bool) (EditResult, error)

func (*Store) Glob

func (backend *Store) Glob(ctx context.Context, pattern, path string) (GlobResult, error)

func (*Store) Grep

func (backend *Store) Grep(ctx context.Context, pattern string, options GrepOptions) (GrepResult, error)

func (*Store) List

func (backend *Store) List(ctx context.Context, path string) (ListResult, error)

func (*Store) Read

func (backend *Store) Read(ctx context.Context, path string, offset, limit int) (ReadResult, error)

func (*Store) RuntimeUpdates

func (backend *Store) RuntimeUpdates(context.Context) map[string]any

func (*Store) StateFields

func (backend *Store) StateFields() []StateField

func (*Store) Upload

func (backend *Store) Upload(ctx context.Context, uploads []Upload) []UploadResult

func (*Store) Write

func (backend *Store) Write(ctx context.Context, path, content string) (WriteResult, error)

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 Upload

type Upload struct {
	Path    string
	Content []byte
}

type UploadResult

type UploadResult struct {
	Path  string `json:"path"`
	Error string `json:"error,omitempty"`
}

type WriteResult

type WriteResult struct {
	Path string `json:"path"`
}

func WriteDurable

func WriteDurable(ctx context.Context, backend Backend, path, content string) (WriteResult, error)

WriteDurable uses a backend's durable replacement boundary when available and otherwise falls back to the ordinary write contract.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL