network

package
v0.12.4 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 59 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrLocalResize         = errors.New("only the local terminal may resize the shared grid")
	ErrSessionEnded        = errors.New("terminal session has ended")
	ErrSlowObserver        = errors.New("terminal observer fell behind; reconnect to recover available history")
	ErrUnsupportedTerminal = errors.New("terminal sharing is not supported on this platform")
)
View Source
var ErrGatewayDisabled = errors.New("gateway is stopped; run agentpack gateway start to enable sharing")

Functions

func CheckTailnet

func CheckTailnet(ctx context.Context) error

CheckTailnet verifies the machine can use local Tailscale identity services.

func ConfigureDetached

func ConfigureDetached(command *exec.Cmd)

ConfigureDetached isolates workers from the launching terminal's lifetime.

func ConsoleSize

func ConsoleSize(input, _ *os.File) (int, int, error)

func EnsureNode

func EnsureNode(ctx context.Context, home, executable string) error

func EnsurePrivateDirectory

func EnsurePrivateDirectory(path string) error

EnsurePrivateDirectory protects both newly created and existing directories.

func FolderIdentity

func FolderIdentity(directory string) (string, error)

func ForgetRecent

func ForgetRecent(home string, info SessionInfo) error

func GatewayEnabled

func GatewayEnabled(home string) (bool, error)

func GatewayURL

func GatewayURL(home string) (string, error)

func NodeRequest

func NodeRequest(ctx context.Context, home, method, path string) ([]byte, error)

func RecordSessionEnvironment

func RecordSessionEnvironment(home, id, digest string) error

func RegisterPresence

func RegisterPresence(home string, info SessionInfo, process *os.Process) (func(), error)

RegisterPresence advertises a native-stdio launch without changing its pipes. Its process is owned by the caller; the node only receives public metadata.

func RestartWorker

func RestartWorker(ctx context.Context, home, id, operationID string) error

func RunTerminal

func RunTerminal(ctx context.Context, home, id string, input *os.File, output io.Writer) (code int, result error)

RunTerminal attaches directly to the worker, so gateway shutdown cannot interrupt the local terminal. Local and browser input share the same PTY. Closing the launching terminal stops its worker, including during reconnect.

func RunWorker

func RunWorker(ctx context.Context, home string, launch WorkerLaunch, ready func(string) error) (int, error)

RunWorker owns a restartable PTY independently of a gateway. ready receives only the non-secret worker ID, which survives supervised child restarts.

func ServeGateway

func ServeGateway(ctx context.Context, options GatewayOptions) error

func SessionEnvironment

func SessionEnvironment(home, id string) (string, error)

SessionEnvironment records only the effective content hash, never configuration or credentials.

func SetGatewayEnabled

func SetGatewayEnabled(home string, enabled bool) error

func SignalConsole

func SignalConsole(uint32) error

func StartWorker

func StartWorker(ctx context.Context, home, executable string, launch WorkerLaunch) (string, error)

func StopWorker

func StopWorker(ctx context.Context, home, id string) error

func WebAssets

func WebAssets() http.Handler

WebAssets serves the embedded React build. webdist holds only a placeholder until `make ui-stage` copies ui/dist in.

func WriteSharingConfig

func WriteSharingConfig(home string, config SharingConfig) error

Types

type Actor added in v0.12.0

type Actor struct {
	Kind string `json:"kind"`
	User string `json:"user,omitempty"`
	Node string `json:"node,omitempty"`
}

Actor is who started or called an operation. It comes from the transport: the local OS user, the gateway's browser account, or a verified tailnet whois. It is never read from request headers or bodies.

func LocalActor added in v0.12.0

func LocalActor(kind string) Actor

LocalActor is the OS user running this process on this machine.

type Attachment

type Attachment struct {
	ID    uint64
	Ready <-chan struct{}
	// contains filtered or unexported fields
}

func (*Attachment) ReadOutput added in v0.11.2

func (attachment *Attachment) ReadOutput() ([]byte, bool)

ReadOutput drains queued bytes after Ready is signaled, preserving order across bursts.

type Gateway

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

func (*Gateway) Handler

func (g *Gateway) Handler() http.Handler

type GatewayMCP

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

func NewGatewayMCP

func NewGatewayMCP(gateway *Gateway) (*GatewayMCP, error)

func (*GatewayMCP) Close

func (m *GatewayMCP) Close() error

func (*GatewayMCP) ServeHTTP

func (m *GatewayMCP) ServeHTTP(w http.ResponseWriter, r *http.Request)

type GatewayOptions

type GatewayOptions struct {
	Home, Address, PublicURL string
	Start                    func(context.Context, SessionInfo) (string, error)
	Packages                 func(context.Context, string) (ProjectContents, error)
	Install                  func(context.Context, string, string, bool) error
	Library                  LibraryOptions
	Assets                   http.Handler
	Version                  string
}

