@nhtio/adk/batteries/sandbox

Classes

Class	Description
DefaultArtifactMinter	A pure minter with optional, lazily loaded consumer formats.
SandboxEpoch	Opaque epoch issued by the sandbox manager and consumed by readers.

Interfaces

Interface	Description
ArtifactMinter	Artifact-class registry. Format constructors are lazy so unused parsers are never loaded.
BinarySandbox	Command wrapping contract used by the executor adapter.
ConformanceSources	The adapter surfaces the shared conformance battery exercises.
CreateSandboxOptions	Options for createSandbox.
DerivedRules	Backend-derived rules used for admission and drift checks, not a model-facing policy.
EvaluateJavascriptConfig	Configuration for the JavaScript guest battery.
GuestGlobal	A declared capability kept in the host runner.
GuestHandle	A guest evaluation handle; timeout kills and rejects rather than fabricating a result.
GuestLimits	Limits for a hostile guest: exactly seven fields, resolved before spawning and passed to both realms.
GuestRuntime	Runtime boundary for a hardened guest realm; limits and capability declarations cross the boundary.
GuestRuntimeLike	Minimal runtime seam used by the tool and by browser/Node adapters.
HostcallQuotas	Per-evaluation host RPC quotas, separate from the seven guest limits.
PathTranslator	Model-path boundary: normalises ergonomic paths while refusing unambiguous host escapes.
PreflightOptions	Inputs to the construction-time environment admission check.
RunShellCommandOptions	Configuration for the streaming shell-command tool.
SandboxCallDefaults	Defaults visible as model-facing tool arguments; guest limits are intentionally separate.
SandboxedExecutorOptions	Configuration for the sandboxed binary executor.
SandboxFileSystem	Filesystem capability with no copy primitive; traversal is complete and terminal-framed.
SandboxHandle	A live sandbox session: the object every sandbox tool is built against.
SandboxMediaOptions	Arguments for createSandboxMedia.
SandboxMediaReaderOptions	Arguments for createSandboxMediaReader.
SandboxObservabilityOptions	Dependencies used to create the redacting firehose.
SandboxPolicy	Assembly-facing policy. Reads allow by default; writes and network deny by default.
SandboxPolicyEnforcer	Policy boundary. run resolves on spawn and exposes live streams plus a later completion promise.
SandboxPreflight	Immutable decision retained by a sandbox handle for its entire lifetime.
SandboxSearch	Search capability; every result is lazy, complete, and terminal-framed.

Type Aliases

Type Alias	Description
ArtifactFormat	A format declaration accepted by the default minter.
Done	Terminal traversal protocol. Done is mandatory so end-of-stream cannot masquerade as completion.
FramedSource	A framed adapter surface exercised by the shared protocol battery.
GuestLogEvent	One log event exactly as the trusted guest bootstrap's logger posts it.
GuestLogFraming	Delivery and emission framing for guest logs.
GuestOutcome	Settled guest evaluation; partial encoding is still successful execution.
GuestThrown	A thrown guest value, preserving whether encoder representation was complete.
HitFrame	Content-hit frames contain the whole matched line, followed by exactly one Done.
ListFrame	List item frames followed by exactly one Done.
MimeResolver	MIME resolver; undefined means the resolver declines and a later resolver may decide.
ModelPath	Presentation/normalisation brand only; this is NOT a containment guarantee. Every filesystem use must still pass through PathTranslator.toRelative().
ModelWriteRoot	Opaque model-facing write root; constructed only by the path layer.
PathFrame	Path-search item frames followed by exactly one Done.
SandboxEpochIsLive	The capability needed to decide whether a sandbox handle is still alive.
SandboxEvent	Typed records emitted by the sandbox's single audit firehose.
SandboxEventSink	Consumer callback for sandbox audit events.
SandboxNarrator	Model-facing narration seam; implementations must be total over SandboxOutcome.
SandboxOutcome	Exhaustive model-facing sandbox outcome.
SandboxPathRejection	Why a path was rejected outright, before any normalisation.
SandboxPlatform	Platform identity supplied by the construction site.

