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
- func EnvelopePayload(envelope Envelope) ([]byte, error)
- func HostSAS(hostID string, publicKey []byte) string
- func SignEnvelope(private ed25519.PrivateKey, envelope *Envelope) error
- func VerifyEnvelope(public ed25519.PublicKey, envelope Envelope, now time.Time, ...) error
- type AgentInfo
- type AgentModeOption
- type Attachment
- type ClientEnvelope
- type Envelope
- type HostHealth
- type HostHealthReason
- type HostView
- type IndexStatus
- type Message
- type ModelOption
- type Notification
- type PolicySummary
- type ProjectView
- type PromptOptions
- type PromptQueue
- type PromptQueueItem
- type RunEvent
- type RunInfo
- type RunOptions
- type RunSpec
- type RunView
- type SearchHit
- type ServerEnvelope
- type Session
- type SessionKey
- type SessionView
- type Task
- type TaskRef
- type Transcript
- type UpdateStatus
- type Usage
Constants ¶
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" )
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.
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 ¶
EnvelopePayload returns the deterministic bytes covered by a command signature. Struct field order is stable in encoding/json.
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.
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 ¶
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.