type LibraryOptions added in v0.9.0

type LibraryOptions struct {
	Store      *registry.Store
	Bootstrap  func() error
	Save       func(context.Context, SaveAgentpackInput) (SavedAgentpack, error)
	Preview    func(context.Context, string, string, string) (registry.DiffResult, error)
	Restore    func(context.Context, string, string, string, bool) error
	DraftState func(context.Context, registry.Draft) (registry.DraftState, error)
}

type ProjectContents added in v0.12.0

type ProjectContents struct {
	Packages []ProjectPackage `json:"packages"`
	MCP      []ProjectMCP     `json:"mcp"`
}

ProjectContents is one folder's pack.lock as a node reports it.

type ProjectLaunch added in v0.12.0

type ProjectLaunch struct {
	Harness  string    `json:"harness"`
	Mode     string    `json:"mode"`
	LastUsed time.Time `json:"last_used"`
}

type ProjectMCP added in v0.12.0

type ProjectMCP struct {
	Name      string `json:"name"`
	Source    string `json:"source"`
	Launcher  string `json:"launcher"`
	Status    string `json:"status"`
	Package   string `json:"package"`
	Version   string `json:"version"`
	Integrity string `json:"integrity"`
	Host      string `json:"host"`
	Reason    string `json:"reason"`
}

type ProjectPackage added in v0.12.0

type ProjectPackage struct {
	Module      string `json:"module"`
	Commit      string `json:"commit"`
	ContentHash string `json:"content_hash"`
	CacheKey    string `json:"cache_key"`
	Kind        string `json:"kind"`
	Name        string `json:"name"`
	URL         string `json:"url"`
	Direct      bool   `json:"direct"`
}

type ProjectRow added in v0.12.0

type ProjectRow struct {
	Directory         string           `json:"directory"`
	Name              string           `json:"name"`
	FolderID          string           `json:"folder_id"`
	Available         bool             `json:"available"`
	UnavailableReason string           `json:"unavailable_reason"`
	LastUsed          time.Time        `json:"last_used"`
	Launches          []ProjectLaunch  `json:"launches"`
	Packages          []ProjectPackage `json:"packages"`
	MCP               []ProjectMCP     `json:"mcp"`
	Error             string           `json:"error"`
}

ProjectRow is one folder. Launches are unique per harness and mode, newest first.

func Projects added in v0.12.0

func Projects(ctx context.Context, home string, contents func(context.Context, string) (ProjectContents, error)) ([]ProjectRow, error)

Projects groups recent launches by cleaned directory. Contents are read only for available folders, at most projectReadConcurrency at a time; a failed read sets Error on that row alone.

type RecentFolder

type RecentFolder struct {
	SessionInfo
	Available         bool   `json:"available"`
	UnavailableReason string `json:"unavailable_reason,omitempty"`
}

func RecentFolders

func RecentFolders(home string) ([]RecentFolder, error)

Availability is current filesystem state, never a persisted authorization grant.

type Replay

type Replay struct {
	Offset uint64
	Data   []byte
}

Replay is a byte stream, not a terminal screen snapshot. Offset > 0 means earlier bytes were discarded, including potentially required ANSI state.

type SaveAgentpackInput added in v0.9.0

type SaveAgentpackInput struct {
	Directory   string `json:"directory"`
	Name        string `json:"name,omitempty"`
	AgentpackID string `json:"agentpack_id,omitempty"`
	Label       string `json:"label,omitempty"`
	Mode        string `json:"mode,omitempty"`
	AutoCapture bool   `json:"auto_capture"`
}

type SavedAgentpack added in v0.9.0

type SavedAgentpack struct {
	Agentpack registry.Agentpack `json:"agentpack"`
	Revision  registry.Revision  `json:"revision"`
}

type Session

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

Session owns a single child and PTY. Gateway handlers only attach to it; closing an attachment never signals the child.

func StartSession

func StartSession(command *exec.Cmd, rows, columns uint16) (*Session, error)

func (*Session) Attach

func (session *Session) Attach(local bool, since uint64) (*Attachment, Replay, error)

Attach atomically captures history and subscribes to all subsequent bytes. Only the private local transport may identify an attachment as local. Replay starts at since while that byte is still buffered; otherwise it is the whole buffer.

func (*Session) AttachmentError

func (session *Session) AttachmentError(attachment *Attachment) error

func (*Session) Detach

func (session *Session) Detach(attachment *Attachment)

func (*Session) MarkRestarting

func (session *Session) MarkRestarting() error

MarkRestarting lets attachments distinguish a supervised restart from an exit.

func (*Session) Resize

func (session *Session) Resize(attachment *Attachment, rows, columns uint16) error

func (*Session) State

func (session *Session) State() TerminalState

func (*Session) Stop