Variables

Variable	Description
ALLOWED_RIPGREP_FLAGS	Flags emitted by the sandbox's own ripgrep adapter.
artifactMinterSchema	Duck-type schema.
assertPosixBinShell	Alias used by the SRT adapter at construction time.
DEFAULT_MIME_PEEK_BYTES	The default prefix available to a custom resolver.
defaultArtifactMinter	The shared default registry. Its format thunks remain lazy until selected.
defaultMimeResolver	The default resolver, also exported under the concise name used by consumers.
defaultSandboxNarrator	Existence-blind default narrator; not-found and denied-by-policy intentionally share wording.
DOUBLE_DASH_BINARIES	Binaries for which passing -- terminates option parsing.
E_INVALID_SANDBOX_CONFIG	Invalid sandbox configuration.
E_SANDBOX_DEPENDENCY_MISSING	Sandbox dependency is missing or unavailable at assembly time.
E_SANDBOX_FAILED	Sandbox operational failure presented to the model.
E_SANDBOX_GATE_REQUIRED	A required approval gate was not supplied.
E_SANDBOX_NARROWING_UNSUPPORTED	A requested policy narrowing cannot be represented by the backend.
E_SANDBOX_NOT_INITIALIZED	Sandbox operation was attempted before initialization.
E_SANDBOX_PATH_ESCAPE	Thrown when a model-supplied path is an UNAMBIGUOUS escape or an unsupported form.
E_SANDBOX_POLICY_CONFLICT	Requested policy conflicts with another enforced policy.
E_SANDBOX_REFUSED	Sandbox refusal presented to the model.
E_SANDBOX_UNSUPPORTED_ENV	Sandbox environment is unsupported.
E_SES_EVALUATION_TIMEOUT	A guest evaluation exceeded its tool-selected deadline.
E_SES_LOCKDOWN_REQUIRED	SES lockdown was unavailable or did not harden the guest realm.
escapeShellArgs	Compatibility alias for consumers that describe this operation as escaping.
escapeShellValue	Compatibility alias for consumers that describe this operation as escaping.
extensionMimeResolver	Resolve a MIME type from a filename, without sniffing bytes.
guestLimitFloors	Minimum representable guest values.
guestLimitsDefaults	Default guest values, each paired with its own floor.
guestLimitsSchema	Schema enforcing every guest field's own floor.
guestRuntimeSchema	Duck-type schema.
hostcallQuotasDefaults	Default host quotas.
hostcallQuotasSchema	Schema enforcing every host quota floor.
mimeResolverSchema	MIME resolver schema.
pathTranslatorSchema	Duck-type schema.
POSIX_SHELLS	Shells for which SRT's POSIX quote() and the -c invocation contract agree.
runSandboxPreflight	Compatibility alias for the construction-site call in WP-A1.
SANDBOX_EXTENSION_MIME	Extension to MIME mappings used by the default resolver.
sandboxFileSystemSchema	Duck-type schema.
sandboxPolicyEnforcerSchema	Duck-type schema.
sandboxPolicySchema	Closed structural schema for SandboxPolicy.
sandboxSearchSchema	Duck-type schema.

Functions

