codeexecutor

type Capabilities ¶ added in v0.5.0

type Capabilities struct {
	Isolation      string
	NetworkAllowed bool
	ReadOnlyMount  bool
	Streaming      bool
	MaxDiskBytes   int64
}

Capabilities describes engine capabilities for selection.

type CodeBlock ¶

type CodeBlock struct {
	Code     string `json:"code"`
	Language string `json:"language"`
}

CodeBlock represents a single block of code to be executed.

func ExtractCodeBlock(
	input string,
	delimiter CodeBlockDelimiter,
) []CodeBlock

type CodeBlockDelimiter ¶

type CodeBlockDelimiter struct {
	Start string
	End   string
}

CodeBlockDelimiter defines the start and end delimiters for code blocks.

type CodeExecutionInput ¶

type CodeExecutionInput struct {
	CodeBlocks  []CodeBlock `json:"code_blocks"`
	ExecutionID string      `json:"execution_id,omitempty"`
}

CodeExecutionInput is the input for code execution.

type CodeExecutionResult ¶

type CodeExecutionResult struct {
	Output      string `json:"output"`
	OutputFiles []File `json:"output_files,omitempty"`
}

CodeExecutionResult is the result of code execution including files.

func (r CodeExecutionResult) String() string

type CodeExecutor ¶

type CodeExecutor interface {
	// ExecuteCode executes the code blocks provided in the input and
	// returns the result.
	ExecuteCode(context.Context, CodeExecutionInput) (CodeExecutionResult, error)
	// CodeBlockDelimiter returns the delimiters used for code blocks.
	CodeBlockDelimiter() CodeBlockDelimiter
}

CodeExecutor executes code blocks via a friendly front-door API.

func NewEnvInjectingCodeExecutor(
	exec CodeExecutor,
	provider RunEnvProvider,
) CodeExecutor

type Engine ¶ added in v0.5.0

type Engine interface {
	Manager() WorkspaceManager
	FS() WorkspaceFS
	Runner() ProgramRunner
	// Describe returns optional capabilities.
	Describe() Capabilities
}

Engine is a backend that provides workspace and execution services.

func NewEngine(
	m WorkspaceManager,
	f WorkspaceFS,
	r ProgramRunner,
) Engine

func NewEnvInjectingEngine(eng Engine, provider RunEnvProvider) Engine

type EngineProvider ¶ added in v0.5.0

type EngineProvider interface {
	Engine() Engine
}

EngineProvider is an optional interface that a CodeExecutor may implement to expose its underlying engine for skill tools.

type File ¶

