ws

package
v0.10.4 Latest Latest
Warning

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

 Go to latest Published: Feb 11, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Wing → Relay
	TypeWingRegister  = "wing.register"
	TypeWingHeartbeat = "wing.heartbeat"
	TypeTaskChunk     = "task.chunk"
	TypeTaskDone      = "task.done"
	TypeTaskError     = "task.error"

	// Relay → Wing
	TypeTaskSubmit = "task.submit"
	TypeTaskCancel = "task.cancel"

	// PTY (bidirectional)
	TypePTYStart   = "pty.start"   // browser → relay → wing
	TypePTYStarted = "pty.started" // wing → relay → browser
	TypePTYOutput  = "pty.output"  // wing → relay → browser
	TypePTYInput   = "pty.input"   // browser → relay → wing
	TypePTYResize  = "pty.resize"  // browser → relay → wing
	TypePTYExited  = "pty.exited"  // wing → relay → browser
	TypePTYAttach  = "pty.attach"  // browser → relay → wing (reattach)
	TypePTYKill    = "pty.kill"    // browser → relay → wing (terminate session)
	TypePTYDetach  = "pty.detach"  // browser → relay (explicit detach before disconnect)

	// Chat (bidirectional through relay)
	TypeChatStart   = "chat.start"   // browser → relay → wing
	TypeChatStarted = "chat.started" // wing → relay → browser
	TypeChatMessage = "chat.message" // browser → relay → wing
	TypeChatChunk   = "chat.chunk"   // wing → relay → browser
	TypeChatDone    = "chat.done"    // wing → relay → browser
	TypeChatHistory = "chat.history" // wing → relay → browser
	TypeChatDelete  = "chat.delete"  // browser → relay → wing
	TypeChatDeleted = "chat.deleted" // wing → relay → browser

	// Directory listing (bidirectional through relay)
	TypeDirList    = "dir.list"    // browser → relay → wing
	TypeDirResults = "dir.results" // wing → relay → browser

	// Wing → Relay (session reclaim after wing restart)
	TypePTYReclaim = "pty.reclaim"

	// Session sync (relay requests, wing responds; also sent on heartbeat)
	TypeSessionsList = "sessions.list" // relay → wing
	TypeSessionsSync = "sessions.sync" // wing → relay

	// Relay → Wing (control)
	TypeRegistered      = "registered"
	TypeWingUpdate      = "wing.update"
	TypeEggConfigUpdate = "egg.config_update" // relay → wing: push new egg config
	TypeError           = "error"
)

Message types for the relay WebSocket protocol.

Variables

This section is empty.

Functions

This section is empty.

Types

type ChatChunk 

type ChatChunk struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Text      string `json:"text"`
}

ChatChunk carries a streaming response chunk from wing to browser.

type ChatDelete 

type ChatDelete struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
}

ChatDelete requests deletion of a chat session.

type ChatDeleteHandler 

type ChatDeleteHandler func(ctx context.Context, del ChatDelete, write PTYWriteFunc)

ChatDeleteHandler is called when the wing receives a chat.delete.

type ChatDeleted 

type ChatDeleted struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
}

ChatDeleted confirms a chat session was deleted.

type ChatDone 

type ChatDone struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Content   string `json:"content"` // full assistant response
}

ChatDone signals the assistant response is complete.

type ChatHistoryEntry 

type ChatHistoryEntry struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

ChatHistoryEntry is a single message in the history payload.

type ChatHistoryMsg 

type ChatHistoryMsg struct {
	Type      string             `json:"type"`
	SessionID string             `json:"session_id"`
	Messages  []ChatHistoryEntry `json:"messages"`
}

ChatHistoryMsg carries conversation history for a resumed session.

type ChatMessage 

type ChatMessage struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Content   string `json:"content"`
}

ChatMessage carries a user message to the wing.

type ChatMessageHandler 

type ChatMessageHandler func(ctx context.Context, msg ChatMessage, write PTYWriteFunc)

ChatMessageHandler is called when the wing receives a chat.message.

type ChatStart 

type ChatStart struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id,omitempty"` // empty = new, set = resume
	Agent     string `json:"agent"`
}

ChatStart requests a new or resumed chat session.

type ChatStartHandler 

type ChatStartHandler func(ctx context.Context, start ChatStart, write PTYWriteFunc)

ChatStartHandler is called when the wing receives a chat.start request.

type ChatStarted 

type ChatStarted struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Agent     string `json:"agent"`
}

ChatStarted confirms the chat session is ready.

type ChunkSender 

type ChunkSender func(taskID, text string)

ChunkSender sends a text chunk back to the relay for a running task.

type Client 

