script

package
v1.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package script defines approved Skill entrypoints and task-scoped process execution. It is independent of the Agent scheduler and sandbox implementation.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrPermission = errors.New("script: permission denied")
	ErrDrift      = errors.New("script: approval drift")
	ErrLimit      = errors.New("script: resource limit")
	ErrClosed     = errors.New("script: executor closed")
)

Functions

func Failure

func Failure(code Code, cause error) error

Failure constructs a sanitized error while preserving its cause for errors.Is.

func Hash

func Hash(b []byte) string

Hash returns the SHA-256 of exact approved bytes.

func ValidPath

func ValidPath(p string) bool

ValidPath accepts canonical, relative slash-separated paths only.

func ValidateArgs

func ValidateArgs(args []string) error

ValidateArgs applies baseline bounds before an optional business validator.

Types

type Approval

type Approval struct {
	Metadata skill.Metadata
	Scripts  map[string]EntryPoint
	Files    map[string]string
	Image    string
	Env      map[string]string
}

Approval pins explicitly registered files at the time of review/initialization.

func Approve

func Approve(ctx context.Context, catalog *skill.Catalog, r Registration) (Approval, error)

Approve pins only explicitly listed files of a loaded Skill. It does not authorize new files after reload, install dependencies or execute anything.

type Code

type Code string

Code is a stable, model-safe execution outcome.

const (
	CodeOK                Code = "ok"
	CodeDisabled          Code = "disabled"
	CodeUnsupportedHost   Code = "unsupported_host"
	CodePermission        Code = "permission_denied"
	CodeScriptMissing     Code = "script_not_found"
	CodeDrift             Code = "approval_drift"
	CodeInvalidArgs       Code = "invalid_arguments"
	CodeDockerUnavailable Code = "docker_unavailable"
	CodeImageMissing      Code = "image_missing"
	CodeImagePull         Code = "image_pull_failed"
	CodeContainer         Code = "container_error"
	CodeScriptFailed      Code = "script_failed"
	CodeTimeout           Code = "timeout"
	CodeCanceled          Code = "canceled"
	CodeResourceLimit     Code = "resource_limit"
	CodeLogLimit          Code = "log_limit"
	CodeOutputLimit       Code = "output_limit"
	CodeWorkspaceLimit    Code = "workspace_limit"
	CodeCleanup           Code = "cleanup_failed"
)

type EntryPoint

type EntryPoint struct {
	Path         string
	Version      string
	ValidateArgs func([]string) error `json:"-"`
}

EntryPoint explicitly permits one script. Version must change when a custom business argument validator changes, so suspended approvals detect policy drift.

type Error

type Error struct {
	Code Code
	// contains filtered or unexported fields
}

Error hides backend paths, credentials and daemon diagnostics from tool output. Unwrap retains machine-readable cancellation and permission causes.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Executor

type Executor interface {
	Fingerprint() string
	CreateWorkspace(context.Context, string) (Workspace, error)
	ValidateWorkspace(context.Context, Workspace) error
	Execute(context.Context, Request) (Result, error)
	ReleaseWorkspace(context.Context, Workspace) error
	OpenFile(context.Context, Workspace, string) (io.ReadCloser, error)
	Close(context.Context) error
}

Executor is the sandbox boundary. Implementations own task isolation, file access and process cleanup; an Agent never assumes a particular runtime.

type File

type File struct {
	Name string `json:"name"`
	Path string `json:"path"`
	Size int64  `json:"size"`
}

File is a safe logical reference, relative to the task workspace.

type Registration

type Registration struct {
	SkillID     string
	Fingerprint string
	Scripts     []EntryPoint
	Files       []string
	Image       string
	Env         map[string]string
}

Registration is application-owned trust, never metadata read from SKILL.md. Files lists extra imports/assets required by Scripts; all files are pinned.

type Request

type Request struct {
	SkillID          string
	SkillFingerprint string
	ScriptPath       string
	Args             []string
	Workspace        Workspace
	Timeout          time.Duration
}

Request is supplied by trusted host code. Models receive only SkillID, ScriptPath and Args through the bound tool, never Workspace or Timeout.

type Result

type Result struct {
	Success     bool   `json:"success"`
	Code        Code   `json:"code"`
	ExitCode    int    `json:"exit_code"`
	Stdout      string `json:"stdout"`
	Stderr      string `json:"stderr"`
	DurationMS  int64  `json:"duration_ms"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	Files       []File `json:"files"`
	Started     bool   `json:"-"`
}

Result includes partial logs and known effects on every execution outcome.

type Workspace

type Workspace struct {
	ID    string `json:"id"`
	Owner string `json:"owner"`
}

Workspace is an opaque framework-created reference. It is never a host path.

Directories

Path Synopsis
Package docker runs approved Python Skill scripts in disposable containers.
Package docker runs approved Python Skill scripts in disposable containers.

Jump to

Keyboard shortcuts

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