protocol

package module
v0.37.0 Latest Latest
Warning

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

 Go to latest Published: May 2, 2026 License: MIT Imports: 7 Imported by: 0

README

protocol-go

Go types for the GSD Cloud wire protocol — the message format the daemon and relay use to talk to each other over websockets.

Install

go get github.com/gsd-build/protocol-go

Usage

import (
    "encoding/json"

    protocol "github.com/gsd-build/protocol-go"
)

// Decode an incoming frame:
env, err := protocol.ParseEnvelope(data)
if err != nil {
    // handle error
}
switch msg := env.Payload.(type) {
case *protocol.Hello:
    _ = msg.MachineID
case *protocol.Task:
    _ = msg.Prompt
}

// Decode an incoming frame with transport bounds:
env, err = protocol.ParseEnvelopeWithLimits(data, protocol.DefaultEnvelopeLimits())
if err != nil {
    // close or reject the frame
}

// Encode an outgoing frame - marshal the payload struct directly:
data, _ := json.Marshal(&protocol.Hello{
    Type:      protocol.MsgTypeHello,
    MachineID: "machine-1",
})

protocol.ExtractBinding, protocol.ValidateRequestBinding, and protocol.ValidateSessionBinding expose request/session correlation checks for relay and daemon handlers.

See PROTOCOL.md for the wire format specification.

License

MIT — see LICENSE.

Documentation

Overview

Package protocol defines the wire format between the GSD Cloud daemon, the Fly.io relay, and the browser. See PROTOCOL.md for the authoritative specification; every change here must be mirrored in that file.

Index

Constants

View Source 
const (
	DefaultMaxFrameBytes   = 1 << 20
	DefaultMaxDepth        = 32
	DefaultMaxObjectFields = 256
	DefaultMaxArrayItems   = 4096
)
View Source 
const (
	MsgTypeTask                            = "task"
	MsgTypeTaskLifecycle                   = "taskLifecycle"
	MsgTypeStop                            = "stop"
	MsgTypePermissionResponse              = "permissionResponse"
	MsgTypeQuestionResponse                = "questionResponse"
	MsgTypeBrowseDir                       = "browseDir"
	MsgTypeReadFile                        = "readFile"
	MsgTypeMkDir                           = "mkDir"
	MsgTypeMkDirResult                     = "mkDirResult"
	MsgTypeListSkills                      = "listSkills"
	MsgTypeListSkillsResult                = "listSkillsResult"
	MsgTypeCompactRequest      MessageType = "compactRequest"
	MsgTypeContextStatsRequest MessageType = "contextStatsRequest"

	MsgTypeStream                        = "stream"
	MsgTypeTaskStarted                   = "taskStarted"
	MsgTypeTaskComplete                  = "taskComplete"
	MsgTypeTaskError                     = "taskError"
	MsgTypeTaskCancelled                 = "taskCancelled"
	MsgTypePermissionRequest             = "permissionRequest"
	MsgTypeQuestion                      = "question"
	MsgTypeHeartbeat                     = "heartbeat"
	MsgTypeBrowseDirResult               = "browseDirResult"
	MsgTypeReadFileResult                = "readFileResult"
	MsgTypeContextStats      MessageType = "contextStats"
	MsgTypeCompactStatus     MessageType = "compactStatus"

	MsgTypeHello   = "hello"
	MsgTypeWelcome = "welcome"

	MsgTypeMachineStatus              = "machineStatus"
	MsgTypePreviewOpen                = "previewOpen"
	MsgTypePreviewOpenResult          = "previewOpenResult"
	MsgTypePreviewClose               = "previewClose"
	MsgTypePreviewHTTPRequest         = "previewHttpRequest"
	MsgTypePreviewHTTPResponseHead    = "previewHttpResponseHead"
	MsgTypePreviewStreamChunk         = "previewStreamChunk"
	MsgTypePreviewStreamCancel        = "previewStreamCancel"
	MsgTypePreviewWebSocketOpen       = "previewWebSocketOpen"
	MsgTypePreviewWebSocketOpenResult = "previewWebSocketOpenResult"
	MsgTypePreviewWebSocketData       = "previewWebSocketData"
	MsgTypePreviewWebSocketClose      = "previewWebSocketClose"
	MsgTypeLocalServerDetected        = "localServerDetected"

	MsgTypeTerminalOpen     = "terminalOpen"
	MsgTypeTerminalOpened   = "terminalOpened"
	MsgTypeTerminalInput    = "terminalInput"
	MsgTypeTerminalOutput   = "terminalOutput"
	MsgTypeTerminalSnapshot = "terminalSnapshot"
	MsgTypeTerminalResize   = "terminalResize"
	MsgTypeTerminalClose    = "terminalClose"
	MsgTypeTerminalExit     = "terminalExit"
	MsgTypeTerminalError    = "terminalError"

	MsgTypeAgentTerminalStarted         = "agentTerminalStarted"
	MsgTypeAgentTerminalUpdated         = "agentTerminalUpdated"
	MsgTypeAgentTerminalAttach          = "agentTerminalAttach"
	MsgTypeAgentTerminalSnapshotRequest = "agentTerminalSnapshotRequest"
)