type Client struct {
	RoostURL  string // e.g. "wss://ws.wingthing.ai/ws/wing"
	Token     string // device auth token
	MachineID string
	Platform  string // runtime.GOOS
	Version   string // build version

	Agents     []string
	Skills     []string
	Labels     []string
	Identities []string
	Projects   []WingProject

	OnTask            TaskHandlerWithChunks
	OnPTY             PTYHandler
	OnChatStart       ChatStartHandler
	OnChatMessage     ChatMessageHandler
	OnChatDelete      ChatDeleteHandler
	OnDirList         DirHandler
	OnUpdate          func(ctx context.Context)
	OnEggConfigUpdate func(ctx context.Context, yamlStr string)
	OnOrphanKill      func(ctx context.Context, sessionID string) // kill egg with no active goroutine
	SessionLister     func(ctx context.Context) []SessionInfo
	// contains filtered or unexported fields
}

Client is an outbound WebSocket client that connects a wing to the roost.

func (*Client) RegisterPTYSession added in v0.7.35 

func (c *Client) RegisterPTYSession(ctx context.Context, sessionID string) (write PTYWriteFunc, input <-chan []byte, cleanup func())

RegisterPTYSession creates an input channel for a reclaimed session so pty.attach/input/resize/kill messages from the relay get routed to it. Returns the input channel and a write function. The caller must start a goroutine to handle the session and clean up when done.

func (*Client) Run 

func (c *Client) Run(ctx context.Context) error

Run connects to the relay and processes tasks until ctx is cancelled. Automatically reconnects on disconnect with exponential backoff.

func (*Client) SendReclaim added in v0.7.0 

func (c *Client) SendReclaim(ctx context.Context, sessionID, agent, cwd string) error

SendReclaim sends a pty.reclaim message to the relay for a surviving session.

type DirEntry added in v0.6.3 

type DirEntry struct {
	Name  string `json:"name"`
	IsDir bool   `json:"is_dir"`
	Path  string `json:"path"`
}

DirEntry is a single entry in a directory listing.

type DirHandler added in v0.6.3 

type DirHandler func(ctx context.Context, req DirList, write PTYWriteFunc)

DirHandler is called when the wing receives a dir.list request.

type DirList added in v0.6.3 

type DirList struct {
	Type      string `json:"type"`
	RequestID string `json:"request_id"`
	Path      string `json:"path"`
	WingID    string `json:"wing_id,omitempty"`
}

DirList requests a directory listing from the wing.

type DirResults added in v0.6.3 

type DirResults struct {
	Type      string     `json:"type"`
	RequestID string     `json:"request_id"`
	Entries   []DirEntry `json:"entries"`
}

DirResults returns directory entries from the wing.

type EggConfigUpdate added in v0.8.0 

type EggConfigUpdate struct {
	Type string `json:"type"`
	YAML string `json:"yaml"` // serialized egg.yaml content
}

EggConfigUpdate pushes a new egg config from relay to wing.

type Envelope 

type Envelope struct {
	Type string `json:"type"`
}

Envelope wraps every WebSocket message with a type field for routing.

type ErrorMsg 

type ErrorMsg struct {
	Type    string `json:"type"`
	Message string `json:"message"`
}

ErrorMsg is sent by the relay for protocol errors.

type PTYAttach 

type PTYAttach struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	PublicKey string `json:"public_key,omitempty"` // new browser ephemeral key
}

PTYAttach requests reattachment to an existing PTY session.

type PTYDetach added in v0.7.19 

type PTYDetach struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
}

PTYDetach explicitly detaches the browser from a PTY session.

type PTYExited 

type PTYExited struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	ExitCode  int    `json:"exit_code"`
	Error     string `json:"error,omitempty"` // crash/error info for display
}

PTYExited tells the browser the process exited.

type PTYHandler 

type PTYHandler func(ctx context.Context, start PTYStart, write PTYWriteFunc, input <-chan []byte)

PTYHandler is called when the wing receives a pty.start request. It should spawn the agent in a PTY and manage I/O. The write function sends messages back through the relay to the browser. The input channel receives raw JSON messages (pty.input and pty.resize) from the browser.

type PTYInput 

type PTYInput struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Data      string `json:"data"` // base64-encoded
}

PTYInput carries keystrokes from browser to wing.

type PTYKill 

type PTYKill struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
}

PTYKill requests termination of a PTY session.

type PTYOutput 

type PTYOutput struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Data      string `json:"data"` // base64-encoded
}

PTYOutput carries raw terminal bytes from wing to browser.

type PTYReclaim added in v0.7.0 

type PTYReclaim struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Agent     string `json:"agent,omitempty"`
	CWD       string `json:"cwd,omitempty"`
}

PTYReclaim is sent by the wing after reconnect to reclaim a surviving egg session.

type PTYResize 

type PTYResize struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Cols      int    `json:"cols"`
	Rows      int    `json:"rows"`
}

PTYResize tells the wing to resize the terminal.

type PTYStart 

type PTYStart struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Agent     string `json:"agent"` // "claude", "codex", "ollama"
	Cols      int    `json:"cols"`
	Rows      int    `json:"rows"`
	PublicKey string `json:"public_key,omitempty"` // browser's ephemeral X25519 (base64)
	CWD       string `json:"cwd,omitempty"`        // working directory for the agent
	WingID    string `json:"wing_id,omitempty"`    // target wing (picks first if empty)
}

