egg

package
v0.124.0 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CaptureSessionHistory added in v0.122.0 

func CaptureSessionHistory(agent, cwd, eggDir, home string, startedAfter time.Time) error

CaptureSessionHistory copies the agent's native session history (e.g. Claude's JSONL) into the egg directory as chat.jsonl.gz + chat.meta. Best-effort: errors are logged, never fatal.

func DefaultCacheDirs added in v0.22.0 

func DefaultCacheDirs() []string

DefaultCacheDirs returns OS-standard cache directories that build tools need. Go, npm, pip, cargo, etc. all write to these. No secrets live here.

func DefaultDenyPaths added in v0.20.0 

func DefaultDenyPaths() []string

DefaultDenyPaths returns paths that should be blocked by default in sandboxed sessions.

func ParseChatMeta added in v0.122.0 

func ParseChatMeta(data string) map[string]string

ParseChatMeta parses a simple key=value metadata file.

func ParseFSRules added in v0.20.0 

func ParseFSRules(fs []string, home string) ([]sandbox.Mount, []string, []string)

ParseFSRules splits fs entries into mounts, deny paths, and deny-write paths. Entries are "mode:path" where mode is rw, ro, deny, or deny-write.

func RestoreSessionHistory added in v0.122.0 

func RestoreSessionHistory(agent, cwd, eggDir, home string) (agentSessionID string, err error)

RestoreSessionHistory decompresses chat.jsonl.gz and places it in the agent's native session directory so the agent can resume the conversation. Returns the agent session ID for use with resume flags.

Types

type AgentProfile added in v0.9.8 

type AgentProfile struct {
	Domains       []string // network domains needed (empty = no network)
	EnvVars       []string // required env var names (merged from host)
	PlatformEnv   []string // platform-specific env vars (e.g. macOS Keychain access)
	WriteDirs     []string // relative to $HOME, need write access
	WriteRegex    []string // dirs needing UseRegex (e.g. ".claude" covers .claude.json)
	SettingsFile  string   // agent config file relative to HOME (e.g. ".claude/settings.json")
	SessionDir    string   // agent session storage relative to $HOME (e.g. ".claude/projects")
	ResumeFlag    string   // CLI flag for resuming (e.g. "--resume")
	SessionIDFlag string   // CLI flag for controlling session ID (e.g. "--session-id")
}

AgentProfile declares what an agent needs from the host system. The sandbox merges these into the egg config automatically so users don't need to know agent internals (e.g. where Claude stores config).

func Profile added in v0.9.8 

func Profile(agent string) AgentProfile

Profile returns the agent profile for the given agent name. Unknown agents get a restrictive default (no network, no extra dirs). Platform-specific env vars are injected based on runtime.GOOS.

type BaseField added in v0.23.0 

type BaseField struct {
	Name    string `yaml:"name,omitempty"`
	FS      string `yaml:"fs,omitempty"`
	Network string `yaml:"network,omitempty"`
	Env     string `yaml:"env,omitempty"`
}

BaseField handles the `base` key in egg configs. It can be a scalar string (backward compat: "none", "strict", etc.) or an object with per-section masks.

func (BaseField) HasMasks added in v0.23.0 

func (b BaseField) HasMasks() bool

func (BaseField) IsZero added in v0.23.0 

func (b BaseField) IsZero() bool

func (BaseField) MarshalYAML added in v0.23.0 

func (b BaseField) MarshalYAML() (interface{}, error)

func (*BaseField) UnmarshalYAML added in v0.23.0 

func (b *BaseField) UnmarshalYAML(value *yaml.Node) error

type Client 

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

Client wraps the generated gRPC client for a single egg process.

func Dial 

func Dial(socketPath, tokenPath string) (*Client, error)

Dial connects to an egg's Unix socket and reads its auth token.

func (*Client) AttachSession 

func (c *Client) AttachSession(ctx context.Context, sessionID string) (pb.Egg_SessionClient, error)

AttachSession opens a bidirectional stream for PTY I/O.

func (*Client) Close 

func (c *Client) Close() error

Close closes the gRPC connection.

func (*Client) Kill 

func (c *Client) Kill(ctx context.Context, sessionID string) error

Kill terminates the session.

func (*Client) Resize 

func (c *Client) Resize(ctx context.Context, sessionID string, rows, cols uint32) error

Resize changes terminal dimensions.

func (*Client) Status added in v0.19.0 

func (c *Client) Status(ctx context.Context) (*pb.StatusResponse, error)

Status returns debug stats from the egg session.

type ConfigSnapshot added in v0.20.0 

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

ConfigSnapshot holds copies of agent config files taken before a session.

func SnapshotAgentConfig added in v0.20.0 

