protocol

package
v0.1.16 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package protocol contains the wire types shared by the hub and the host daemon. The host link is a single WebSocket carrying JSON envelopes. The same types are used by the browser client where noted.

Index

Constants

View Source
const (
	// Version is the host-link protocol version. The hub accepts the current
	// major version and reports a mismatch with an upgrade hint.
	Version = "0.1"

	ActionResume = "resume"
	ActionNew    = "new"
	ActionFork   = "fork"

	ModeTerminal   = "terminal"
	ModeStructured = "structured"

	StateIdle      = "idle"
	StateRunning   = "running"
	StateWaiting   = "waiting_for_input"
	StateCompleted = "completed"
	StateFailed    = "failed"
	StateUnknown   = "unknown"
	StateStarting  = "starting"
	StateStopping  = "stopping"
	StateExited    = "exited"
)
View Source
const (
	UpdateStateIdle        = "idle"
	UpdateStateChecking    = "checking"
	UpdateStateDownloading = "downloading"
	UpdateStateReady       = "ready"
	UpdateStateWaitingIdle = "waiting_for_idle"
	UpdateStateInstalling  = "installing"
	UpdateStateVerifying   = "verifying"
	UpdateStateSuccess     = "success"
	UpdateStateFailed      = "failed"
	UpdateStateRolledBack  = "rolled_back"
	UpdateStateBlocked     = "blocked"
	UpdateStateDisabled    = "disabled"
)

Update states reported by hosts in UpdateStatus.State.

View Source
const (
	TaskDraft           = "draft"
	TaskReady           = "ready"
	TaskQueued          = "queued"
	TaskRunning         = "running"
	TaskWaitingApproval = "waiting_for_approval"
	TaskBlocked         = "blocked"
	TaskCompleted       = "completed"
	TaskFailed          = "failed"
	TaskCancelled       = "cancelled"
)

Task lifecycle. Only explicit transitions are accepted by the API; the hub never starts a task implicitly.

Variables

This section is empty.

Functions

func EnvelopePayload

func EnvelopePayload(envelope Envelope) ([]byte, error)

EnvelopePayload returns the deterministic bytes covered by a command signature. Struct field order is stable in encoding/json.

func HostSAS

func HostSAS(hostID string, publicKey []byte) string

func SignEnvelope

func SignEnvelope(private ed25519.PrivateKey, envelope *Envelope) error

SignEnvelope signs the canonical JSON representation of an envelope. The signature field is excluded from the signed bytes. A fresh nonce and issue time are added when missing so receivers can reject stale or replayed commands.

func VerifyEnvelope

func VerifyEnvelope(public ed25519.PublicKey, envelope Envelope, now time.Time, maxSkew time.Duration) error

VerifyEnvelope checks the signature and issue time. Nonce uniqueness is enforced by the receiver because only it knows which nonces it has seen.

Types

type AgentInfo

type AgentInfo struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Path         string   `json:"path"`
	Supported    bool     `json:"supported"`
	Capabilities []string `json:"capabilities,omitempty"`
	// Untested is true when the detected version is outside the tested band.
	Untested bool `json:"untested,omitempty"`
	// VersionWarning explains an untested or unrecognized version.
	VersionWarning string `json:"version_warning,omitempty"`
}

AgentInfo describes one coding-agent installation on a host.

type AgentModeOption

type AgentModeOption struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

AgentModeOption is a selectable agent/collaboration mode.

type Attachment

type Attachment struct {
	Name string `json:"name"`
	MIME string `json:"mime,omitempty"`
	Data string `json:"data"` // base64
}

Attachment is a user-supplied file forwarded to the host for a prompt. Only the host writes it to disk; the hub never persists file content.

type ClientEnvelope