Message type constants.

Variables

This section is empty.

Functions

func TraceID added in v0.4.1 

func TraceID(traceparent string) string

TraceID extracts the trace-id component from a W3C traceparent header. Returns "" if the traceparent is empty or malformed. Format: version-traceid-parentid-traceflags (e.g. "00-abc...def-012...789-01")

func ValidateEnvelopeFrame added in v0.21.0 

func ValidateEnvelopeFrame(data []byte, limits EnvelopeLimits) error

ValidateEnvelopeFrame checks transport-level JSON bounds before a frame is unmarshaled into a concrete protocol payload.

func ValidateRequestBinding added in v0.21.0 

func ValidateRequestBinding(expected any, actual any) error

ValidateRequestBinding verifies that an actual message is bound to the same request ID as the expected request message or binding.

func ValidateSessionBinding added in v0.21.0 

func ValidateSessionBinding(expected any, actual any) error

ValidateSessionBinding verifies that an actual message is bound to the same session and channel identifiers as the expected message or binding.

Types

type AgentTerminalAttach added in v0.29.1 

type AgentTerminalAttach struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	ChannelID  string `json:"channelId"`
}

type AgentTerminalPort added in v0.29.1 

type AgentTerminalPort struct {
	Host string `json:"host"`
	Port int    `json:"port"`
	URL  string `json:"url"`
}

type AgentTerminalReadiness added in v0.29.1 

type AgentTerminalReadiness struct {
	State       string `json:"state"`
	Source      string `json:"source,omitempty"`
	MatchedText string `json:"matchedText,omitempty"`
	ReadyAt     string `json:"readyAt,omitempty"`
	TimeoutMs   int    `json:"timeoutMs,omitempty"`
}

type AgentTerminalSnapshotRequest added in v0.29.1 

type AgentTerminalSnapshotRequest struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	ChannelID  string `json:"channelId"`
}

type AgentTerminalStarted added in v0.29.1 

type AgentTerminalStarted struct {
	Type           string                 `json:"type"`
	JobID          string                 `json:"jobId"`
	TerminalID     string                 `json:"terminalId"`
	SessionID      string                 `json:"sessionId"`
	ChannelID      string                 `json:"channelId"`
	TaskID         string                 `json:"taskId,omitempty"`
	ToolCallID     string                 `json:"toolCallId,omitempty"`
	ProjectID      string                 `json:"projectId"`
	CommandPreview string                 `json:"commandPreview"`
	Title          string                 `json:"title"`
	CWD            string                 `json:"cwd"`
	Status         string                 `json:"status"`
	Readiness      AgentTerminalReadiness `json:"readiness"`
	Ports          []AgentTerminalPort    `json:"ports,omitempty"`
	URLs           []string               `json:"urls,omitempty"`
	Seq            int64                  `json:"seq,omitempty"`
	StartedAt      string                 `json:"startedAt"`
}

type AgentTerminalUpdated added in v0.29.1 

type AgentTerminalUpdated struct {
	Type       string                 `json:"type"`
	JobID      string                 `json:"jobId"`
	TerminalID string                 `json:"terminalId"`
	SessionID  string                 `json:"sessionId"`
	ChannelID  string                 `json:"channelId"`
	Status     string                 `json:"status"`
	Readiness  AgentTerminalReadiness `json:"readiness"`
	Ports      []AgentTerminalPort    `json:"ports,omitempty"`
	URLs       []string               `json:"urls,omitempty"`
	Seq        int64                  `json:"seq,omitempty"`
	UpdatedAt  string                 `json:"updatedAt"`
}

type Binding added in v0.21.0 

type Binding struct {
	RequestID  string
	SessionID  string
	ChannelID  string
	MachineID  string
	PreviewID  string
	StreamID   string
	TerminalID string
	TaskID     string
}

Binding contains the protocol identifiers used to bind requests, sessions, channels, and transport streams.

func ExtractBinding added in v0.21.0 

func ExtractBinding(message any) Binding

ExtractBinding returns common correlation identifiers from a protocol message payload or Envelope.

type BrowseDir 

type BrowseDir struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	ChannelID string `json:"channelId"`
	MachineID string `json:"machineId"`
	Path      string `json:"path"`
	Limit     int    `json:"limit,omitempty"`
	Cursor    string `json:"cursor,omitempty"`
}

BrowseDir lists directory contents on the daemon's machine.

type BrowseDirResult 

type BrowseDirResult struct {
	Type       string        `json:"type"`
	RequestID  string        `json:"requestId"`
	ChannelID  string        `json:"channelId"`
	OK         bool          `json:"ok"`
	Entries    []BrowseEntry `json:"entries,omitempty"`
	HasMore    bool          `json:"hasMore,omitempty"`
	NextCursor string        `json:"nextCursor,omitempty"`
	Error      string        `json:"error,omitempty"`
}

