network

package
v0.13.8 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 68 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 AttachTerminal added in v0.13.0

func AttachTerminal(ctx context.Context, home, id string, since uint64) (*websocket.Conn, error)

AttachTerminal opens a local-viewer connection to an existing worker without taking ownership of it.

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 ConversationAnswerElicitation added in v0.13.0

func ConversationAnswerElicitation(ctx context.Context, home, sessionID, elicitationID, value string) error

ConversationAnswerElicitation forwards an elicitation answer to the session worker.

func ConversationAnswerPermission added in v0.13.0

func ConversationAnswerPermission(ctx context.Context, home, sessionID, requestID, optionID string) error

ConversationAnswerPermission forwards a permission answer to the session worker.

func ConversationLog added in v0.13.0

func ConversationLog(ctx context.Context, home, sessionID string, since int64) ([]acp.LogEntry, error)

ConversationLog reads the worker conversation NDJSON log for a local session.

func ConversationPrompt added in v0.13.0

func ConversationPrompt(ctx context.Context, home, sessionID, text string) error

ConversationPrompt sends a text prompt to the session worker.

func ConversationPromptImages added in v0.13.0

func ConversationPromptImages(ctx context.Context, home, sessionID, text string, images []acp.PromptImage) error

ConversationPromptImages sends a prompt with stored image attachments to the session worker.

func ConversationSnapshot added in v0.13.0

func ConversationSnapshot(ctx context.Context, home, sessionID, nodeID string, since int64) ([]acp.LogEntry, bool, 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, body ...io.Reader) ([]byte, error)

func NodeRequestStream added in v0.13.0

func NodeRequestStream(ctx context.Context, home, method, path string, dst io.Writer, maxBytes int64) error

NodeRequestStream writes a successful node response to dst, stopping after maxBytes.

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 SubscribeConversation added in v0.13.0

func SubscribeConversation(ctx context.Context, home, sessionID, nodeID string, since int64) (<-chan ConversationUpdate, context.CancelFunc, error)

func TerminalReplayTail added in v0.13.0

func TerminalReplayTail(ctx context.Context, home, sessionID string, maxBytes int) (string, error)

TerminalReplayTail returns up to maxBytes from the end of the worker PTY replay.

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"`
	StableNodeID string `json:"stable_node_id,omitempty"` // Verified tailnet identity; Node is the display name.
}

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 AgentCapabilities added in v0.13.0

type AgentCapabilities struct {
	LoadSession         bool                      `json:"loadSession,omitempty"`
	PromptCapabilities  *AgentPromptCapabilities  `json:"promptCapabilities,omitempty"`
	SessionCapabilities *AgentSessionCapabilities `json:"sessionCapabilities,omitempty"`
}

type AgentPromptCapabilities added in v0.13.0

type AgentPromptCapabilities struct {
	Image bool `json:"image,omitempty"`
}

type AgentSession added in v0.13.0

type AgentSession struct {
	ID    string `json:"id"`
	Title string `json:"title,omitempty"`
	Cwd   string `json:"cwd,omitempty"`
}

AgentSession is one resumable agent-side conversation from session/list.

func ListAgentSessions added in v0.13.0

func ListAgentSessions(ctx context.Context, home, directory, harness, definitionRoot, modeName string) ([]AgentSession, error)

ListAgentSessions probes the harness ACP adapter for prior sessions in a workspace.

type AgentSessionCapabilities added in v0.13.0

type AgentSessionCapabilities struct {
	Resume *struct{} `json:"resume,omitempty"`
	Fork   *struct{} `json:"fork,omitempty"`
}

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 ConversationSession added in v0.13.0

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

ConversationSession is the worker-side ACP conversation view.

func NewConversationSession added in v0.13.0

func NewConversationSession(log *acp.EventLog, broker *acp.Broker) *ConversationSession

func (*ConversationSession) AgentCapabilitiesView added in v0.13.0

func (session *ConversationSession) AgentCapabilitiesView() *AgentCapabilities

func (*ConversationSession) AgentExited added in v0.13.0

func (session *ConversationSession) AgentExited() bool

func (*ConversationSession) AnswerElicitation added in v0.13.0

func (session *ConversationSession) AnswerElicitation(ctx context.Context, elicitationID, value string) error

func (*ConversationSession) AnswerPermission added in v0.13.0

func (session *ConversationSession) AnswerPermission(ctx context.Context, requestID, optionID string) error

func (*ConversationSession) Attach added in v0.13.0

func (session *ConversationSession) Attach(since int64) (entries []acp.LogEntry, truncated bool)

func (*ConversationSession) Cancel added in v0.13.0

func (session *ConversationSession) Cancel(ctx context.Context) error

func (*ConversationSession) ConfigJSON added in v0.13.0

func (session *ConversationSession) ConfigJSON() json.RawMessage

func (*ConversationSession) ConversationState added in v0.13.0

func (session *ConversationSession) ConversationState() string

func (*ConversationSession) Prompt added in v0.13.0

func (session *ConversationSession) Prompt(ctx context.Context, input acp.PromptInput) error

func (*ConversationSession) SetAgentCapabilities added in v0.13.0

func (session *ConversationSession) SetAgentCapabilities(capabilities *AgentCapabilities)

func (*ConversationSession) SetConfigOption added in v0.13.0

func (session *ConversationSession) SetConfigOption(ctx context.Context, key string, value json.RawMessage) error

func (*ConversationSession) SetConfigOptions added in v0.13.0

func (session *ConversationSession) SetConfigOptions(raw json.RawMessage)

func (*ConversationSession) SetModes added in v0.13.0

func (session *ConversationSession) SetModes(raw json.RawMessage)

func (*ConversationSession) SetStateChange added in v0.13.0

func (session *ConversationSession) SetStateChange(persistedState string, callback func(string))

type ConversationUpdate added in v0.13.0

type ConversationUpdate struct {
	Entry     acp.LogEntry
	Truncated bool
	Err       error
}

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) (string, error)
	Packages                 func(context.Context, string) (ProjectContents, error)
	Install                  func(context.Context, string, string, bool) error
	Update                   func(context.Context) 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"`
	Transport         string             `json:"transport,omitempty"`
	AgentSessionID    string             `json:"agent_session_id,omitempty"`
	AgentCapabilities *AgentCapabilities `json:"agent_capabilities,omitempty"`
	ConversationState string             `json:"conversation_state,omitempty"`
	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, conversation *ConversationSession, secret, sessionDir 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 replacing the agent process. Terminal attachments reconnect to the new PTY; ACP clients retain the worker endpoint.

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"`
	Transport     string      `json:"transport,omitempty"`
	ForkSessionID string      `json:"fork_session_id,omitempty"`
	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