type ClientEnvelope struct {
	Type       string         `json:"type"`
	RunID      string         `json:"run_id,omitempty"`
	LastSeq    uint64         `json:"last_seq,omitempty"`
	Data       []byte         `json:"data,omitempty"`
	Cols       int            `json:"cols,omitempty"`
	Rows       int            `json:"rows,omitempty"`
	Text       string         `json:"text,omitempty"`
	ApprovalID string         `json:"approval_id,omitempty"`
	Decision   string         `json:"decision,omitempty"`
	Options    *PromptOptions `json:"options,omitempty"`
	// Device signatures are optional for cookie-only browser sessions and
	// mandatory for a device that registered a command-signing key (or when
	// the hub enforces signed commands).
	DeviceAlgorithm string `json:"device_algorithm,omitempty"`
	DeviceTimestamp int64  `json:"device_timestamp,omitempty"`
	DeviceNonce     string `json:"device_nonce,omitempty"`
	DeviceSignature string `json:"device_signature,omitempty"`
}

ClientEnvelope is sent by the browser over the client WebSocket.

type Envelope

type Envelope struct {
	Type      string         `json:"type"`
	Protocol  string         `json:"protocol,omitempty"`
	HostID    string         `json:"host_id,omitempty"`
	HostName  string         `json:"host_name,omitempty"`
	OS        string         `json:"os,omitempty"`
	Arch      string         `json:"arch,omitempty"`
	Version   string         `json:"version,omitempty"`
	Nonce     string         `json:"nonce,omitempty"`
	IssuedAt  int64          `json:"issued_at,omitempty"`
	Signature string         `json:"signature,omitempty"`
	Agents    []AgentInfo    `json:"agents,omitempty"`
	Policy    *PolicySummary `json:"policy,omitempty"`
	Sessions  []Session      `json:"sessions,omitempty"`
	Removed   []SessionKey   `json:"removed,omitempty"`
	Full      bool           `json:"full,omitempty"`
	Features  []string       `json:"features,omitempty"`
	RequestID string         `json:"request_id,omitempty"`
	// TraceID carries the hub HTTP request id across the host link. It is
	// optional and never used as a metric label.
	TraceID string    `json:"trace_id,omitempty"`
	Method  string    `json:"method,omitempty"`
	Params  []byte    `json:"params,omitempty"`
	Result  []byte    `json:"result,omitempty"`
	OK      bool      `json:"ok,omitempty"`
	Error   string    `json:"error,omitempty"`
	Run     *RunSpec  `json:"run,omitempty"`
	Runs    []RunInfo `json:"runs,omitempty"`
	// NativeID reports the native session a structured new-session or fork
	// created. The hub adopts it as a new session and does not modify the
	// source session.
	NativeID   string         `json:"native_id,omitempty"`
	Action     string         `json:"action,omitempty"`
	ForkedFrom string         `json:"forked_from,omitempty"`
	Agent      string         `json:"agent,omitempty"`
	Cwd        string         `json:"cwd,omitempty"`
	Update     *UpdateStatus  `json:"update,omitempty"`
	Index      *IndexStatus   `json:"index,omitempty"`
	Event      *RunEvent      `json:"event,omitempty"`
	Usage      *Usage         `json:"usage,omitempty"`
	RunID      string         `json:"run_id,omitempty"`
	Seq        uint64         `json:"seq,omitempty"`
	Data       []byte         `json:"data,omitempty"`
	Cols       int            `json:"cols,omitempty"`
	Rows       int            `json:"rows,omitempty"`
	Code       int            `json:"code,omitempty"`
	Reason     string         `json:"reason,omitempty"`
	Message    string         `json:"message,omitempty"`
	ApprovalID string         `json:"approval_id,omitempty"`
	Decision   string         `json:"decision,omitempty"`
	Options    *PromptOptions `json:"options,omitempty"`
}

Envelope is the message format of the host link.

type HostHealth

type HostHealth struct {
	State     string             `json:"state"` // healthy, degraded, offline, pending, disabled
	Reasons   []HostHealthReason `json:"reasons"`
	CheckedAt time.Time          `json:"checked_at"`
}

HostHealth is a derived, explainable view of a paired host. Reasons are generated from observed inventory, index, update and connection state; the hub never invents probe results.

type HostHealthReason