func SnapshotAgentConfig(agent string) *ConfigSnapshot

SnapshotAgentConfig reads critical config files for the given agent and saves their contents.

func (*ConfigSnapshot) Restore added in v0.20.0 

func (s *ConfigSnapshot) Restore()

Restore reverts config files to their pre-session state.

type EggConfig added in v0.8.0 

type EggConfig struct {
	Base                       BaseField         `yaml:"base,omitempty"`
	FS                         []string          `yaml:"fs"`
	Network                    NetworkField      `yaml:"network"`
	Env                        EnvField          `yaml:"env"`
	Resources                  EggResources      `yaml:"resources"`
	Shell                      string            `yaml:"shell"`
	DangerouslySkipPermissions bool              `yaml:"dangerously_skip_permissions"`
	Audit                      bool              `yaml:"audit"`
	Trace                      bool              `yaml:"trace"`
	AgentSettings              map[string]string `yaml:"agent_settings,omitempty"` // agent name -> settings file path
}

EggConfig holds the sandbox and environment configuration for egg sessions.

func DefaultEggConfig added in v0.8.0 

func DefaultEggConfig() *EggConfig

DefaultEggConfig returns the restrictive default config used when no egg.yaml exists. CWD is writable, home is read-only except agent-drilled holes. Sensitive dirs are denied. OS-standard cache dirs are writable so build tools (go, npm, cargo, pip) work out of the box. egg.yaml itself is deny-write so agents can read but not modify their sandbox config.

func DiscoverEggConfig added in v0.8.0 

func DiscoverEggConfig(cwd string, wingDefault *EggConfig) *EggConfig

DiscoverEggConfig looks for egg.yaml in the given directory, falls back to the wing default, then to built-in defaults. Project configs are resolved through the base chain (additive inheritance) before being returned.

func LoadEggConfig added in v0.8.0 

func LoadEggConfig(path string) (*EggConfig, error)

LoadEggConfig reads and parses an egg.yaml file.

func LoadEggConfigFromYAML added in v0.8.0 

func LoadEggConfigFromYAML(yamlStr string) (*EggConfig, error)

LoadEggConfigFromYAML parses an egg config from a YAML string.

func MergeEggConfig added in v0.21.0 

func MergeEggConfig(parent, child *EggConfig) *EggConfig

MergeEggConfig merges a child config on top of a parent config. - fs: append child to parent; child ro/rw overrides parent deny for same path - network: union (dedup); "*" in either -> ["*"] - env: union (dedup); "*" in either -> ["*"] - resources: child wins per-field (non-zero overrides parent) - shell: child wins if non-empty - dangerously_skip_permissions: OR

func ResolveEggConfig added in v0.21.0 

func ResolveEggConfig(path string) (*EggConfig, error)

ResolveEggConfig loads an egg.yaml and resolves its base chain, returning a fully merged config. If base is empty, merges on top of DefaultEggConfig. If base is "none", returns the config as-is (empty slate).

func (*EggConfig) BuildEnv added in v0.8.0 

func (c *EggConfig) BuildEnv() []string

BuildEnv filters the host environment based on the config. SSH_AUTH_SOCK is stripped when ~/.ssh is denied — otherwise the agent can still make outbound SSH connections via the forwarded socket despite the filesystem deny, causing unexpected host-key prompts inside the egg.

func (*EggConfig) BuildEnvMap added in v0.8.0 

func (c *EggConfig) BuildEnvMap() map[string]string

BuildEnvMap returns the environment as a map for proto SpawnRequest.

func (*EggConfig) IsAllEnv added in v0.20.0 

func (c *EggConfig) IsAllEnv() bool

IsAllEnv returns true if the env config passes all environment variables.

func (*EggConfig) NetworkSummary added in v0.20.0 

func (c *EggConfig) NetworkSummary() string

NetworkSummary returns a short description of the network config for logging.

func (*EggConfig) ToSandboxConfig added in v0.8.0 

func (c *EggConfig) ToSandboxConfig() sandbox.Config

ToSandboxConfig converts the egg config to a sandbox.Config.

func (*EggConfig) YAML added in v0.8.0 

func (c *EggConfig) YAML() (string, error)

YAML returns the config serialized as YAML.

type EggResources added in v0.8.0 

type EggResources struct {
	CPU     string `yaml:"cpu"`    // duration: "300s"
	Memory  string `yaml:"memory"` // size: "2GB"
	MaxFDs  uint32 `yaml:"max_fds"`
	MaxPids uint32 `yaml:"max_pids"` // cgroup pids.max (Linux only)
}

EggResources configures resource limits for sandboxed processes.

func (*EggResources) CPUDuration added in v0.8.0 

func (r *EggResources) CPUDuration() time.Duration

CPUDuration parses the CPU field as a duration.