BrowseDirResult is the daemon's response to a BrowseDir request.

type BrowseEntry 

type BrowseEntry struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	IsDirectory bool   `json:"isDirectory"`
	Size        int64  `json:"size"`
	ModifiedAt  string `json:"modifiedAt"`
}

BrowseEntry is one row in a directory listing.

type CompactLifecycleStatus added in v0.4.1 

type CompactLifecycleStatus string
const (
	CompactStatusStarted   CompactLifecycleStatus = "started"
	CompactStatusCompleted CompactLifecycleStatus = "completed"
	CompactStatusFailed    CompactLifecycleStatus = "failed"
)

type CompactReason added in v0.4.1 

type CompactReason string
const (
	CompactReasonManual    CompactReason = "manual"
	CompactReasonThreshold CompactReason = "threshold"
	CompactReasonOverflow  CompactReason = "overflow"
)

type CompactRequest added in v0.4.1 

type CompactRequest struct {
	Type         MessageType `json:"type"`
	SessionID    string      `json:"sessionId"`
	ChannelID    string      `json:"channelId"`
	RequestID    string      `json:"requestId"`
	Instructions string      `json:"instructions,omitempty"`
}

type CompactStatus added in v0.4.1 

type CompactStatus struct {
	Type                 MessageType            `json:"type"`
	SessionID            string                 `json:"sessionId"`
	ChannelID            string                 `json:"channelId"`
	RequestID            string                 `json:"requestId"`
	Status               CompactLifecycleStatus `json:"status"`
	Reason               CompactReason          `json:"reason"`
	Instructions         string                 `json:"instructions,omitempty"`
	TokensBefore         *int64                 `json:"tokensBefore"`
	TokensAfter          *int64                 `json:"tokensAfter"`
	ContextWindow        int64                  `json:"contextWindow"`
	ReserveTokens        int64                  `json:"reserveTokens"`
	KeepRecentTokens     int64                  `json:"keepRecentTokens"`
	AutoThresholdPercent float64                `json:"autoThresholdPercent"`
	Summary              string                 `json:"summary,omitempty"`
	FirstKeptEntryID     string                 `json:"firstKeptEntryId,omitempty"`
	Error                string                 `json:"error,omitempty"`
	Source               string                 `json:"source"`
	ObservedAt           time.Time              `json:"observedAt"`
}

type ContextRef added in v0.19.1 

type ContextRef struct {
	Kind       string `json:"kind"`
	Path       string `json:"path"`
	Name       string `json:"name"`
	Size       *int64 `json:"size,omitempty"`
	ModifiedAt string `json:"modifiedAt,omitempty"`
}

type ContextStats added in v0.4.1 

type ContextStats struct {
	Type                 MessageType `json:"type"`
	SessionID            string      `json:"sessionId"`
	ChannelID            string      `json:"channelId"`
	RequestID            string      `json:"requestId,omitempty"`
	Tokens               *int64      `json:"tokens"`
	ContextWindow        int64       `json:"contextWindow"`
	Percent              *float64    `json:"percent"`
	ReserveTokens        int64       `json:"reserveTokens"`
	KeepRecentTokens     int64       `json:"keepRecentTokens"`
	AutoThresholdPercent float64     `json:"autoThresholdPercent"`
	Source               string      `json:"source"`
	ObservedAt           time.Time   `json:"observedAt"`
}

type ContextStatsRequest added in v0.4.1 

type ContextStatsRequest struct {
	Type      MessageType `json:"type"`
	SessionID string      `json:"sessionId"`
	ChannelID string      `json:"channelId"`
	RequestID string      `json:"requestId"`
}

type Envelope 

type Envelope struct {
	Type    string
	Payload any
}

Envelope is a parsed message ready for type-switching.

func ParseEnvelope 

func ParseEnvelope(data []byte) (*Envelope, error)

ParseEnvelope reads raw JSON, looks at the type field, and unmarshals into the correct concrete struct.

func ParseEnvelopeWithLimits added in v0.21.0 

func ParseEnvelopeWithLimits(data []byte, limits EnvelopeLimits) (*Envelope, error)

ParseEnvelopeWithLimits validates frame size, JSON nesting depth, object field counts, and array element counts before parsing the envelope.

func (Envelope) DecodePayload added in v0.32.0 

func (e Envelope) DecodePayload() (any, error)

type EnvelopeLimits added in v0.21.0 

type EnvelopeLimits struct {
	MaxFrameBytes   int
	MaxDepth        int
	MaxObjectFields int
	MaxArrayItems   int
}

EnvelopeLimits bounds protocol frame parsing before payload unmarshalling. Zero values use the default limit for that field.

func DefaultEnvelopeLimits added in v0.21.0 

func DefaultEnvelopeLimits() EnvelopeLimits

DefaultEnvelopeLimits returns the default frame parsing limits.

type Heartbeat 

type Heartbeat struct {
	Type          string `json:"type"`
	MachineID     string `json:"machineId"`
	DaemonVersion string `json:"daemonVersion"`
	Status        string `json:"status"`
	Timestamp     string `json:"timestamp"`
}

