execenv

Documentation

Index

• func Close(rt Runtime) error
• func IsApprovalAborted(err error) bool
• func IsErrorCode(err error, code ErrorCode) bool
• func NewCodedError(code ErrorCode, format string, args ...any) error
• func RegisterSandboxFactory(factory SandboxFactory) error
• func WithApprover(ctx context.Context, approver Approver) context.Context
• func WrapCodedError(code ErrorCode, cause error, format string, args ...any) error
• type ApprovalAbortedError
  • func (e *ApprovalAbortedError) Code() ErrorCode
  • func (e *ApprovalAbortedError) Error() string
• type ApprovalRequest
• type ApprovalRequiredError
  • func (e *ApprovalRequiredError) Code() ErrorCode
  • func (e *ApprovalRequiredError) Error() string
• type Approver
  • func ApproverFromContext(ctx context.Context) (Approver, bool)
• type CodedError
• type CommandDecision
• type CommandRequest
• type CommandResult
• type CommandRunner
• type Config
• type ErrorCode
  • func ErrorCodeOf(err error) ErrorCode
• type EscalationReason
• type ExecutionRoute
• type FileSystem
• type PermissionMode
• type Runtime
  • func New(cfg Config) (Runtime, error)
• type SandboxFactory
• type SandboxPermission
• type SandboxPolicy
• type SandboxPolicyType

Functions

func Close

func Close(rt Runtime) error

Close releases optional runtime resources (for example persistent sandbox sessions). Runtimes without cleanup hooks are no-op.

func IsApprovalAborted

func IsApprovalAborted(err error) bool

IsApprovalAborted reports whether err indicates user canceled approval.

func IsErrorCode

func IsErrorCode(err error, code ErrorCode) bool

IsErrorCode reports whether err carries a specific machine-readable code.

func NewCodedError

func NewCodedError(code ErrorCode, format string, args ...any) error

NewCodedError creates a coded error with formatted message.

func RegisterSandboxFactory

func RegisterSandboxFactory(factory SandboxFactory) error

RegisterSandboxFactory registers one sandbox backend factory.

func WithApprover

func WithApprover(ctx context.Context, approver Approver) context.Context

WithApprover injects one approver into context.

func WrapCodedError

func WrapCodedError(code ErrorCode, cause error, format string, args ...any) error

WrapCodedError wraps an existing cause with a stable error code.

Types

type ApprovalAbortedError

type ApprovalAbortedError struct {
	Reason string
}

ApprovalAbortedError indicates user explicitly canceled an approval request.

func (*ApprovalAbortedError) Code

func (e *ApprovalAbortedError) Code() ErrorCode

func (*ApprovalAbortedError) Error

func (e *ApprovalAbortedError) Error() string

type ApprovalRequest

type ApprovalRequest struct {
	ToolName string
	Action   string
	Reason   string
	Command  string
}

ApprovalRequest describes one approval request raised by tools.

type ApprovalRequiredError

type ApprovalRequiredError struct {
	Reason string
}

ApprovalRequiredError indicates that the call should be reviewed by upper application layer. Kernel tool layer does not handle approval workflow.

func (*ApprovalRequiredError) Code

func (e *ApprovalRequiredError) Code() ErrorCode

func (*ApprovalRequiredError) Error

func (e *ApprovalRequiredError) Error() string

type Approver

type Approver interface {
	Approve(context.Context, ApprovalRequest) (bool, error)
}

Approver handles interactive approval decision in upper application layer.

func ApproverFromContext

func ApproverFromContext(ctx context.Context) (Approver, bool)

ApproverFromContext returns approver from context.

type CodedError

type CodedError interface {
	error
	Code() ErrorCode
}

CodedError exposes a stable code for programmatic handling.

type CommandDecision

type CommandDecision struct {
	Route      ExecutionRoute
	Escalation *EscalationReason
}

CommandDecision is runtime routing result for one command request.

type CommandRequest

type CommandRequest struct {
	Command     string
	Dir         string
	Timeout     time.Duration
	IdleTimeout time.Duration
}

CommandRequest is one command execution request.

type CommandResult

type CommandResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

CommandResult is one command execution result.

type CommandRunner

type CommandRunner interface {
	Run(context.Context, CommandRequest) (CommandResult, error)
}

CommandRunner executes shell commands for tools.

type Config