func (session *Session) Stop(ctx context.Context) error

Stop is explicit process termination. Gateway shutdown uses Detach instead.

func (*Session) Wait

func (session *Session) Wait(ctx context.Context) (int, error)

func (*Session) WriteInput

func (session *Session) WriteInput(attachment *Attachment, data []byte) error

type SessionInfo

type SessionInfo struct {
	LastUsed       time.Time     `json:"last_used,omitzero"`
	FolderID       string        `json:"folder_id,omitempty"`
	ID             string        `json:"id"`
	Name           string        `json:"name,omitempty"`
	Directory      string        `json:"directory"`
	DefinitionRoot string        `json:"definition_root,omitempty"`
	Harness        string        `json:"harness"`
	Mode           string        `json:"mode"`
	State          TerminalState `json:"state"`
	StartedAt      time.Time     `json:"started_at,omitzero"`
	StartedBy      *Actor        `json:"started_by,omitempty"`
}

func Recent

func Recent(home string) ([]SessionInfo, error)

func RenameSession added in v0.9.3

func RenameSession(ctx context.Context, home, id, name string) (SessionInfo, error)

func Sessions

func Sessions(ctx context.Context, home string) ([]SessionInfo, error)

type SharingConfig

type SharingConfig struct {
	Enabled bool     `json:"enabled"`
	Allow   []string `json:"allow,omitempty"`
}

SharingConfig contains explicit machine/tag exceptions to personal identity. It does not change Tailscale ACLs or expose anything outside the tailnet.

func ReadSharingConfig

func ReadSharingConfig(home string) (SharingConfig, error)

ReadSharingConfig defaults to sharing on, like Agentnet's tailnet discovery: peers still need your own untagged identity or an explicit allow entry.

type TailnetNode

type TailnetNode struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Address string `json:"-"`
	Online  bool   `json:"online"`
	// Version is what a peer's /peer answer reports; empty from a peer that predates it.
	Version string `json:"version,omitempty"`
}

func TailnetNodes

func TailnetNodes(ctx context.Context, home string) ([]TailnetNode, error)

TailnetNodes probes only allowed, online peers learned from the local daemon.

type TerminalOutput

type TerminalOutput struct {
	Offset     uint64        `json:"offset"`
	NextOffset uint64        `json:"next_offset"`
	Output     string        `json:"output"`
	Truncated  bool          `json:"truncated"`
	State      TerminalState `json:"state"`
}

type TerminalState

type TerminalState struct {
	Interactive bool   `json:"interactive"`
	Running     bool   `json:"running"`
	Restarting  bool   `json:"restarting"`
	SharedInput bool   `json:"shared_input,omitempty"`
	Responder   uint64 `json:"responder,omitempty"`
	Rows        uint16 `json:"rows"`
	Columns     uint16 `json:"columns"`
	ExitCode    int    `json:"exit_code"`
}

TerminalState contains no command arguments, environment, or credentials.

type WorkerHTTP

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

func WorkerHandler

func WorkerHandler(session *Session, secret string) (*WorkerHTTP, error)

WorkerHandler is private IPC. The gateway authenticates its own callers, then attaches using this worker's secret. Never expose the secret to browsers.

func (*WorkerHTTP) Restart

func (worker *WorkerHTTP) Restart(ctx context.Context, operationID string) (result error)

Restart keeps the private endpoint stable while the original launch pipeline rebuilds staging and starts a fresh agent. Old attachments receive an ended notice with Restarting=true and reconnect to the new PTY.

func (*WorkerHTTP) ServeHTTP

func (worker *WorkerHTTP) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*WorkerHTTP) Shutdown

func (worker *WorkerHTTP) Shutdown(ctx context.Context) error

Shutdown drains final frames without signaling the child. net/http does not manage hijacked WebSocket connections, so the worker tracks them explicitly.

func (*WorkerHTTP) Stop

func (worker *WorkerHTTP) Stop(ctx context.Context) error

type WorkerLaunch

type WorkerLaunch struct {
	Session     SessionInfo `json:"session"`
	Program     string      `json:"program"`
	Arguments   []string    `json:"arguments"`
	Directory   string      `json:"directory"`
	Environment []string    `json:"environment"`
	Rows        uint16      `json:"rows"`
	Columns     uint16      `json:"columns"`
}

WorkerLaunch is delivered through a private startup pipe, never HTTP or disk. Launching agentpack itself here keeps staging, auth and cleanup in the CLI.

type WorkerRecord

type WorkerRecord struct {
	Session SessionInfo `json:"session"`
	ID      string      `json:"id"`
	PID     int         `json:"pid"`
	Address string      `json:"address"`
	Secret  string      `json:"secret"`
}

WorkerRecord is private connection material, readable only by the local OS user. Public node listings must use a separate allowlisted session view.

Jump to

Keyboard shortcuts

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