Heartbeat is the daemon's 30s health pulse.

type Hello 

type Hello struct {
	Type          string             `json:"type"`
	MachineID     string             `json:"machineId"`
	DaemonVersion string             `json:"daemonVersion"`
	OS            string             `json:"os"`
	Arch          string             `json:"arch"`
	ActiveTasks   []string           `json:"activeTasks,omitempty"`
	Capabilities  *HelloCapabilities `json:"capabilities,omitempty"`
}

Hello is the first frame sent by the daemon after connecting.

type HelloCapabilities added in v0.4.1 

type HelloCapabilities struct {
	Stop                      bool `json:"stop,omitempty"`
	Terminal                  bool `json:"terminal,omitempty"`
	AgentTerminalJobs         bool `json:"agentTerminalJobs,omitempty"`
	ContextRefs               bool `json:"contextRefs,omitempty"`
	PreviewTunnel             bool `json:"previewTunnel,omitempty"`
	PreviewMaxFrameBytes      int  `json:"previewMaxFrameBytes,omitempty"`
	PreviewChunkBytes         int  `json:"previewChunkBytes,omitempty"`
	PreviewWebSocketProtocols bool `json:"previewWebSocketProtocols,omitempty"`
	LocalServerDetection      bool `json:"localServerDetection,omitempty"`
	Skills                    bool `json:"skills,omitempty"`
}

HelloCapabilities describes optional daemon protocol support.

type ListSkills added in v0.22.0 

type ListSkills struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	ChannelID string `json:"channelId"`
	MachineID string `json:"machineId"`
	CWD       string `json:"cwd"`
}

ListSkills asks the daemon to list available skills for a working directory.

type ListSkillsResult added in v0.22.0 

type ListSkillsResult struct {
	Type      string  `json:"type"`
	RequestID string  `json:"requestId"`
	ChannelID string  `json:"channelId"`
	OK        bool    `json:"ok"`
	Skills    []Skill `json:"skills,omitempty"`
	Error     string  `json:"error,omitempty"`
}

ListSkillsResult is the daemon's response to a ListSkills request.

type LocalServerDetected added in v0.20.0 

type LocalServerDetected struct {
	Type       string `json:"type"`
	SessionID  string `json:"sessionId"`
	ChannelID  string `json:"channelId"`
	TaskID     string `json:"taskId,omitempty"`
	ToolUseID  string `json:"toolUseId,omitempty"`
	Host       string `json:"host"`
	Port       int    `json:"port"`
	URL        string `json:"url"`
	Command    string `json:"command,omitempty"`
	Source     string `json:"source"`
	DetectedAt string `json:"detectedAt"`
}

type MachineStatus added in v0.4.1 

type MachineStatus struct {
	Type          string `json:"type"`
	MachineID     string `json:"machineId"`
	State         string `json:"state"`
	PreviousState string `json:"previousState,omitempty"`
	Reason        string `json:"reason,omitempty"`
	OccurredAt    string `json:"occurredAt"`
}

MachineStatus is pushed to all connected browsers when machine presence changes.

type MessageType added in v0.4.1 

type MessageType = string

type MkDir added in v0.2.0 

type MkDir struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	ChannelID string `json:"channelId"`
	MachineID string `json:"machineId"`
	Path      string `json:"path"`
}

MkDir asks the daemon to create a directory.

type MkDirResult added in v0.2.0 

type MkDirResult struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	ChannelID string `json:"channelId"`
	OK        bool   `json:"ok"`
	Error     string `json:"error,omitempty"`
}

MkDirResult is the daemon's response to a MkDir request.

type PermissionRequest 

type PermissionRequest struct {
	Type          string          `json:"type"`
	TaskID        string          `json:"taskId,omitempty"`
	AttemptID     string          `json:"attemptId,omitempty"`
	AttemptNumber int             `json:"attemptNumber,omitempty"`
	SessionID     string          `json:"sessionId"`
	ChannelID     string          `json:"channelId"`
	RequestID     string          `json:"requestId"`
	ToolName      string          `json:"toolName"`
	ToolInput     json.RawMessage `json:"toolInput"`
}

PermissionRequest is Claude asking for tool approval.

type PermissionResponse 

type PermissionResponse struct {
	Type      string `json:"type"`
	ChannelID string `json:"channelId"`
	SessionID string `json:"sessionId"`
	RequestID string `json:"requestId"`
	Approved  bool   `json:"approved"`
}

PermissionResponse is the browser's answer to a permission request.

type PreviewClose added in v0.17.0 

type PreviewClose struct {
	Type      string `json:"type"`
	PreviewID string `json:"previewId"`
	Reason    string `json:"reason"`
}

type PreviewHTTPRequest added in v0.17.0 