type HostHealthReason struct {
	Code     string `json:"code"`
	Severity string `json:"severity"` // info, warning, error
	Message  string `json:"message"`
}

HostHealthReason is one machine-readable cause for a host's health state.

type HostView

type HostView struct {
	ID       string         `json:"id"`
	Name     string         `json:"name"`
	OS       string         `json:"os"`
	Arch     string         `json:"arch"`
	Version  string         `json:"version"`
	Status   string         `json:"status"`
	LastSeen time.Time      `json:"last_seen"`
	Update   *UpdateStatus  `json:"update,omitempty"`
	Agents   []AgentInfo    `json:"agents"`
	Policy   *PolicySummary `json:"policy,omitempty"`
	Index    *IndexStatus   `json:"index,omitempty"`
	Health   *HostHealth    `json:"health,omitempty"`
	Favorite bool           `json:"favorite,omitempty"`
	Pending  bool           `json:"pending,omitempty"`
	SAS      string         `json:"sas,omitempty"`
	Disabled bool           `json:"disabled,omitempty"`
}

HostView is the hub-side projection of a paired host.

type IndexStatus

type IndexStatus struct {
	State   string `json:"state"` // disabled, building, ready, error
	Indexed int    `json:"indexed"`
	Total   int    `json:"total"`
	Bytes   int64  `json:"bytes,omitempty"`
	Error   string `json:"error,omitempty"`
}

IndexStatus is the host-local full-text index progress. It never contains transcript content.

type Message

type Message struct {
	Role       string    `json:"role"`
	Kind       string    `json:"kind,omitempty"` // text, tool_call, tool_result
	Text       string    `json:"text,omitempty"`
	ToolName   string    `json:"tool_name,omitempty"`
	ToolInput  string    `json:"tool_input,omitempty"`
	ToolOutput string    `json:"tool_output,omitempty"`
	Timestamp  time.Time `json:"timestamp"`
}

Message is one entry of a normalized transcript.

type ModelOption

type ModelOption struct {
	ID             string   `json:"id"`
	Provider       string   `json:"provider,omitempty"`
	Name           string   `json:"name"`
	Variants       []string `json:"variants,omitempty"`
	DefaultVariant string   `json:"default_variant,omitempty"`
	Inputs         []string `json:"inputs,omitempty"`
}

ModelOption is one model advertised by a native agent runtime.

type Notification

type Notification struct {
	ID        string    `json:"id"`
	Kind      string    `json:"kind"`
	Title     string    `json:"title"`
	Body      string    `json:"body"`
	RunID     string    `json:"run_id,omitempty"`
	Link      string    `json:"link,omitempty"`
	HostID    string    `json:"host_id,omitempty"`
	HostName  string    `json:"host_name,omitempty"`
	Agent     string    `json:"agent,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	Read      bool      `json:"read"`
}

Notification is a content-free in-app event for the run owner.

type PolicySummary

type PolicySummary struct {
	AllowedRoots  []string `json:"allowed_roots"`
	AllowAllRoots bool     `json:"allow_all_roots,omitempty"`
	AllowedAgents []string `json:"allowed_agents"`
	AllowNew      bool     `json:"allow_new_sessions"`
	AllowFork     bool     `json:"allow_fork"`
	// AllowPersistentApprovals reports whether the agent's own "always"
	// permission option may be granted. Off by default.
	AllowPersistentApprovals bool `json:"allow_persistent_approvals,omitempty"`
}

PolicySummary is the read-only view of the host policy that the hub may display. Enforcement always stays on the host.

type ProjectView

type ProjectView struct {
	HostID   string    `json:"host_id"`
	HostName string    `json:"host_name"`
	Cwd      string    `json:"cwd"`
	Name     string    `json:"name"`
	Branch   string    `json:"git_branch,omitempty"`
	RepoRoot string    `json:"repo_root,omitempty"`
	RepoURL  string    `json:"repo_url,omitempty"`
	Sessions int       `json:"sessions"`
	Active   int       `json:"active"`
	Agents   []string  `json:"agents"`
	LastAt   time.Time `json:"last_at"`
}

ProjectView groups native sessions that share a working directory on one host. The hub never stores file contents; this is metadata only.

type PromptOptions

type PromptOptions struct {
	Model       string       `json:"model,omitempty"`
	Provider    string       `json:"provider,omitempty"`
	Variant     string       `json:"variant,omitempty"`
	AgentMode   string       `json:"agent_mode,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
}