func (*EggResources) MemBytes added in v0.8.0 

func (r *EggResources) MemBytes() uint64

MemBytes parses the Memory field as bytes (supports GB, MB suffixes).

type EnvField added in v0.20.0 

type EnvField []string

EnvField handles YAML unmarshaling of env: string | []string. "*" → ["*"], list → as-is.

func (*EnvField) UnmarshalYAML added in v0.20.0 

func (e *EnvField) UnmarshalYAML(value *yaml.Node) error

type NetworkField added in v0.20.0 

type NetworkField []string

NetworkField handles YAML unmarshaling of network: string | []string. "none" → nil, "*" → ["*"], list → as-is.

func (*NetworkField) UnmarshalYAML added in v0.20.0 

func (n *NetworkField) UnmarshalYAML(value *yaml.Node) error

type RunConfig added in v0.9.0 

type RunConfig struct {
	Agent   string
	CWD     string
	Shell   string
	FS      []string // "rw:./", "deny:~/.ssh"
	Network []string // domain list
	Env     map[string]string
	Rows    uint32
	Cols    uint32

	DangerouslySkipPermissions bool
	CPULimit                   time.Duration
	MemLimit                   uint64
	MaxFDs                     uint32
	PidLimit                   uint32
	Debug                      bool
	Audit                      bool
	Trace                      bool          // wrap sandbox command with strace (Linux only)
	VTE                        bool          // use VTerm snapshot for reconnect instead of replay buffer
	RenderedConfig             string        // effective egg config as YAML (after merge/resolve)
	UserHome                   string        // per-user home directory (relay sessions only)
	IdleTimeout                time.Duration // 0 = disabled; self-terminate after this much idle
	ResumeSessionID            string        // agent session ID to resume (from chat.meta)
}

RunConfig holds everything needed to start a single egg session.

type Server 

type Server struct {
	pb.UnimplementedEggServer
	// contains filtered or unexported fields
}

Server implements the Egg gRPC service — wraps a SINGLE process. Each egg is its own child process with its own socket/PID/token in ~/.wingthing/eggs/<session-id>/.

func NewServer 

func NewServer(dir string) (*Server, error)

NewServer creates a new per-session egg server. dir is the session directory: ~/.wingthing/eggs/<session-id>/

func (*Server) Kill 

func (s *Server) Kill(ctx context.Context, req *pb.KillRequest) (*pb.KillResponse, error)

Kill terminates the session.

func (*Server) Resize 

func (s *Server) Resize(ctx context.Context, req *pb.ResizeRequest) (*pb.ResizeResponse, error)

Resize changes the terminal dimensions.

func (*Server) RunSession added in v0.9.0 

func (s *Server) RunSession(ctx context.Context, rc RunConfig) error

RunSession is the core lifecycle: create sandbox, start agent in PTY, serve gRPC, exit when done.

func (*Server) Session 

func (s *Server) Session(stream pb.Egg_SessionServer) error

Session implements the bidirectional PTY I/O stream.

func (*Server) Status added in v0.19.0 

func (s *Server) Status(ctx context.Context, req *pb.StatusRequest) (*pb.StatusResponse, error)

type Session 

type Session struct {
	ID             string
	PID            int
	Agent          string
	CWD            string
	Network        string // summary: "none", "*", or comma-separated domains
	RenderedConfig string // effective egg config as YAML (after merge/resolve)
	Cols           uint32
	Rows           uint32
	StartedAt      time.Time
	// contains filtered or unexported fields
}

Session holds a single PTY process and its state.

type VTerm added in v0.58.0 

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

VTerm wraps charmbracelet/x/vt with scrollback capture via ScrollOut callback. All methods are thread-safe. Callbacks fire inside Write, so mu is already held.

func NewVTerm added in v0.58.0 

func NewVTerm(cols, rows int) *VTerm

NewVTerm creates a VTerm with the given dimensions.

func (*VTerm) Close added in v0.58.0 

func (v *VTerm) Close() error

Close releases the emulator resources.

func (*VTerm) Resize added in v0.58.0 

func (v *VTerm) Resize(cols, rows int)

Resize changes the terminal dimensions.

func (*VTerm) ScrollbackLen added in v0.58.0 

func (v *VTerm) ScrollbackLen() int

ScrollbackLen returns the number of scrollback lines currently stored.

func (*VTerm) Snapshot added in v0.58.0 

func (v *VTerm) Snapshot() []byte

Snapshot generates a reconnect payload: scrollback + grid + cursor restore. The output is valid ANSI that any terminal emulator can consume directly.

func (*VTerm) Write added in v0.58.0 

func (v *VTerm) Write(p []byte) (int, error)

Write feeds PTY output to the emulator.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.