type PreviewHTTPRequest struct {
	Type      string              `json:"type"`
	RequestID string              `json:"requestId"`
	StreamID  string              `json:"streamId"`
	PreviewID string              `json:"previewId"`
	Method    string              `json:"method"`
	Path      string              `json:"path"`
	Headers   map[string][]string `json:"headers,omitempty"`
}

type PreviewHTTPResponseHead added in v0.17.0 

type PreviewHTTPResponseHead struct {
	Type       string              `json:"type"`
	RequestID  string              `json:"requestId"`
	StreamID   string              `json:"streamId"`
	PreviewID  string              `json:"previewId"`
	StatusCode int                 `json:"statusCode"`
	Headers    map[string][]string `json:"headers,omitempty"`
}

type PreviewOpen added in v0.17.0 

type PreviewOpen struct {
	Type       string `json:"type"`
	RequestID  string `json:"requestId"`
	PreviewID  string `json:"previewId"`
	SessionID  string `json:"sessionId"`
	ChannelID  string `json:"channelId"`
	MachineID  string `json:"machineId"`
	TargetHost string `json:"targetHost"`
	TargetPort int    `json:"targetPort"`
	ExpiresAt  string `json:"expiresAt"`
}

type PreviewOpenResult added in v0.17.0 

type PreviewOpenResult struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	PreviewID string `json:"previewId"`
	OK        bool   `json:"ok"`
	ErrorCode string `json:"errorCode,omitempty"`
	Message   string `json:"message,omitempty"`
}

type PreviewStreamCancel added in v0.17.0 

type PreviewStreamCancel struct {
	Type     string `json:"type"`
	StreamID string `json:"streamId"`
	Reason   string `json:"reason"`
}

type PreviewStreamChunk added in v0.17.0 

type PreviewStreamChunk struct {
	Type       string `json:"type"`
	StreamID   string `json:"streamId"`
	Sequence   int64  `json:"sequence"`
	BodyBase64 string `json:"bodyBase64"`
	Final      bool   `json:"final"`
}

type PreviewWebSocketClose added in v0.17.0 

type PreviewWebSocketClose struct {
	Type     string `json:"type"`
	StreamID string `json:"streamId"`
	Code     int    `json:"code,omitempty"`
	Reason   string `json:"reason,omitempty"`
}

type PreviewWebSocketData added in v0.17.0 

type PreviewWebSocketData struct {
	Type       string `json:"type"`
	StreamID   string `json:"streamId"`
	Sequence   int64  `json:"sequence"`
	IsBinary   bool   `json:"isBinary"`
	BodyBase64 string `json:"bodyBase64"`
}

type PreviewWebSocketOpen added in v0.17.0 

type PreviewWebSocketOpen struct {
	Type      string              `json:"type"`
	StreamID  string              `json:"streamId"`
	PreviewID string              `json:"previewId"`
	Path      string              `json:"path"`
	Headers   map[string][]string `json:"headers,omitempty"`
	Protocols []string            `json:"protocols,omitempty"`
}

type PreviewWebSocketOpenResult added in v0.17.0 

type PreviewWebSocketOpenResult struct {
	Type      string `json:"type"`
	StreamID  string `json:"streamId"`
	PreviewID string `json:"previewId"`
	OK        bool   `json:"ok"`
	Protocol  string `json:"protocol,omitempty"`
	ErrorCode string `json:"errorCode,omitempty"`
	Message   string `json:"message,omitempty"`
}

type Question 

type Question struct {
	Type          string           `json:"type"`
	TaskID        string           `json:"taskId,omitempty"`
	AttemptID     string           `json:"attemptId,omitempty"`
	AttemptNumber int              `json:"attemptNumber,omitempty"`
	SessionID     string           `json:"sessionId"`
	ChannelID     string           `json:"channelId"`
	RequestID     string           `json:"requestId"`
	Question      string           `json:"question"`
	Header        string           `json:"header,omitempty"`
	MultiSelect   bool             `json:"multiSelect,omitempty"`
	Options       []QuestionOption `json:"options,omitempty"`
}

Question is Claude asking the user for input.

type QuestionOption added in v0.4.1 

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
	Preview     string `json:"preview,omitempty"`
}

QuestionOption is a structured answer choice for AskUserQuestion.

type QuestionResponse 

type QuestionResponse struct {
	Type      string `json:"type"`
	ChannelID string `json:"channelId"`
	SessionID string `json:"sessionId"`
	RequestID string `json:"requestId"`
	Answer    string `json:"answer"`
}

QuestionResponse is the browser's answer to a question.

type ReadFile 

type ReadFile struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	ChannelID string `json:"channelId"`
	MachineID string `json:"machineId"`
	Path      string `json:"path"`
	MaxBytes  int    `json:"maxBytes,omitempty"`
}

ReadFile reads a file from the daemon's filesystem.

type ReadFileResult 