PromptOptions are optional per-prompt agent settings. Empty values keep the session's existing configuration.

type PromptQueue

type PromptQueue struct {
	Items  []PromptQueueItem `json:"items"`
	Paused bool              `json:"paused"`
}

PromptQueue is the queue view for one run.

type PromptQueueItem

type PromptQueueItem struct {
	ID          string         `json:"id"`
	RunID       string         `json:"run_id"`
	UserID      string         `json:"-"`
	DeviceID    string         `json:"-"`
	Text        string         `json:"text"`
	Options     *PromptOptions `json:"options,omitempty"`
	Position    int            `json:"position"`
	ScheduledAt *time.Time     `json:"scheduled_at,omitempty"`
	State       string         `json:"state"`
	Attempts    int            `json:"attempts"`
	LastError   string         `json:"last_error,omitempty"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
}

PromptQueueItem is one queued structured prompt. Only metadata and the prompt itself are stored on the hub; the agent still runs on the host.

type RunEvent

type RunEvent struct {
	Type       string   `json:"type"`
	RunID      string   `json:"run_id,omitempty"`
	Seq        uint64   `json:"seq,omitempty"`
	MessageID  string   `json:"message_id,omitempty"`
	CallID     string   `json:"call_id,omitempty"`
	ApprovalID string   `json:"approval_id,omitempty"`
	Role       string   `json:"role,omitempty"`
	Text       string   `json:"text,omitempty"`
	ToolName   string   `json:"tool_name,omitempty"`
	ToolInput  string   `json:"tool_input,omitempty"`
	ToolOutput string   `json:"tool_output,omitempty"`
	Action     string   `json:"action,omitempty"`
	Resources  []string `json:"resources,omitempty"`
	Decision   string   `json:"decision,omitempty"`
	State      string   `json:"state,omitempty"`
	Error      string   `json:"error,omitempty"`
}

RunEvent is a normalized structured-mode event. Terminal runs do not use it.

type RunInfo

type RunInfo struct {
	RunID     string    `json:"run_id"`
	SessionID string    `json:"session_id,omitempty"`
	Agent     string    `json:"agent"`
	Mode      string    `json:"mode,omitempty"`
	State     string    `json:"state"`
	StartedAt time.Time `json:"started_at"`
}

RunInfo is reported by a host after reconnect so the hub can adopt runs that survived a hub restart.

type RunOptions

type RunOptions struct {
	Models          []ModelOption     `json:"models"`
	Modes           []AgentModeOption `json:"modes"`
	CurrentModel    string            `json:"current_model,omitempty"`
	CurrentProvider string            `json:"current_provider,omitempty"`
	CurrentVariant  string            `json:"current_variant,omitempty"`
	CurrentMode     string            `json:"current_mode,omitempty"`
	SupportsFiles   bool              `json:"supports_files"`
}

RunOptions are the real capabilities and current settings of a live run.

type RunSpec

type RunSpec struct {
	RunID     string `json:"run_id"`
	SessionID string `json:"session_id,omitempty"`
	Agent     string `json:"agent"`
	NativeID  string `json:"native_id,omitempty"`
	Cwd       string `json:"cwd"`
	Action    string `json:"action"`
	Mode      string `json:"mode"`
	Cols      int    `json:"cols"`
	Rows      int    `json:"rows"`
	// Force resumes a session that a best-effort process scan reports as open
	// in a native terminal. The hub only sets it after an explicit,
	// step-up-confirmed user decision; the host still enforces run uniqueness.
	Force bool `json:"force,omitempty"`
}

RunSpec is sent from the hub to the host to start a run.

type RunView

type RunView struct {
	ID            string     `json:"id"`
	SessionID     string     `json:"session_id,omitempty"`
	HostID        string     `json:"host_id"`
	HostName      string     `json:"host_name,omitempty"`
	SessionTitle  string     `json:"session_title,omitempty"`
	Agent         string     `json:"agent,omitempty"`
	Cwd           string     `json:"cwd,omitempty"`
	GitBranch     string     `json:"git_branch,omitempty"`
	Mode          string     `json:"mode"`
	State         string     `json:"state"`
	LeaseDeviceID string     `json:"lease_device_id,omitempty"`
	LastEventSeq  uint64     `json:"last_event_seq,omitempty"`
	StartedAt     time.Time  `json:"started_at"`
	EndedAt       *time.Time `json:"ended_at,omitempty"`
	ErrorCode     string     `json:"error_code,omitempty"`
	ErrorMessage  string     `json:"error_message,omitempty"`
	// PendingApproval is the newest unresolved approval request, so a page
	// reload can render the approval card without replaying the whole stream.
	PendingApproval *RunEvent `json:"pending_approval,omitempty"`
}

RunView is the hub-side projection of a run.

type SearchHit

type SearchHit struct {
	SessionID string    `json:"session_id,omitempty"`
	HostID    string    `json:"host_id,omitempty"`
	HostName  string    `json:"host_name,omitempty"`
	NativeID  string    `json:"native_id"`
	Agent     string    `json:"agent"`
	Title     string    `json:"title"`
	Snippet   string    `json:"snippet"`
	At        time.Time `json:"at"`
}

SearchHit is one federated search result from a host.

type ServerEnvelope

type ServerEnvelope struct {
	Type     string        `json:"type"`
	Epoch    string        `json:"epoch,omitempty"`
	Host     *HostView     `json:"host,omitempty"`
	Hosts    []HostView    `json:"hosts,omitempty"`
	Session  *SessionView  `json:"session,omitempty"`
	Sessions []SessionView `json:"sessions,omitempty"`
	Run      *RunView      `json:"run,omitempty"`
	Event    *RunEvent     `json:"event,omitempty"`
	Usage    *Usage        `json:"usage,omitempty"`
	RunID    string        `json:"run_id,omitempty"`
	Seq      uint64        `json:"seq,omitempty"`
	State    string        `json:"state,omitempty"`
	Data     []byte        `json:"data,omitempty"`
	Error    string        `json:"error,omitempty"`
	Message  string        `json:"message,omitempty"`
}

ServerEnvelope is sent to the browser over the client WebSocket.

type Session

type Session struct {
	NativeID        string    `json:"native_id"`
	Agent           string    `json:"agent"`
	Title           string    `json:"title"`
	Cwd             string    `json:"cwd"`
	GitBranch       string    `json:"git_branch,omitempty"`
	RepoRoot        string    `json:"repo_root,omitempty"`
	RepoURL         string    `json:"repo_url,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
	MessageCount    int       `json:"message_count"`
	State           string    `json:"state"`
	ActiveElsewhere bool      `json:"active_elsewhere"`
	Warning         string    `json:"warning,omitempty"`
	// ParentNativeID and ForkedFromNativeID are native relationships reported
	// by the agent store (subagent/child and native fork source). They never
	// replace the session's own native id.
	ParentNativeID     string `json:"parent_native_id,omitempty"`
	ForkedFromNativeID string `json:"forked_from_native_id,omitempty"`
}

