flutter_sandbox library

Classes

BackgroundShell: Optional Shell capability: detached, log-file-backed jobs that outlive the initiating tool call. Implemented by process-backed environments (local shell); sandboxed/web environments simply do not implement it and callers answer a clean "not supported here" note instead.
CancelToken: Cooperative cancellation, the Dart counterpart of the web AbortSignal.
CancelTokenSource: The writable side of a CancelToken. Keep it private to the caller that owns the operation; hand only the token to callees.
CubeCacheManager: Saves, restores and clears a cube's cache directories.
CubeCachePolicy: The spec.cache: section of a cube.
CubeEnvHidden: A variable explicitly removed from the child environment (e.g. HOME).
CubeEnvPolicy: The spec.env: section: the ordered variable list.
CubeEnvValue: A variable with a literal value.
CubeEnvValueFrom: A variable resolved from the host environment at CubeEnvPolicy.apply time. source has the form env:NAME.
CubeEnvVar: One declared environment variable. Sealed: a literal CubeEnvValue, a host-resolved CubeEnvValueFrom, or a removed CubeEnvHidden.
CubeFsGuard: A FileSystem whose operations are gated by a cube's filesystem policy.
CubeFsPolicy: The spec.filesystem: section: workspace root plus mount overrides.
CubeMount: One mount entry: a path prefix and the access level granted under it.
CubeNetworkPolicy: The spec.network: section: ordered allow/deny rule lists.
CubeNetworkRule: One network rule: a host pattern plus an optional port set.
CubePolicyDecision: The outcome of a CubePolicyEngine.checkCommand evaluation.
CubePolicyEngine: Evaluates a shell command line against a cube's tool and network policies.
CubeProfileStaging: A backend whose kernel confinement is driven by a profile artifact that must exist on disk before the wrapped command runs. SandboxedShell probes for this capability and stages buildProfile's output to .fah/cube-profiles/<cacheKey>.sb (once per spec) before the first wrapped exec.
CubeResolver: Resolves CubeSpec manifests by path or name.
CubeResourceLimits: The spec.resources: section: optional cpu string, byte limits and a wall-clock timeout.
CubeSandboxBackend: A platform strategy for confining a cube's processes at the OS level.
CubeSettings: The cube: config section: opt-in switch plus the default manifest.
CubeSpec: A parsed cube manifest: identity plus the five policy sections.
CubeToolPolicy: The spec.tools: section of a cube: the allow/deny command-word sets.
Err<T, E>: A failed Result.
ExecutionEnv: Filesystem and process execution environment used by the harness.
FileInfo: Metadata for one filesystem object.
FileSystem: Filesystem capability used by the harness.
LinuxUnshareBackend: The Linux backend: unshare argv generation plus command wrapping.
MacOsSandboxBackend: The macOS backend: SBPL profile generation plus sandbox-exec wrapping.
MemoryExecutionEnv: In-memory ExecutionEnv: MemoryFileSystem plus a Shell.
MemoryFileSystem: In-memory FileSystem with POSIX-style (/-separated) paths.
NoOpCubeBackend: A CubeSandboxBackend that changes nothing — the Dart-layer policies (tool policy, filesystem guard, network scan) are the only enforcement in this mode.
Ok<T, E>: A successful Result.
Result<T, E>: Result of a fallible operation. Expected failures are returned as Err instead of thrown — FileSystem operations must never throw.
SandboxedExecutionEnv: An ExecutionEnv confined by a cube's policies.
SandboxedShell
Shell: Shell execution capability used by the harness.
ShellExecOptions: Options for Shell.exec.
ShellExecResult: Outcome of a completed Shell.exec invocation.
ShellJob: A detached shell job: a process that keeps running after the tool call that started it has returned. Output is appended to the job's log file (the path is chosen by the caller of BackgroundShell.startShellJob).
UnavailableShell: A Shell that reports ExecutionErrorCode.shellUnavailable for every command — the correct behavior on platforms without a process shell (web, or any sandboxed environment).
WindowsJobBackend: The Windows backend: Job Object descriptor generation (execution needs FFI — Phase 4 follow-up).

Enums