type ReadFileResult struct {
	Type      string `json:"type"`
	RequestID string `json:"requestId"`
	ChannelID string `json:"channelId"`
	OK        bool   `json:"ok"`
	Content   string `json:"content,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
	Error     string `json:"error,omitempty"`
}

ReadFileResult is the daemon's response to a ReadFile request.

type Skill added in v0.22.0 

type Skill struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Path        string `json:"path"`
	Scope       string `json:"scope"`
}

Skill is a locally installed agent skill discovered on the daemon machine.

type Stop 

type Stop struct {
	Type      string `json:"type"`
	ChannelID string `json:"channelId"`
	SessionID string `json:"sessionId"`
}

Stop asks the daemon to interrupt the current Claude process for a session.

type Stream 

type Stream struct {
	Type           string          `json:"type"`
	TaskID         string          `json:"taskId,omitempty"`
	AttemptID      string          `json:"attemptId,omitempty"`
	AttemptNumber  int             `json:"attemptNumber,omitempty"`
	SessionID      string          `json:"sessionId"`
	ChannelID      string          `json:"channelId"`
	SequenceNumber int64           `json:"sequenceNumber"`
	Event          json.RawMessage `json:"event"`
	RequestID      string          `json:"requestId,omitempty"`
	Traceparent    string          `json:"traceparent,omitempty"` // W3C trace context
}

Stream carries a single Claude event plus a sequence number.

type Task 

type Task struct {
	Type               string        `json:"type"`
	TaskID             string        `json:"taskId"`
	SessionID          string        `json:"sessionId"`
	ChannelID          string        `json:"channelId"`
	AttemptID          string        `json:"attemptId,omitempty"`
	AttemptNumber      int           `json:"attemptNumber,omitempty"`
	LeaseExpiresAt     string        `json:"leaseExpiresAt,omitempty"`
	DeadlineProfile    TaskDeadlines `json:"deadlineProfile,omitempty"`
	TurnKind           TurnKind      `json:"turnKind,omitempty"`
	Prompt             string        `json:"prompt"`
	Engine             string        `json:"engine,omitempty"`   // "pi"; empty defaults to pi
	Provider           string        `json:"provider,omitempty"` // Pi provider; empty defaults to claude-cli
	Model              string        `json:"model"`
	Effort             string        `json:"effort"`
	PermissionMode     string        `json:"permissionMode"`
	CWD                string        `json:"cwd"`
	ClaudeSessionID    string        `json:"claudeSessionId,omitempty"` // passed to --resume
	RequestID          string        `json:"requestId,omitempty"`
	Traceparent        string        `json:"traceparent,omitempty"` // W3C trace context
	ImageURLs          []string      `json:"imageUrls,omitempty"`   // user-attached image URLs
	ContextRefs        []ContextRef  `json:"contextRefs,omitempty"`
	CustomInstructions string        `json:"customInstructions,omitempty"`
	DisableSkills      bool          `json:"disableSkills,omitempty"`
}

Task is sent from the browser to the daemon to dispatch a user message.

type TaskAttemptStatus added in v0.32.0 

type TaskAttemptStatus string
const (
	TaskAttemptStatusCreated               TaskAttemptStatus = "created"
	TaskAttemptStatusQueued                TaskAttemptStatus = "queued"
	TaskAttemptStatusStarted               TaskAttemptStatus = "started"
	TaskAttemptStatusPiStarted             TaskAttemptStatus = "pi_started"
	TaskAttemptStatusPromptWritten         TaskAttemptStatus = "prompt_written"
	TaskAttemptStatusFirstEventSeen        TaskAttemptStatus = "first_event_seen"
	TaskAttemptStatusFirstVisibleEventSeen TaskAttemptStatus = "first_visible_event_seen"
	TaskAttemptStatusStreaming             TaskAttemptStatus = "streaming"
	TaskAttemptStatusWaitingInput          TaskAttemptStatus = "waiting_input"
	TaskAttemptStatusToolRunning           TaskAttemptStatus = "tool_running"
	TaskAttemptStatusCleanupStarted        TaskAttemptStatus = "cleanup_started"
	TaskAttemptStatusCleanupFinished       TaskAttemptStatus = "cleanup_finished"
	TaskAttemptStatusCompleted             TaskAttemptStatus = "completed"
	TaskAttemptStatusFailed                TaskAttemptStatus = "failed"
	TaskAttemptStatusCanceled              TaskAttemptStatus = "canceled"
	TaskAttemptStatusTimedOut              TaskAttemptStatus = "timed_out"
	TaskAttemptStatusLost                  TaskAttemptStatus = "lost"
)

type TaskCancelled added in v0.4.0 

type TaskCancelled struct {
	Type          string `json:"type"`
	TaskID        string `json:"taskId"`
	AttemptID     string `json:"attemptId,omitempty"`
	AttemptNumber int    `json:"attemptNumber,omitempty"`
	SessionID     string `json:"sessionId"`
	ChannelID     string `json:"channelId"`
	FailureCode   string `json:"failureCode,omitempty"`
	Retryable     bool   `json:"retryable,omitempty"`
	UserMessage   string `json:"userMessage,omitempty"`
	RequestID     string `json:"requestId,omitempty"`
	Traceparent   string `json:"traceparent,omitempty"` // W3C trace context
}

TaskCancelled tells the relay/browser that a task was interrupted by the user.

type TaskComplete 

type TaskComplete struct {
	Type            string `json:"type"`
	TaskID          string `json:"taskId"`
	AttemptID       string `json:"attemptId,omitempty"`
	AttemptNumber   int    `json:"attemptNumber,omitempty"`
	SessionID       string `json:"sessionId"`
	ChannelID       string `json:"channelId"`
	ClaudeSessionID string `json:"claudeSessionId"`
	InputTokens     int64  `json:"inputTokens"`
	OutputTokens    int64  `json:"outputTokens"`
	CostUSD         string `json:"costUsd"`
	DurationMs      int    `json:"durationMs"`
	RequestID       string `json:"requestId,omitempty"`
	Traceparent     string `json:"traceparent,omitempty"` // W3C trace context
}

TaskComplete reports final result metadata.

type TaskDeadlines added in v0.32.0 

type TaskDeadlines struct {
	ProcessStartMs      int `json:"processStartMs,omitempty"`
	PromptWriteMs       int `json:"promptWriteMs,omitempty"`
	FirstEventMs        int `json:"firstEventMs,omitempty"`
	FirstVisibleEventMs int `json:"firstVisibleEventMs,omitempty"`
	StreamIdleMs        int `json:"streamIdleMs,omitempty"`
	ToolIdleMs          int `json:"toolIdleMs,omitempty"`
	UserInputMs         int `json:"userInputMs,omitempty"`
	CleanupTermMs       int `json:"cleanupTermMs,omitempty"`
}

type TaskError 

type TaskError struct {
	Type          string `json:"type"`
	TaskID        string `json:"taskId"`
	AttemptID     string `json:"attemptId,omitempty"`
	AttemptNumber int    `json:"attemptNumber,omitempty"`
	SessionID     string `json:"sessionId"`
	ChannelID     string `json:"channelId"`
	Error         string `json:"error"`
	FailureCode   string `json:"failureCode,omitempty"`
	Retryable     bool   `json:"retryable,omitempty"`
	UserMessage   string `json:"userMessage,omitempty"`
	RequestID     string `json:"requestId,omitempty"`
	Traceparent   string `json:"traceparent,omitempty"` // W3C trace context
}

TaskError reports a failure.

type TaskLifecycle added in v0.32.0 

type TaskLifecycle struct {
	Type          MessageType        `json:"type"`
	TaskID        string             `json:"taskId"`
	AttemptID     string             `json:"attemptId"`
	AttemptNumber int                `json:"attemptNumber"`
	SessionID     string             `json:"sessionId"`
	ChannelID     string             `json:"channelId"`
	Phase         TaskLifecyclePhase `json:"phase"`
	Status        TaskAttemptStatus  `json:"status"`
	Retryable     bool               `json:"retryable,omitempty"`
	FailureCode   string             `json:"failureCode,omitempty"`
	Message       string             `json:"message,omitempty"`
	UserMessage   string             `json:"userMessage,omitempty"`
	ObservedAt    time.Time          `json:"observedAt"`
	DeadlineAt    *time.Time         `json:"deadlineAt,omitempty"`
	PID           int                `json:"pid,omitempty"`
	Provider      string             `json:"provider,omitempty"`
	Model         string             `json:"model,omitempty"`
	RequestID     string             `json:"requestId,omitempty"`
	Traceparent   string             `json:"traceparent,omitempty"`
}

type TaskLifecyclePhase added in v0.32.0 

type TaskLifecyclePhase string
const (
	TaskLifecyclePhaseAccepted              TaskLifecyclePhase = "accepted"
	TaskLifecyclePhaseQueued                TaskLifecyclePhase = "queued"
	TaskLifecyclePhaseStarted               TaskLifecyclePhase = "started"
	TaskLifecyclePhasePiStarted             TaskLifecyclePhase = "pi_started"
	TaskLifecyclePhasePromptWritten         TaskLifecyclePhase = "prompt_written"
	TaskLifecyclePhaseFirstEventSeen        TaskLifecyclePhase = "first_event_seen"
	TaskLifecyclePhaseFirstVisibleEventSeen TaskLifecyclePhase = "first_visible_event_seen"
	TaskLifecyclePhaseStreaming             TaskLifecyclePhase = "streaming"
	TaskLifecyclePhaseToolStarted           TaskLifecyclePhase = "tool_started"
	TaskLifecyclePhaseToolFinished          TaskLifecyclePhase = "tool_finished"
	TaskLifecyclePhaseWaitingInput          TaskLifecyclePhase = "waiting_input"
	TaskLifecyclePhaseInputReceived         TaskLifecyclePhase = "input_received"
	TaskLifecyclePhaseCleanupStarted        TaskLifecyclePhase = "cleanup_started"
	TaskLifecyclePhaseCleanupFinished       TaskLifecyclePhase = "cleanup_finished"
	TaskLifecyclePhaseHeartbeat             TaskLifecyclePhase = "heartbeat"
	TaskLifecyclePhaseRetryScheduled        TaskLifecyclePhase = "retry_scheduled"
	TaskLifecyclePhaseCompleted             TaskLifecyclePhase = "completed"
	TaskLifecyclePhaseFailed                TaskLifecyclePhase = "failed"
	TaskLifecyclePhaseCanceled              TaskLifecyclePhase = "canceled"
	TaskLifecyclePhaseTimedOut              TaskLifecyclePhase = "timed_out"
	TaskLifecyclePhaseLost                  TaskLifecyclePhase = "lost"
)

type TaskStarted 

type TaskStarted struct {
	Type          string `json:"type"`
	TaskID        string `json:"taskId"`
	AttemptID     string `json:"attemptId,omitempty"`
	AttemptNumber int    `json:"attemptNumber,omitempty"`
	SessionID     string `json:"sessionId"`
	ChannelID     string `json:"channelId"`
	StartedAt     string `json:"startedAt"`
	RequestID     string `json:"requestId,omitempty"`
	Traceparent   string `json:"traceparent,omitempty"` // W3C trace context
}

TaskStarted signals the daemon began processing a task.

type TerminalClose added in v0.18.0 

type TerminalClose struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	ChannelID  string `json:"channelId"`
}

TerminalClose terminates the PTY.

type TerminalError added in v0.18.0 

type TerminalError struct {
	Type       string `json:"type"`
	RequestID  string `json:"requestId,omitempty"`
	TerminalID string `json:"terminalId,omitempty"`
	SessionID  string `json:"sessionId,omitempty"`
	ChannelID  string `json:"channelId"`
	Error      string `json:"error"`
}

TerminalError reports a terminal lifecycle or authorization error.

type TerminalExit added in v0.18.0 

type TerminalExit struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	SessionID  string `json:"sessionId"`
	ChannelID  string `json:"channelId"`
	ExitCode   *int   `json:"exitCode,omitempty"`
	Signal     string `json:"signal,omitempty"`
	Reason     string `json:"reason"`
	EndedAt    string `json:"endedAt"`
}

TerminalExit reports terminal process completion.

type TerminalInput added in v0.18.0 

type TerminalInput struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	ChannelID  string `json:"channelId"`
	DataBase64 string `json:"dataBase64"`
}

TerminalInput carries browser input bytes as base64.

type TerminalOpen added in v0.18.0 

type TerminalOpen struct {
	Type          string `json:"type"`
	RequestID     string `json:"requestId"`
	TerminalID    string `json:"terminalId,omitempty"`
	SessionID     string `json:"sessionId"`
	ChannelID     string `json:"channelId"`
	Token         string `json:"token,omitempty"`
	CWD           string `json:"cwd,omitempty"`
	Cols          int    `json:"cols"`
	Rows          int    `json:"rows"`
	IdleTimeoutMs int    `json:"idleTimeoutMs,omitempty"`
	MaxLifetimeMs int    `json:"maxLifetimeMs,omitempty"`
}

TerminalOpen requests a chat-scoped PTY terminal.

type TerminalOpened added in v0.18.0 

type TerminalOpened struct {
	Type       string `json:"type"`
	RequestID  string `json:"requestId"`
	TerminalID string `json:"terminalId"`
	SessionID  string `json:"sessionId"`
	ChannelID  string `json:"channelId"`
	Shell      string `json:"shell"`
	CWD        string `json:"cwd"`
	StartedAt  string `json:"startedAt"`
}

TerminalOpened confirms a terminal has started.

type TerminalOutput added in v0.18.0 

type TerminalOutput struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	SessionID  string `json:"sessionId"`
	ChannelID  string `json:"channelId"`
	Seq        int64  `json:"seq"`
	DataBase64 string `json:"dataBase64"`
}

TerminalOutput carries terminal output bytes as base64.

type TerminalResize added in v0.18.0 

type TerminalResize struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	ChannelID  string `json:"channelId"`
	Cols       int    `json:"cols"`
	Rows       int    `json:"rows"`
}

TerminalResize resizes the PTY.

type TerminalSnapshot added in v0.18.0 

type TerminalSnapshot struct {
	Type       string `json:"type"`
	TerminalID string `json:"terminalId"`
	SessionID  string `json:"sessionId"`
	ChannelID  string `json:"channelId"`
	Seq        int64  `json:"seq"`
	DataBase64 string `json:"dataBase64"`
}

TerminalSnapshot carries bounded scrollback bytes as base64.

type TurnKind added in v0.32.0 

type TurnKind string
const (
	TurnKindUser         TurnKind = "user"
	TurnKindSessionTitle TurnKind = "session_title"
	TurnKindContextStats TurnKind = "context_stats"
	TurnKindCompact      TurnKind = "compact"
	TurnKindControl      TurnKind = "control"
)

type Welcome 

type Welcome struct {
	Type                string `json:"type"`
	LatestDaemonVersion string `json:"latestDaemonVersion,omitempty"`
}

Welcome is the relay's response to Hello.

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.