Documentation
¶
Index ¶
- func CaptureSessionHistory(agent, cwd, eggDir, home string, startedAfter time.Time) error
- func DefaultCacheDirs() []string
- func DefaultDenyPaths() []string
- func FindLiveSessionFile(agent, cwd, home string) (string, error)
- func ParseChatMeta(data string) map[string]string
- func ParseFSRules(fs []string, home string) ([]sandbox.Mount, []string, []string)
- func RestoreSessionHistory(agent, cwd, eggDir, home string) (agentSessionID string, err error)
- type AgentProfile
- type BaseField
- type Client
- func (c *Client) AttachSession(ctx context.Context, sessionID string) (pb.Egg_SessionClient, error)
- func (c *Client) Close() error
- func (c *Client) Kill(ctx context.Context, sessionID string) error
- func (c *Client) Resize(ctx context.Context, sessionID string, rows, cols uint32) error
- func (c *Client) Status(ctx context.Context) (*pb.StatusResponse, error)
- type ConfigSnapshot
- type EggConfig
- func DefaultEggConfig() *EggConfig
- func DiscoverEggConfig(cwd string, wingDefault *EggConfig) *EggConfig
- func LoadEggConfig(path string) (*EggConfig, error)
- func LoadEggConfigFromYAML(yamlStr string) (*EggConfig, error)
- func MergeEggConfig(parent, child *EggConfig) *EggConfig
- func ResolveEggConfig(path string) (*EggConfig, error)
- func (c *EggConfig) BuildEnv(home string) []string
- func (c *EggConfig) BuildEnvMap(home string) map[string]string
- func (c *EggConfig) IsAllEnv() bool
- func (c *EggConfig) NetworkSummary() string
- func (c *EggConfig) ToSandboxConfig(home string) sandbox.Config
- func (c *EggConfig) YAML() (string, error)
- type EggResources
- type EnvField
- type NetworkField
- type RunConfig
- type Server
- func (s *Server) Kill(ctx context.Context, req *pb.KillRequest) (*pb.KillResponse, error)
- func (s *Server) Resize(ctx context.Context, req *pb.ResizeRequest) (*pb.ResizeResponse, error)
- func (s *Server) RunSession(ctx context.Context, rc RunConfig) error
- func (s *Server) Session(stream pb.Egg_SessionServer) error
- func (s *Server) Status(ctx context.Context, req *pb.StatusRequest) (*pb.StatusResponse, error)
- type Session
- type ToolListEntry
- type ToolListResponse
- type ToolListener
- type ToolRequest
- type ToolResponse
- type VTerm
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CaptureSessionHistory ¶ added in v0.122.0
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 FindLiveSessionFile ¶ added in v0.127.0
FindLiveSessionFile locates the live agent JSONL file for an active session. Returns the file path and agent name, or empty strings if not found.
func ParseChatMeta ¶ added in v0.122.0
ParseChatMeta parses a simple key=value metadata file.
func ParseFSRules ¶ added in v0.20.0
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
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) MarshalYAML ¶ added in v0.23.0
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps the generated gRPC client for a single egg process.
func (*Client) AttachSession ¶
AttachSession opens a bidirectional stream for PTY I/O.
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
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
LoadEggConfig reads and parses an egg.yaml file.
func LoadEggConfigFromYAML ¶ added in v0.8.0
LoadEggConfigFromYAML parses an egg config from a YAML string.
func MergeEggConfig ¶ added in v0.21.0
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
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
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. If home is non-empty it is used to expand ~ in FS rules; otherwise os.UserHomeDir().
func (*EggConfig) BuildEnvMap ¶ added in v0.8.0
BuildEnvMap returns the environment as a map for proto SpawnRequest. If home is non-empty it is used to expand ~ in FS rules; otherwise os.UserHomeDir().
func (*EggConfig) IsAllEnv ¶ added in v0.20.0
IsAllEnv returns true if the env config passes all environment variables.
func (*EggConfig) NetworkSummary ¶ added in v0.20.0
NetworkSummary returns a short description of the network config for logging.
func (*EggConfig) ToSandboxConfig ¶ added in v0.8.0
ToSandboxConfig converts the egg config to a sandbox.Config. If home is non-empty it is used to expand ~ in FS rules; otherwise os.UserHomeDir().
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.
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)
ToolNames []string // names of privileged tools (for shim generation)
ToolSocketPath string // path to tool.sock (set by wing, empty = no tools)
}
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 ¶
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
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 ToolListEntry ¶ added in v0.130.0
type ToolListEntry struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
}
ToolListEntry describes one tool for the list action.
type ToolListResponse ¶ added in v0.130.0
type ToolListResponse struct {
Tools []ToolListEntry `json:"tools"`
}
ToolListResponse is returned for the "list" action.
type ToolListener ¶ added in v0.130.0
type ToolListener struct {
// contains filtered or unexported fields
}
ToolListener accepts connections on a Unix socket and dispatches tool execution.
func NewToolListener ¶ added in v0.130.0
func NewToolListener(sockPath string, tools []*config.ToolConfig) (*ToolListener, error)
NewToolListener creates and starts a tool socket listener. sockPath is the path for the Unix socket (e.g. ~/.wingthing/eggs/<session>/tool.sock).
func (*ToolListener) Close ¶ added in v0.130.0
func (tl *ToolListener) Close() error
Close stops the listener and waits for in-flight requests to finish.
func (*ToolListener) Reload ¶ added in v0.130.0
func (tl *ToolListener) Reload(tools []*config.ToolConfig)
Reload replaces the tool configs atomically.
type ToolRequest ¶ added in v0.130.0
type ToolRequest struct {
Action string `json:"action,omitempty"` // "list" for tool discovery
Tool string `json:"tool,omitempty"`
Args []string `json:"args,omitempty"`
}
ToolRequest is sent by `wt tool-call` over the Unix socket.
type ToolResponse ¶ added in v0.130.0
type ToolResponse struct {
ExitCode int `json:"exit_code,omitempty"`
Stdout string `json:"stdout,omitempty"`
Stderr string `json:"stderr,omitempty"`
Error string `json:"error,omitempty"`
}
ToolResponse is returned to the client.
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 (*VTerm) ScrollbackLen ¶ added in v0.58.0
ScrollbackLen returns the number of scrollback lines currently stored.