Session is the normalized metadata for one native agent session.

type SessionKey

type SessionKey struct {
	Agent    string `json:"agent"`
	NativeID string `json:"native_id"`
}

SessionKey identifies a native session without sending its metadata.

type SessionView

type SessionView struct {
	ID                 string    `json:"id"`
	HostID             string    `json:"host_id"`
	HostName           string    `json:"host_name"`
	Agent              string    `json:"agent"`
	NativeID           string    `json:"native_id"`
	Title              string    `json:"title"`
	Cwd                string    `json:"cwd"`
	GitBranch          string    `json:"git_branch,omitempty"`
	RepoRoot           string    `json:"repo_root,omitempty"`
	RepoURL            string    `json:"repo_url,omitempty"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
	MessageCount       int       `json:"message_count"`
	State              string    `json:"state"`
	ActiveElsewhere    bool      `json:"active_elsewhere"`
	Warning            string    `json:"warning,omitempty"`
	ParentNativeID     string    `json:"parent_native_id,omitempty"`
	ForkedFromNativeID string    `json:"forked_from_native_id,omitempty"`
	// LocalTitle and Tags are per-user hub metadata. They never modify the
	// agent's native title or transcript.
	LocalTitle string   `json:"local_title,omitempty"`
	Tags       []string `json:"tags,omitempty"`
}

SessionView is the hub-side projection of a native session.

type Task

type Task struct {
	ID          string     `json:"id"`
	UserID      string     `json:"-"`
	Title       string     `json:"title"`
	Description string     `json:"description,omitempty"`
	Project     string     `json:"project,omitempty"`
	HostID      string     `json:"host_id,omitempty"`
	HostName    string     `json:"host_name,omitempty"`
	Agent       string     `json:"agent,omitempty"`
	Model       string     `json:"model,omitempty"`
	Mode        string     `json:"mode,omitempty"`
	Priority    string     `json:"priority"`
	Status      string     `json:"status"`
	SessionID   string     `json:"session_id,omitempty"`
	RunID       string     `json:"run_id,omitempty"`
	Result      string     `json:"result,omitempty"`
	Error       string     `json:"error,omitempty"`
	Tags        []string   `json:"tags,omitempty"`
	DependsOn   []string   `json:"depends_on,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	StartedAt   *time.Time `json:"started_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
}