PTYStart requests a new interactive terminal session on the wing.

type PTYStarted 

type PTYStarted struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Agent     string `json:"agent"`
	PublicKey string `json:"public_key,omitempty"` // wing's X25519 (base64)
	CWD       string `json:"cwd,omitempty"`        // resolved working directory
}

PTYStarted confirms the PTY session is running.

type PTYWriteFunc 

type PTYWriteFunc func(v any) error

PTYWriteFunc sends a message back to the relay over the wing's WebSocket.

type QueuedTask 

type QueuedTask struct {
	ID        string    `json:"id"`
	UserID    string    `json:"user_id"`
	Identity  string    `json:"identity"`
	Payload   string    `json:"-"` // opaque JSON forwarded to wing
	WingID    string    `json:"wing_id,omitempty"`
	Status    string    `json:"status"` // pending, dispatched
	CreatedAt time.Time `json:"created_at"`
}

QueuedTask is a routing entry in the relay's volatile queue. The relay stores only an opaque payload — it never inspects task content.

type RegisteredMsg 

type RegisteredMsg struct {
	Type   string `json:"type"`
	WingID string `json:"wing_id"`
}

RegisteredMsg is the relay's acknowledgment of a successful wing registration.

type SessionInfo added in v0.7.32 

type SessionInfo struct {
	SessionID      string `json:"session_id"`
	Agent          string `json:"agent"`
	CWD            string `json:"cwd,omitempty"`
	EggConfig      string `json:"egg_config,omitempty"` // YAML config snapshot
	NeedsAttention bool   `json:"needs_attention,omitempty"`
}

SessionInfo describes one active session on a wing.

type SessionsList added in v0.7.32 

type SessionsList struct {
	Type      string `json:"type"`
	RequestID string `json:"request_id"`
}

SessionsList requests the wing's current session list.

type SessionsSync added in v0.7.32 

type SessionsSync struct {
	Type      string        `json:"type"`
	RequestID string        `json:"request_id,omitempty"` // set when responding to sessions.list
	Sessions  []SessionInfo `json:"sessions"`
}

SessionsSync carries the wing's current session list.

type TaskChunk 

type TaskChunk struct {
	Type   string `json:"type"`
	TaskID string `json:"task_id"`
	Text   string `json:"text"`
}

TaskChunk is streamed from the wing back to the relay during execution.

type TaskDone 

type TaskDone struct {
	Type   string `json:"type"`
	TaskID string `json:"task_id"`
}

TaskDone is sent by the wing when a task completes successfully.

type TaskErrorMsg 

type TaskErrorMsg struct {
	Type   string `json:"type"`
	TaskID string `json:"task_id"`
	Error  string `json:"error"`
}

TaskErrorMsg is sent by the wing when a task fails.

type TaskHandler 

type TaskHandler func(ctx context.Context, task TaskSubmit) (output string, err error)

TaskHandler is called when the wing receives a task to execute.

type TaskHandlerWithChunks 

type TaskHandlerWithChunks func(ctx context.Context, task TaskSubmit, send ChunkSender) (output string, err error)

TaskHandlerWithChunks is called when the wing receives a task, with a chunk sender for streaming.

type TaskSubmit 

type TaskSubmit struct {
	Type      string `json:"type"`
	TaskID    string `json:"task_id"`
	Prompt    string `json:"prompt"`
	Skill     string `json:"skill,omitempty"`
	Agent     string `json:"agent,omitempty"`
	Isolation string `json:"isolation,omitempty"`
}

TaskSubmit is sent from the relay to a wing to execute a task.

type WingHeartbeat 

type WingHeartbeat struct {
	Type      string `json:"type"`
	MachineID string `json:"machine_id"`
}

WingHeartbeat is sent by the wing every 30s.

type WingProject added in v0.6.0 

type WingProject struct {
	Name    string `json:"name"`               // directory name (e.g. "wingthing")
	Path    string `json:"path"`               // absolute path (e.g. "/Users/ehrlich/repos/wingthing")
	ModTime int64  `json:"mod_time,omitempty"` // unix timestamp of last modification
}

WingProject is a project directory discovered on the wing.

type WingRegister 

type WingRegister struct {
	Type       string        `json:"type"`
	MachineID  string        `json:"machine_id"`
	Platform   string        `json:"platform,omitempty"` // runtime.GOOS (e.g. "darwin", "linux")
	Version    string        `json:"version,omitempty"`  // build version (e.g. "v0.7.35")
	Agents     []string      `json:"agents"`
	Skills     []string      `json:"skills"`
	Labels     []string      `json:"labels"`
	Identities []string      `json:"identities"`
	Projects   []WingProject `json:"projects,omitempty"`
}

WingRegister is sent by the wing on connect.

type WingUpdate added in v0.7.3 

type WingUpdate struct {
	Type string `json:"type"`
}

WingUpdate tells the wing to self-update to the latest release.

Source Files

View all Source files

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.