CompactionErrorCode: Stable error codes for CompactionException, ported from pi's CompactionError kinds.
CubeBackendMode: How a cube's commands are confined: policy (the Dart policy layers only) or kernel (wrapped in the OS sandbox primitive of the host platform — sandbox-exec on macOS, unshare on Linux).
CubePathAccess: Access level granted for a path.
ExecutionErrorCode: Stable, backend-independent error codes returned by Shell.exec.
FileErrorCode: Stable, backend-independent error codes returned by FileSystem operations.
FileKind: Kind of filesystem object addressed by a FileSystem.
SessionErrorCode: Stable error codes for SessionException, ported from pi's SessionErrorCode union.

Constants

yieldTokenZoneKey → const Symbol: Zone key under which the agent loop publishes the current tool phase's soft-yield token (see currentYieldToken).

Functions

cubeBackendForPlatform(String os, {CubeSpec spec = const CubeSpec(name: 'host'), String workspaceRoot = '/workspace', String tmpdir = '/tmp', Map<String, String> envVars = const {}}) → CubeSandboxBackend: Picks the backend for host platform os, bound to a run's context.
cubeEnvPrefix({required String workspaceRoot, required String tmpdir, Map<String, String> envVars = const {}}) → String: The env -i VAR=value argument words for a kernel-wrapped run: the fixed PATH trio, HOME at workspaceRoot and TMPDIR under it (the only guaranteed-writable area), then the cube's injected envVars on top (a same-named var overrides the default). Values are single-quoted so paths with spaces survive the outer shell.
cubeSpecCacheKey(CubeSpec spec) → String: The content-addressed spec key: 10 hex chars of the md5 over the spec's CubeSpec.toCanonicalMap JSON. Shared by the cache root (cube-cache/<key>) and the kernel profile staging path (cube-profiles/<key>.sb).
currentYieldToken() → CancelToken?: The soft-yield token of the enclosing tool-call phase, or null.
parseDurationSpec(String raw) → Duration: Parses a single-unit duration string — '3600s', '5m', '24h' — into a Duration. Compounds ('1h30m') and unknown units are rejected with FormatException.
parseSizeBytes(String raw) → int: Parses a size string to bytes: a plain integer ('1024') is bytes; binary suffixes K/KiB, M/Mi/MiB, G/GiB are 1024-based and decimal B, KB, MB, GB are 1000-based (case-insensitive).
resolveWorkspacePath(String path, String specWorkspace, String workspaceRoot) → String?: Remaps a spec-written path onto the realized workspace root: when path equals or lives under specWorkspace, that prefix is swapped for workspaceRoot (/workspace/data with root /work becomes /work/data); null when path is outside the workspace — including look-alike prefixes like /workspacefoo — meaning the caller keeps it as written.
sandboxExecOptions(CubeSpec spec, ShellExecOptions? options) → ShellExecOptions: A Shell whose commands are gated by a cube's policies. Builds the forwarded options for a permitted command under spec: the timeout clamped to the cube's CubeResourceLimits.timeout (the smaller of caller and cube wins; a null caller inherits the cube's), plus the cube's injected env vars.
shellQuote(String value) → String: Quotes value as a single POSIX shell word: wrapped in single quotes with embedded quotes escaped the standard '\'' way. An empty value becomes ''.

Exceptions / Errors

AgentHarnessException: Base class for all harness exceptions. Sealed so consumers can exhaustively switch on the exception type.
CancelledException: Thrown by CancelToken.throwIfCancelled and by operations that abort early due to cancellation.
CompactionException: Thrown when the compaction pipeline cannot produce a summary.
ConfigException: Thrown when harness configuration is invalid (e.g. malformed config files or missing required settings).
ExecutionError: Error returned by Shell.exec.
FileError: Error returned by FileSystem operations.
SessionException: Thrown when a session storage operation fails (read, write, or corrupt JSONL records).
ToolNotFoundException: Thrown when a tool referenced by the model is not registered.
ToolValidationException: Thrown when tool call arguments fail validation against the tool's declared parameter schema.

flutter_sandbox library

Classes

Enums

Constants

Functions

Exceptions / Errors

flutter_sandbox package

flutter_sandbox library