Task is one user-owned unit of agent work. It links to native sessions and runs by id; the hub stores no transcript content with it.

type TaskRef

type TaskRef struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Status string `json:"status"`
}

TaskRef is a compact dependency reference.

type Transcript

type Transcript struct {
	Messages []Message `json:"messages"`
	Next     int       `json:"next,omitempty"`
	Total    int       `json:"total"`
	Warning  string    `json:"warning,omitempty"`
}

Transcript is a page of normalized messages.

type UpdateStatus

type UpdateStatus struct {
	Current       string    `json:"current"`
	Latest        string    `json:"latest,omitempty"`
	Available     bool      `json:"available"`
	Prerelease    bool      `json:"prerelease,omitempty"`
	CheckedAt     time.Time `json:"checked_at"`
	Error         string    `json:"error,omitempty"`
	Channel       string    `json:"channel,omitempty"`
	AutoEnabled   bool      `json:"auto_enabled"`
	InstallIdle   bool      `json:"install_when_idle"`
	State         string    `json:"state,omitempty"`
	Message       string    `json:"message,omitempty"`
	Signature     string    `json:"signature,omitempty"`
	LastAttempt   time.Time `json:"last_attempt,omitempty"`
	LastSuccess   time.Time `json:"last_success,omitempty"`
	Blocked       string    `json:"blocked_version,omitempty"`
	RemoteInstall bool      `json:"remote_install,omitempty"`
}

UpdateStatus is reported by a host after checking the release feed. The hub stores only this metadata so update availability and the host-local updater state can be shown centrally. The hub may toggle RemoteInstall, but the channel, signature policy and release source stay host-local.

type Usage

type Usage struct {
	InputTokens      int64     `json:"input_tokens"`
	OutputTokens     int64     `json:"output_tokens"`
	CacheReadTokens  int64     `json:"cache_read_tokens"`
	CacheWriteTokens int64     `json:"cache_write_tokens"`
	CostUSD          *float64  `json:"cost_usd,omitempty"`
	Source           string    `json:"source,omitempty"` // agent, estimated
	UpdatedAt        time.Time `json:"updated_at,omitempty"`
}

Usage is token and cost metadata reported by an agent runtime. Empty values mean the runtime did not expose that measurement; the hub never invents prices or estimates tokens.

Jump to

Keyboard shortcuts

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