executor

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 5, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package executor provides pluggable command execution backends. Agents declare their execution environment in agent.yaml, and the appropriate executor routes Bash tool commands to local shell, Docker containers, AWS SSM sessions, or Kubernetes pods.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Type selects the executor backend: "local", "docker", "ssm", "kubectl".
	// Empty or "local" uses the default local shell executor.
	Type string `yaml:"type"`

	// Options holds backend-specific configuration as key-value pairs.
	//
	// Docker options:
	//   image        - container image (required)
	//   volumes      - comma-separated host:container mount pairs
	//   env          - comma-separated KEY=VALUE environment variables
	//   working_dir  - working directory inside the container
	//   shell        - shell to use (default: "/bin/sh")
	//   platform     - platform flag (e.g., "linux/amd64")
	//
	// SSM options:
	//   instance_id  - EC2 instance ID (required)
	//   region       - AWS region
	//   profile      - AWS CLI profile
	//   timeout      - command timeout in seconds (default: 600)
	//
	// Kubectl options:
	//   pod          - pod name (required)
	//   namespace    - Kubernetes namespace (default: "default")
	//   container    - container name (for multi-container pods)
	//   shell        - shell to use (default: "/bin/sh")
	Options map[string]string `yaml:"options,omitempty"`
}

Config is parsed from the agent.yaml `environment` field.

type DockerExecutor

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

DockerExecutor runs commands inside a long-lived Docker container. The container is started on creation and removed on Close.

func NewDockerExecutor

func NewDockerExecutor(cfg *Config, workingDir string) (*DockerExecutor, error)

NewDockerExecutor creates a Docker container from the given config and returns an executor that runs commands inside it.

func (*DockerExecutor) Close

func (e *DockerExecutor) Close() error

Close stops and removes the Docker container.

func (*DockerExecutor) EnvironmentDescription

func (e *DockerExecutor) EnvironmentDescription() string

EnvironmentDescription returns a description of the Docker execution environment.

func (*DockerExecutor) Execute

func (e *DockerExecutor) Execute(ctx context.Context, command string) ([]byte, error)

Execute runs a command inside the Docker container.

func (*DockerExecutor) Type

func (e *DockerExecutor) Type() string

Type returns "docker".

type Executor

type Executor interface {
	// Execute runs a shell command and returns combined stdout+stderr.
	Execute(ctx context.Context, command string) ([]byte, error)

	// Close releases any resources held by the executor
	// (e.g., stops a long-lived Docker container).
	Close() error

	// Type returns the executor backend name (e.g., "local", "docker", "ssm", "kubectl").
	Type() string

	// EnvironmentDescription returns a human-readable summary of the execution
	// environment, suitable for injection into agent system prompts so the model
	// knows where its tool commands will run.
	EnvironmentDescription() string
}

Executor runs shell commands in an execution environment.

func New

func New(cfg *Config, workingDir string) (Executor, error)

New creates an Executor from the given config. If cfg is nil or has an empty/local type, a LocalExecutor is returned.

type KubeExecutor

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

KubeExecutor runs commands in a Kubernetes pod via the client-go API.

func NewKubeExecutor

func NewKubeExecutor(cfg *Config) (*KubeExecutor, error)

NewKubeExecutor creates an executor targeting a Kubernetes pod. It resolves kubeconfig from in-cluster config, explicit kubeconfig path, or the default loading rules (~/.kube/config, KUBECONFIG env).

func (*KubeExecutor) Close

func (e *KubeExecutor) Close() error

Close is a no-op (pod lifecycle is managed externally).

func (*KubeExecutor) EnvironmentDescription

func (e *KubeExecutor) EnvironmentDescription() string

EnvironmentDescription returns a description of the Kubernetes execution environment.

func (*KubeExecutor) Execute

func (e *KubeExecutor) Execute(ctx context.Context, command string) ([]byte, error)

Execute runs a command in the Kubernetes pod via SPDY exec streaming.

func (*KubeExecutor) Type

func (e *KubeExecutor) Type() string

Type returns "kubectl".

type LocalExecutor

type LocalExecutor struct {
	WorkingDir string
}

LocalExecutor runs commands via local bash shell.

func (*LocalExecutor) Close

func (e *LocalExecutor) Close() error

Close is a no-op for the local executor.

func (*LocalExecutor) EnvironmentDescription

func (e *LocalExecutor) EnvironmentDescription() string

EnvironmentDescription returns a description of the local execution environment.

func (*LocalExecutor) Execute

func (e *LocalExecutor) Execute(ctx context.Context, command string) ([]byte, error)

Execute runs a command in the local shell.

func (*LocalExecutor) Type

func (e *LocalExecutor) Type() string

Type returns "local".

type SSMExecutor

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

SSMExecutor runs commands on an EC2 instance via AWS Systems Manager.

func NewSSMExecutor

func NewSSMExecutor(cfg *Config, workingDir string) (*SSMExecutor, error)

NewSSMExecutor creates an SSM executor targeting the given EC2 instance.

func (*SSMExecutor) Close

func (e *SSMExecutor) Close() error

Close is a no-op for SSM (stateless per-command).

func (*SSMExecutor) EnvironmentDescription

func (e *SSMExecutor) EnvironmentDescription() string

EnvironmentDescription returns a description of the SSM execution environment.

func (*SSMExecutor) Execute

func (e *SSMExecutor) Execute(ctx context.Context, command string) ([]byte, error)

Execute runs a command on the EC2 instance via SSM SendCommand and polls for the result.

func (*SSMExecutor) Type

func (e *SSMExecutor) Type() string

Type returns "ssm".

Jump to

Keyboard shortcuts

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