type File struct {
	Name      string `json:"name"`
	Content   string `json:"content,omitempty"`
	MIMEType  string `json:"mime_type"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
}

File represents a file generated during code execution.

type FileRef ¶ added in v0.5.0

type FileRef struct {
	Name      string
	MIMEType  string
	Content   string
	SavedAs   string
	Version   int
	SizeBytes int64
	Truncated bool
}

FileRef references a file collected from workspace.

type InputRecord ¶ added in v0.5.0

type InputRecord struct {
	From      string    `json:"from"`
	To        string    `json:"to"`
	Resolved  string    `json:"resolved,omitempty"`
	Version   *int      `json:"version,omitempty"`
	Mode      string    `json:"mode,omitempty"`
	Timestamp time.Time `json:"ts"`
}

InputRecord tracks a staged input resolution.

type InputSpec ¶ added in v0.5.0

type InputSpec struct {
	From string
	To   string
	Mode string
	Pin  bool
}

InputSpec declares a single input mapping into the workspace.

From supports schemes:

• artifact://name[@version]
• host://abs/path
• workspace://rel/path
• skill://name/rel/path

To is a workspace-relative destination (default: WORK_DIR/inputs/<name>). Mode hints the strategy: "link" (symlink/hardlink where possible) or "copy" (default fallback when link is not possible).

type InteractiveProgramRunner ¶ added in v1.7.0

type InteractiveProgramRunner interface {
	StartProgram(
		ctx context.Context,
		ws Workspace,
		spec InteractiveProgramSpec,
	) (ProgramSession, error)
}

InteractiveProgramRunner is an optional executor capability for multi-turn interactive program execution.

type InteractiveProgramSpec ¶ added in v1.7.0

type InteractiveProgramSpec struct {
	RunProgramSpec
	TTY bool
}

InteractiveProgramSpec describes a session-oriented program invocation in a workspace.

type OutputManifest ¶ added in v0.5.0

type OutputManifest struct {
	Files     []FileRef
	LimitsHit bool
}

OutputManifest is the structured result of CollectOutputs.

type OutputRecord ¶ added in v0.5.0

type OutputRecord struct {
	Globs     []string  `json:"globs"`
	SavedAs   []string  `json:"saved_as,omitempty"`
	Versions  []int     `json:"versions,omitempty"`
	LimitsHit bool      `json:"limits_hit"`
	Timestamp time.Time `json:"ts"`
}

OutputRecord tracks an output collection run.

type OutputSpec ¶ added in v0.5.0

type OutputSpec struct {
	Globs         []string
	MaxFiles      int
	MaxFileBytes  int64
	MaxTotalBytes int64
	Save          bool
	NameTemplate  string
	Inline        bool
}

OutputSpec declares outputs to collect and optionally persist. Globs are workspace-relative patterns; implementations should support ** semantics.

func (s *OutputSpec) UnmarshalJSON(data []byte) error

type ProgramLog ¶ added in v1.7.0

type ProgramLog struct {
	Output     string
	Offset     int
	NextOffset int
}

ProgramLog returns output from a specific offset without mutating the incremental cursor.

type ProgramPoll ¶ added in v1.7.0

type ProgramPoll struct {
	Status     string
	Output     string
	Offset     int
	NextOffset int
	ExitCode   *int
}

ProgramPoll captures the latest incremental output for a running or exited interactive program session.

type ProgramResultProvider ¶ added in v1.7.0

type ProgramResultProvider interface {
	RunResult() RunResult
}

ProgramResultProvider optionally exposes a final RunResult for interactive sessions after they exit.

type ProgramRunner ¶ added in v0.5.0

type ProgramRunner interface {
	RunProgram(ctx context.Context, ws Workspace,
		spec RunProgramSpec) (RunResult, error)
}

ProgramRunner executes programs within a workspace.

type ProgramSession ¶ added in v1.7.0

type ProgramSession interface {
	ID() string
	Poll(limit *int) ProgramPoll
	Log(offset *int, limit *int) ProgramLog
	Write(data string, newline bool) error
	Kill(grace time.Duration) error
	Close() error
}

ProgramSession exposes a running interactive program session.

Implementations are expected to be safe for concurrent use by tool-layer callers. In particular, Poll, Log, Write, Kill, Close, and any optional state/result helpers may be invoked concurrently for the same session.

type ProgramState ¶ added in v1.8.0

type ProgramState struct {
	Status   string
	ExitCode *int
}

ProgramState captures non-streaming session status without advancing any incremental output cursor.

type ProgramStateProvider ¶ added in v1.8.0

type ProgramStateProvider interface {
	State() ProgramState
}

ProgramStateProvider optionally exposes non-destructive session state for lifecycle management and cleanup.

type PutFile ¶ added in v0.5.0

type PutFile struct {
	Path    string // relative to workspace root
	Content []byte
	Mode    uint32 // POSIX mode bits (e.g., 0644, 0755)
}

PutFile describes a file to place into a workspace.

type ResourceLimits ¶ added in v0.5.0

type ResourceLimits struct {
	// CPUPercent is an approximate percentage of one CPU.
	CPUPercent int
	// MemoryMB is a soft limit in megabytes.
	MemoryMB int
	// MaxPIDs limits number of processes/threads.
	MaxPIDs int
}

ResourceLimits restrict program execution resources.

type RunEnvProvider ¶ added in v1.8.0

type RunEnvProvider func(ctx context.Context) map[string]string

RunEnvProvider returns per-run environment variables derived from the execution context. Implementations typically read caller-supplied state (e.g. user tokens) from the context and return them as key-value pairs to be merged into every RunProgramSpec executed by the wrapped engine.

Returned entries never override values already present in the spec's Env map, preserving explicit per-call overrides from tools.

type RunProgramSpec ¶ added in v0.5.0

type RunProgramSpec struct {
	Cmd     string
	Args    []string
	Env     map[string]string
	Cwd     string // relative to workspace root
	Stdin   string
	Timeout time.Duration
	Limits  ResourceLimits
}

RunProgramSpec describes a program invocation in a workspace.

type RunResult ¶ added in v0.5.0

type RunResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
	Duration time.Duration
	TimedOut bool
}

RunResult captures a single program run result.

type SkillMeta ¶ added in v0.5.0

type SkillMeta struct {
	Name     string    `json:"name"`
	RelPath  string    `json:"rel_path"`
	Digest   string    `json:"digest"`
	Mounted  bool      `json:"mounted"`
	StagedAt time.Time `json:"staged_at"`
}

SkillMeta records a staged skill snapshot.

type StageOptions ¶ added in v0.5.0

type StageOptions struct {
	// ReadOnly makes the staged tree non-writable after copy/mount.
	ReadOnly bool
	// AllowMount lets implementations use read-only mounts when possible.
	AllowMount bool
}

StageOptions controls directory staging behavior.

type Workspace ¶ added in v0.5.0

type Workspace struct {
	ID   string
	Path string
}

Workspace represents an isolated execution workspace. Path is host path for local runtime or a logical mount path for containers.

type WorkspaceFS ¶ added in v0.5.0

type WorkspaceFS interface {
	PutFiles(ctx context.Context, ws Workspace,
		files []PutFile) error
	StageDirectory(ctx context.Context, ws Workspace,
		src, to string, opt StageOptions) error
	Collect(ctx context.Context, ws Workspace,
		patterns []string) ([]File, error)
	// StageInputs maps external inputs into workspace according to
	// the provided specs. Implementations should prefer link
	// strategies when Mode=="link" and environment allows it.
	StageInputs(ctx context.Context, ws Workspace,
		specs []InputSpec) error
	// CollectOutputs applies the declarative output spec to collect
	// files and optionally persist artifacts.
	CollectOutputs(ctx context.Context, ws Workspace,
		spec OutputSpec) (OutputManifest, error)
}

WorkspaceFS performs file operations within a workspace.

type WorkspaceManager ¶ added in v0.5.0

type WorkspaceManager interface {
	CreateWorkspace(ctx context.Context, execID string,
		pol WorkspacePolicy) (Workspace, error)
	Cleanup(ctx context.Context, ws Workspace) error
}

WorkspaceManager handles workspace lifecycle.

type WorkspaceMetadata ¶ added in v0.5.0

type WorkspaceMetadata struct {
	Version    int                  `json:"version"`
	CreatedAt  time.Time            `json:"created_at"`
	UpdatedAt  time.Time            `json:"updated_at"`
	LastAccess time.Time            `json:"last_access"`
	Skills     map[string]SkillMeta `json:"skills"`
	Inputs     []InputRecord        `json:"inputs,omitempty"`
	Outputs    []OutputRecord       `json:"outputs,omitempty"`
}

WorkspaceMetadata describes staged skills and recent activity.

func LoadMetadata(root string) (WorkspaceMetadata, error)

type WorkspacePolicy ¶ added in v0.5.0

type WorkspacePolicy struct {
	// Isolated toggles runtime isolation (e.g., container usage).
	Isolated bool
	// Persist keeps workspace after Cleanup when true.
	Persist bool
	// MaxDiskBytes is a soft limit for staged and produced files.
	MaxDiskBytes int64
}

WorkspacePolicy configures workspace behavior.

type WorkspaceRegistry ¶ added in v0.5.0

type WorkspaceRegistry struct {
	// contains filtered or unexported fields
}

WorkspaceRegistry keeps a process-level mapping of logical IDs to created workspaces for reuse within a session.

func NewWorkspaceRegistry() *WorkspaceRegistry

func (r *WorkspaceRegistry) Acquire(
	ctx context.Context, m WorkspaceManager, id string,
) (Workspace, error)