common

Documentation

Index

• Constants
• Variables
• func GenerateLaunchAgentPlist(config LaunchAgentConfig, home string) ([]byte, error)
• func HasCode(err error, code ErrorCode) bool
• func IsExpired(now time.Time, expiresAt *time.Time) bool
• func IsNil(value any) bool
• func ResolveCreateExpiration(now time.Time, defaultSeconds int64, supplied *int64) (*time.Time, error)
• func ResolveUpdateExpiration(now time.Time, current *time.Time, supplied *int64) (*time.Time, error)
• func SupportedRasterMediaType(mediaType string) bool
• func ValidPageURL(value string) bool
• func ValidateID(id string) error
• type Clock
• type CryptoIDGenerator
  • func (CryptoIDGenerator) NewID() (string, error)
• type Error
  • func NewError(code ErrorCode, message string, cause error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorCode
• type IDGenerator
• type LaunchAgentConfig
• type LaunchAgentExecRunner
  • func (LaunchAgentExecRunner) Run(ctx context.Context, command string, args ...string) ([]byte, error)
• type LaunchAgentExecutableResolver
• type LaunchAgentManager
  • func NewLaunchAgentManager(LaunchAgentRunner) (LaunchAgentManager, error)
• type LaunchAgentProviderDescriptor
• type LaunchAgentRunner
• type LaunchAgentStatus
• type ManagedProcess
• type ProcessError
  • func (e *ProcessError) Error() string
  • func (e *ProcessError) Unwrap() error
• type ProcessErrorKind
• type ProcessGroupLauncher
  • func NewProcessGroupLauncher() *ProcessGroupLauncher
  • func (*ProcessGroupLauncher) Launch(ctx context.Context, request ProcessRequest) (ManagedProcess, error)
• type ProcessLauncher
• type ProcessRequest
  • func (r ProcessRequest) Validate() error
• type RasterFormat
  • func DetectRaster(content []byte) (RasterFormat, error)
• type SystemClock
  • func (SystemClock) Now() time.Time

Constants

const (
	LaunchAgentLabel                      = "com.agent-whiteboard.local-agent"
	LaunchAgentControlExecutable          = "/bin/launchctl"
	LaunchAgentProviderPi                 = "pi"
	LaunchAgentProviderCodex              = "codex"
	LaunchAgentPiExecutableEnvironment    = "AGENT_WHITEBOARD_PROVIDER_PI_EXECUTABLE"
	LaunchAgentCodexExecutableEnvironment = "AGENT_WHITEBOARD_PROVIDER_CODEX_EXECUTABLE"
)

const (
	MaxProcessLaunchItems          = 1024
	MaxProcessLaunchAggregateBytes = 1 << 20
)

Variables

var (
	LaunchAgentForegroundGuidance     = unsupportedGuidance(runtime.GOOS)
	ErrLaunchAgentUnsupported         = errors.New(LaunchAgentForegroundGuidance)
	ErrLaunchAgentInstalledNotRunning = errors.New(installedNotRunningGuidance)
	ErrLaunchAgentNotInstalled        = errors.New(notInstalledGuidance)
	// ErrLaunchAgentNotLoaded lets injected runners report launchctl's ordinary missing-service result.
	ErrLaunchAgentNotLoaded = errors.New("LaunchAgent is not loaded")
)

var ErrIDCollision = errors.New("resource id collision")

var ErrProcessOutputOverflow = errors.New("process output unread backlog exceeded")

ErrProcessOutputOverflow reports that a caller did not consume a child output stream before its bounded unread backlog filled. Bytes through the backlog limit remain readable; later bytes from that stream are discarded.

var ErrUnsupportedRaster = errors.New("unsupported raster image")

ErrUnsupportedRaster reports content that is not a decodable supported raster.

Functions

func GenerateLaunchAgentPlist

func GenerateLaunchAgentPlist(config LaunchAgentConfig, home string) ([]byte, error)

GenerateLaunchAgentPlist validates and resolves all configured paths, then returns the deterministic plist for the supplied real user home.

func HasCode

func HasCode(err error, code ErrorCode) bool

func IsExpired

func IsExpired(now time.Time, expiresAt *time.Time) bool

func IsNil

func IsNil(value any) bool

IsNil reports whether value is nil, including a typed nil held by an interface.

func ResolveCreateExpiration

func ResolveCreateExpiration(now time.Time, defaultSeconds int64, supplied *int64) (*time.Time, error)

func ResolveUpdateExpiration

func ResolveUpdateExpiration(now time.Time, current *time.Time, supplied *int64) (*time.Time, error)

func SupportedRasterMediaType

func SupportedRasterMediaType(mediaType string) bool

SupportedRasterMediaType reports whether mediaType is one of the trusted values DetectRaster can produce.

func ValidPageURL

func ValidPageURL(value string) bool

ValidPageURL accepts ordinary HTTPS page URLs and canonical HTTP URLs served from literal IPv4 loopback with no explicit port or a non-default port.

func ValidateID

func ValidateID(id string) error

Types

type Clock

type Clock interface {
	Now() time.Time
}

type CryptoIDGenerator

type CryptoIDGenerator struct{}

func (CryptoIDGenerator) NewID

func (CryptoIDGenerator) NewID() (string, error)

type Error

type Error struct {
	Code    ErrorCode
	Message string
	Err     error
}

func NewError

func NewError(code ErrorCode, message string, cause error) *Error

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorCode

type ErrorCode string

const (
	CodeInvalidRequest       ErrorCode = "invalid_request"
	CodeNotFound             ErrorCode = "not_found"
	CodeContentTooLarge      ErrorCode = "content_too_large"
	CodeUnsupportedMediaType ErrorCode = "unsupported_media_type"
	CodeStorageUnavailable   ErrorCode = "storage_unavailable"
	CodeInternal             ErrorCode = "internal_error"
)

type IDGenerator

type IDGenerator interface {
	NewID() (string, error)
}

type LaunchAgentConfig

type LaunchAgentConfig struct {
	Executable         string
	ConfigPath         string
	Providers          []LaunchAgentProviderDescriptor
	ExecutableResolver LaunchAgentExecutableResolver
}

LaunchAgentConfig contains the durable inputs recorded in the LaunchAgent. Paths must be absolute and clean. ConfigPath may name an absent final file.

type LaunchAgentExecRunner

type LaunchAgentExecRunner struct{}

LaunchAgentExecRunner runs commands directly without a shell and returns combined output.

func (LaunchAgentExecRunner) Run

func (LaunchAgentExecRunner) Run(ctx context.Context, command string, args ...string) ([]byte, error)

type LaunchAgentExecutableResolver

type LaunchAgentExecutableResolver interface {
	LookPath(string) (string, error)
}

LaunchAgentExecutableResolver resolves an executable name using the current process environment. Implementations must return exec.ErrNotFound when it is absent.

type LaunchAgentManager

type LaunchAgentManager interface {
	Install(context.Context, LaunchAgentConfig) error
	Status(context.Context) (LaunchAgentStatus, error)
	Restart(context.Context) error
	Stop(context.Context) error
	Uninstall(context.Context) error
}

LaunchAgentManager owns the per-user managed-agent lifecycle.

func NewLaunchAgentManager

func NewLaunchAgentManager(LaunchAgentRunner) (LaunchAgentManager, error)

NewLaunchAgentManager returns a manager whose lifecycle operations provide exact foreground guidance without invoking the supplied runner.

type LaunchAgentProviderDescriptor

type LaunchAgentProviderDescriptor interface {
	ProviderName() string
	ExecutableName() string
}

LaunchAgentProviderDescriptor describes a registered provider executable. Install only accepts the package's fixed provider names and executable names.

type LaunchAgentRunner

type LaunchAgentRunner interface {
	Run(context.Context, string, ...string) ([]byte, error)
}

LaunchAgentRunner executes one process-control command. LaunchAgentManager implementations pass an absolute command and a complete argument list; no shell is used.

type LaunchAgentStatus

type LaunchAgentStatus struct {
	Installed bool
	Loaded    bool
	Running   bool
	PID       int
}

LaunchAgentStatus intentionally excludes launch arguments, paths, environment, and raw launchctl output.

type ManagedProcess

type ManagedProcess interface {
	Input() io.WriteCloser
	Output() io.Reader
	Errors() io.Reader
	Wait() error
	Terminate() error
	Kill() error
}

ManagedProcess owns process I/O and process-group escalation.

type ProcessError

type ProcessError struct {
	Kind ProcessErrorKind
	Op   string
	Err  error
}

ProcessError is a classified process-group operation failure.

func (*ProcessError) Error

func (e *ProcessError) Error() string

func (*ProcessError) Unwrap

func (e *ProcessError) Unwrap() error

type ProcessErrorKind

type ProcessErrorKind string

ProcessErrorKind classifies process-launch and process-group failures.

const (
	ProcessErrorInvalidRequest     ProcessErrorKind = "invalid_request"
	ProcessErrorExecutable         ProcessErrorKind = "executable"
	ProcessErrorWorkingDirectory   ProcessErrorKind = "working_directory"
	ProcessErrorStart              ProcessErrorKind = "start"
	ProcessErrorCanceled           ProcessErrorKind = "canceled"
	ProcessErrorUnsupported        ProcessErrorKind = "unsupported_platform"
	ProcessErrorUnsafeProcessGroup ProcessErrorKind = "unsafe_process_group"
	ProcessErrorSignal             ProcessErrorKind = "signal"
)

type ProcessGroupLauncher

type ProcessGroupLauncher struct{}

ProcessGroupLauncher starts children in isolated operating-system process groups. Its zero value is ready for use.

func NewProcessGroupLauncher

func NewProcessGroupLauncher() *ProcessGroupLauncher

NewProcessGroupLauncher returns an isolated process launcher.

func (*ProcessGroupLauncher) Launch

func (*ProcessGroupLauncher) Launch(ctx context.Context, request ProcessRequest) (ManagedProcess, error)

Launch validates and starts exactly the requested executable, arguments, environment, and working directory in a new process group.

type ProcessLauncher

type ProcessLauncher interface {
	Launch(context.Context, ProcessRequest) (ManagedProcess, error)
}

ProcessLauncher starts one isolated process from an explicit specification.

type ProcessRequest

type ProcessRequest struct {
	Executable       string
	Arguments        []string
	Environment      []string
	WorkingDirectory string
}

ProcessRequest is a complete, provider-neutral process specification.

func (ProcessRequest) Validate

func (r ProcessRequest) Validate() error

Validate checks the bounded process-launch contract.

type RasterFormat

type RasterFormat struct {
	Extension string
	MediaType string
}

RasterFormat is trusted metadata derived from image bytes, never from a filename or browser-supplied content type.

func DetectRaster

func DetectRaster(content []byte) (RasterFormat, error)

DetectRaster recognizes and config-decodes PNG, JPEG, GIF, and WebP content.

type SystemClock

type SystemClock struct{}

func (SystemClock) Now

func (SystemClock) Now() time.Time