Function	Description
artifactConstructorForPath	Select the default artifact constructor for a path.
assertAllowedRipgrepFlag	Validate a flag emitted by a trusted adapter, not a model-supplied value.
assertArgvValue	Reject an argv value which would otherwise be interpreted as an option.
asyncValidateOrThrow	Validates value against schema asynchronously and returns the coerced result typed as T.
binaryHonorsDoubleDash	Whether a binary in the table can receive the argv terminator.
classifySandboxPathRejection	Classify an unambiguous host escape, or undefined when the path is acceptable.
constructorFromMinter	Select a constructor from a caller-provided minter, never throwing on bad metadata.
createCompartmentRuntime	Construct a minimal SES-backed in-process guest. The runtime boundary is intentionally explicit.
createEvaluateJavascriptTool	Assemble the SES JavaScript evaluation tool.
createGuestRunner	Host runner that retains capability implementations and exposes only enumerated names.
createGuestRuntime	In-process runtime factory for environments where SES is available.
createModelPath	Create a presentation/normalisation path only; this is NOT a containment guarantee. Every filesystem use must still pass through PathTranslator.toRelative().
createModelWriteRoot	Construct the model root representation used in model-facing outcomes.
createPathTranslator	Create a translator that applies the five-step, workspace-relative path policy.
createRunShellCommandTool	Assemble the factory-style run_shell_command tool. It is intentionally not a bulk-registered battery value. cwd is a model-supplied workspace-relative path and receives the complete PathTranslator gauntlet, including symlink refusal; the default is the workspace root.
createSandbox	Admit one process-global sandbox. Drift is detection, not prevention: SRT consults its proxies per request, so a widening can affect an already-spawned child for its lifetime.
createSandboxEpoch	Issue a fresh epoch token without requiring a type assertion.
createSandboxMedia	Construct the staged media value returned by a mutating sandbox operation.
createSandboxMediaReader	Create a non-describable, replayable reader over a sandbox file.
createSandboxObservability	Build the one event surface consumed by WP-A1's sandbox handle.
emitBypass	Emit a loud audit-only bypass report.
emitDriftCheck	Emit a drift result, including an explicit network-domain skip when requested.
emitFallback	Emit the permanent loud report for an unsandboxed invocation.
emitFsNodeVersion	Emit the SRT version used by the in-process evaluator.
implementsArtifactMinter	Structural guard.
implementsGuestLimits	Guard for resolved guest limits.
implementsGuestRuntime	Structural guard.
implementsHostcallQuotas	Guard for resolved host quotas.
implementsMimeResolver	MIME resolver guard.
implementsPathTranslator	Structural guard.
implementsSandboxFileSystem	Structural guard.
implementsSandboxPolicy	Duck-type guard for SandboxPolicy.
implementsSandboxPolicyEnforcer	Structural guard.
implementsSandboxSearch	Structural guard.
isGuestOutcome	Type-only terminal outcome helper.
isRejectedSandboxPath	Return whether a path is an unambiguous host escape before normalisation.
normalizeSandboxPath	Normalise a model path; leading separators denote the sandbox root.
passesSchema	Returns true if value satisfies schema without throwing.
preflightSandbox	Run the once-only, fail-closed environment gauntlet used by createSandbox().
quoteShellArgs	Quote argv using SRT's maintained POSIX implementation.
quoteShellValue	Quote one command string as one shell argument.
reportSandboxBypass	Emit a bypass through the canonical sink for consumers that do not retain the adapter.
resolveGuestLimits	Resolve and validate all seven guest limits exactly once.
resolveHostcallQuotas	Resolve and validate all three hostcall quotas exactly once.
resolveMime	Run a resolver and fall back to the extension resolver when it declines. The callback supplied to consumer code is always bounded by maxPeekBytes.
runSandboxConformance	Run protocol checks for every framed surface, including laziness and the mandatory terminal frame.
sandboxedExecutor	Create a BinaryExecutor that wraps invocations unless an explicitly audited bypass applies.
validateBinShell	Validate the shell selected by the Node SRT adapter.
validateOrThrow	Validates value against schema synchronously and returns the coerced result typed as T.

References

createSandboxTools

Re-exports createSandboxTools

---

forgeSandboxTools

Re-exports forgeSandboxTools

---

sandboxToolDescriptions

Re-exports sandboxToolDescriptions

---

SandboxToolsOptions

Re-exports SandboxToolsOptions