type Config struct {
	PermissionMode PermissionMode
	SandboxType    string
	SafeCommands   []string
	SandboxPolicy  SandboxPolicy

	FileSystem    FileSystem
	HostRunner    CommandRunner
	SandboxRunner CommandRunner
}

Config builds an execution runtime.

type ErrorCode

type ErrorCode string

ErrorCode is a stable machine-readable code for kernel runtime/execution errors.

const (
	ErrorCodeSessionBusy           ErrorCode = "ERR_SESSION_BUSY"
	ErrorCodeApprovalRequired      ErrorCode = "ERR_APPROVAL_REQUIRED"
	ErrorCodeApprovalAborted       ErrorCode = "ERR_APPROVAL_ABORTED"
	ErrorCodeSandboxUnsupported    ErrorCode = "ERR_SANDBOX_UNSUPPORTED"
	ErrorCodeSandboxUnavailable    ErrorCode = "ERR_SANDBOX_UNAVAILABLE"
	ErrorCodeSandboxCommandTimeout ErrorCode = "ERR_SANDBOX_COMMAND_TIMEOUT"
	ErrorCodeSandboxIdleTimeout    ErrorCode = "ERR_SANDBOX_IDLE_TIMEOUT"
	ErrorCodeHostCommandTimeout    ErrorCode = "ERR_HOST_COMMAND_TIMEOUT"
	ErrorCodeHostIdleTimeout       ErrorCode = "ERR_HOST_IDLE_TIMEOUT"
)

func ErrorCodeOf

func ErrorCodeOf(err error) ErrorCode

ErrorCodeOf extracts machine-readable error code, if present.

type EscalationReason

type EscalationReason struct {
	Message string
}

EscalationReason explains why command should leave sandbox path.

type ExecutionRoute

type ExecutionRoute string

ExecutionRoute indicates where one command should run.

const (
	ExecutionRouteSandbox ExecutionRoute = "sandbox"
	ExecutionRouteHost    ExecutionRoute = "host"
)

type FileSystem

type FileSystem interface {
	Getwd() (string, error)
	UserHomeDir() (string, error)
	Open(path string) (*os.File, error)
	ReadDir(path string) ([]os.DirEntry, error)
	Stat(path string) (os.FileInfo, error)
	ReadFile(path string) ([]byte, error)
	WriteFile(path string, data []byte, perm os.FileMode) error
	Glob(pattern string) ([]string, error)
	WalkDir(root string, fn fs.WalkDirFunc) error
}

FileSystem defines file operations for tools. Implementations can target host filesystem or isolated sandboxes.

type PermissionMode

type PermissionMode string

PermissionMode describes top-level execution authorization strategy.

const (
	PermissionModeDefault     PermissionMode = "default"
	PermissionModeFullControl PermissionMode = "full_control"
)

type Runtime

type Runtime interface {
	PermissionMode() PermissionMode
	SandboxType() string
	SandboxPolicy() SandboxPolicy
	FallbackToHost() bool
	FallbackReason() string
	FileSystem() FileSystem
	HostRunner() CommandRunner
	SandboxRunner() CommandRunner
	SafeCommands() []string
	DenyMetaChars() bool
	DecideRoute(command string, sandboxPermission SandboxPermission) CommandDecision
}

Runtime exposes execution primitives and derived security policies.

func New

func New(cfg Config) (Runtime, error)

New builds runtime based on permission mode and optional sandbox type.

type SandboxFactory

type SandboxFactory interface {
	Type() string
	Build(Config) (CommandRunner, error)
}

SandboxFactory builds one sandbox command runner by type.

type SandboxPermission

type SandboxPermission string

SandboxPermission allows tools to request host escalation.

const (
	SandboxPermissionAuto             SandboxPermission = "auto"
	SandboxPermissionRequireEscalated SandboxPermission = "require_escalated"
)

type SandboxPolicy

type SandboxPolicy struct {
	Type             SandboxPolicyType
	NetworkAccess    bool
	WritableRoots    []string
	ReadOnlySubpaths []string
}

SandboxPolicy is a backend-agnostic sandbox policy summary.

type SandboxPolicyType

type SandboxPolicyType string

SandboxPolicyType describes high-level sandbox data boundary semantics.

const (
	SandboxPolicyReadOnly       SandboxPolicyType = "read_only"
	SandboxPolicyWorkspaceWrite SandboxPolicyType = "workspace_write"
	SandboxPolicyDangerFull     SandboxPolicyType = "danger_full_access"
	SandboxPolicyExternal       SandboxPolicyType = "external_sandbox"
)