protocol

package
v0.604.0 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MethodStateSync requests a full state snapshot from the primary instance.
	MethodStateSync = "state.sync"
	// MethodSessionList requests the full list of sessions.
	MethodSessionList = "session.list"
	// MethodSessionGet requests a single session by ID.
	MethodSessionGet = "session.get"
	// MethodSessionActivate requests changing the active session.
	MethodSessionActivate = "session.activate"
	// MethodMessageSend sends a user message to a session.
	MethodMessageSend = "message.send"
	// MethodSessionInterrupt cancels the running LLM call for a session.
	MethodSessionInterrupt = "session.interrupt"
	// MethodInstancePing checks that the instance is alive.
	MethodInstancePing = "instance.ping"
	// MethodInstanceInfo retrieves detailed instance information.
	MethodInstanceInfo = "instance.info"
	// MethodMessageList requests the message history for a session.
	MethodMessageList = "message.list"
	// MethodDelegationRun runs a delegated prompt in a fresh ephemeral session on
	// the target instance and returns the captured assistant output synchronously
	// (hot-peer delegation, B3). Only handled when the target opted in via
	// AcceptDelegations; otherwise the handler returns a typed refusal.
	MethodDelegationRun = "delegation.run"
	// MethodDelegationCancel best-effort cancels an in-flight delegated session on
	// the target by its session id (the caller uses this on ctx cancellation).
	MethodDelegationCancel = "delegation.cancel"
)

RPC method name constants used for JSON-RPC 2.0 calls over the ROUTER socket.

View Source 
const (
	// TopicSessionList is published when the session list changes; carries a full list.
	TopicSessionList = "session.list"
	// TopicSessionUpdate is published when a single session is created or updated.
	TopicSessionUpdate = "session.update"
	// TopicSessionActivated is published when the active session changes.
	TopicSessionActivated = "session.activated"
	// TopicSessionDeleted is published when a session is deleted.
	TopicSessionDeleted = "session.deleted"
)

Session topics — published on the PUB socket for session lifecycle events.

View Source 
const (
	// TopicLLMToken is published for each streaming LLM token.
	TopicLLMToken = "llm.token"
	// TopicLLMStart is published when an LLM call begins.
	TopicLLMStart = "llm.start"
	// TopicLLMEnd is published when an LLM call completes.
	TopicLLMEnd = "llm.end"
)

LLM topics — published during LLM inference.

View Source 
const (
	// TopicToolStart is published when tool execution begins.
	TopicToolStart = "tool.start"
	// TopicToolEnd is published when tool execution completes.
	TopicToolEnd = "tool.end"
)

Tool topics — published during tool execution.

View Source 
const (
	// TopicInstanceHeartbeat is published every 5 seconds to signal liveness.
	TopicInstanceHeartbeat = "instance.heartbeat"
	// TopicInstanceShutdown is published on graceful shutdown.
	TopicInstanceShutdown = "instance.shutdown"
	// TopicInstancePromoted is published when a secondary instance successfully
	// promotes itself to primary after the previous primary died or shut down.
	// Other secondary instances must reset their heartbeat timer and reconnect
	// to the new primary's PUB/RPC endpoints.
	TopicInstancePromoted = "instance.promoted"
)

Instance topics — published for instance lifecycle management.

View Source 
const DelegationProtocolVersion = 1

DelegationProtocolVersion is the wire version of the delegation.run contract. A caller must observe a peer advertising DelegationProtocol >= this value (via PingResult) before routing a delegation to it; capability negotiation fails closed so a peer that is too old (advertising 0) is simply never used.

View Source 
const (
	// TopicMessageAppend is published when a new message is added to a session.
	TopicMessageAppend = "message.append"
)

Message topics.

Variables

This section is empty.

Functions

This section is empty.

Types

type DelegationCancelParams added in v0.604.0 

type DelegationCancelParams struct {
	CorrelationID string `json:"correlation_id"`
}

DelegationCancelParams is the parameter struct for delegation.cancel. It keys on the caller-owned CorrelationID rather than the target's session id, because the synchronous delegation.run RPC only returns the session id AFTER the turn completes — so a caller cancelling an in-flight delegation has only the correlation id it supplied in DelegationRunParams. The target maps the correlation id to the live ephemeral session while the run is in flight.

type DelegationRunParams added in v0.604.0 

type DelegationRunParams struct {
	Prompt        string `json:"prompt"`
	Cwd           string `json:"cwd,omitempty"`
	Persona       string `json:"persona,omitempty"`
	Model         string `json:"model,omitempty"`
	CorrelationID string `json:"correlation_id,omitempty"`
}

DelegationRunParams is the parameter struct for delegation.run. The software owns all launch metadata; the caller passes only the rendered prompt plus the optional persona/model overrides and the correlation id used for idempotency.

type DelegationRunResult added in v0.604.0 

type DelegationRunResult struct {
	SessionID  string `json:"session_id"`
	Output     string `json:"output"`
	StopReason string `json:"stop_reason,omitempty"`
}

DelegationRunResult is the response for delegation.run. Output is the full assistant message text for the turn (the caller feeds it to conclusion.Enrich to extract the <pando:conclusion> block); SessionID is the ephemeral session created on the target for correlation/recovery.

type HeartbeatPayload 

type HeartbeatPayload struct {
	InstanceID      string    `json:"instance_id"`
	ActiveSessionID string    `json:"active_session_id,omitempty"`
	SessionCount    int       `json:"session_count"`
	Uptime          string    `json:"uptime"` // duration string e.g. "1h30m"
	StartedAt       time.Time `json:"started_at"`
}

HeartbeatPayload is published on instance.heartbeat every 5 seconds.

type LLMEndPayload 

type LLMEndPayload struct {
	SessionID string `json:"session_id"`
	TokensIn  int    `json:"tokens_in"`
	TokensOut int    `json:"tokens_out"`
}

LLMEndPayload is published on llm.end when an LLM call completes.

type LLMStartPayload 

type LLMStartPayload struct {
	SessionID string `json:"session_id"`
}

LLMStartPayload is published on llm.start when an LLM call begins.

type LLMTokenPayload 

type LLMTokenPayload struct {
	SessionID string `json:"session_id"`
	Token     string `json:"token"`
}

LLMTokenPayload is published on llm.token for each streaming token.

type MessageAppendPayload 

type MessageAppendPayload struct {
	SessionID string `json:"session_id"`
	MessageID string `json:"message_id"`
	Role      string `json:"role"`    // "user" or "assistant"
	Content   string `json:"content"` // text content or summary
}

MessageAppendPayload is published on message.append.

type MessageListParams added in v0.302.0 

type MessageListParams struct {
	SessionID string `json:"session_id"`
}

MessageListParams is the parameter struct for message.list.

type MessagePayload added in v0.302.0 

type MessagePayload struct {
	ID        string    `json:"id"`
	Role      string    `json:"role"`    // "user" or "assistant"
	Content   string    `json:"content"` // text representation of the message
	CreatedAt time.Time `json:"created_at"`
}

MessagePayload is a single message returned by message.list.

type MessageSendParams 

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

MessageSendParams is the parameter struct for message.send.

type OKResult 

type OKResult struct {
	OK bool `json:"ok"`
}

OKResult is a generic success response.

type PingResult 

type PingResult struct {
	Status     string `json:"status"`
	InstanceID string `json:"instance_id"`
	Uptime     string `json:"uptime"`
	// AcceptsDelegations is true when this instance opted in (AcceptDelegations)
	// and therefore handles delegation.run.
	AcceptsDelegations bool `json:"accepts_delegations,omitempty"`
	// DelegationProtocol is the wire version of the delegation.run contract this
	// instance speaks; 0/absent means "does not accept delegations".
	DelegationProtocol int `json:"delegation_protocol,omitempty"`
}

PingResult is the response for instance.ping. It doubles as the delegation capability advertisement: AcceptsDelegations + DelegationProtocol let a caller learn, in the same round-trip that confirms liveness, whether this peer will accept a delegation.run and at which wire version. Older peers omit these fields (false/0), so capability negotiation fails closed.

type PromotedPayload added in v0.326.0 

type PromotedPayload struct {
	InstanceID string `json:"instance_id"`
	PubAddr    string `json:"pub_addr"`
	RPCAddr    string `json:"rpc_addr"`
}

PromotedPayload is published on instance.promoted when a secondary takes over as primary. Other secondaries use the PubAddr / RPCAddr fields to reconnect.

type SessionActivateParams 

type SessionActivateParams struct {
	SessionID string `json:"session_id"`
}

SessionActivateParams is the parameter struct for session.activate.

type SessionGetParams 

type SessionGetParams struct {
	SessionID string `json:"session_id"`
}

SessionGetParams is the parameter struct for session.get.

type SessionInterruptParams 

type SessionInterruptParams struct {
	SessionID string `json:"session_id"`
}

SessionInterruptParams is the parameter struct for session.interrupt.

type SessionListPayload 

type SessionListPayload struct {
	Sessions []SessionPayload `json:"sessions"`
}

SessionListPayload is published on session.list and carries the full session list.

type SessionPayload 

type SessionPayload struct {
	ID           string    `json:"id"`
	Title        string    `json:"title"`
	UpdatedAt    time.Time `json:"updated_at"`
	MessageCount int64     `json:"message_count"`
}

SessionPayload is published on session.update, session.activated, and session.deleted.

type ShutdownPayload 

type ShutdownPayload struct {
	InstanceID string `json:"instance_id"`
	Reason     string `json:"reason,omitempty"`
}

ShutdownPayload is published on instance.shutdown during graceful shutdown.

type StateSyncParams 

type StateSyncParams struct {
	ProjectID string `json:"project_id,omitempty"`
}

StateSyncParams is the parameter struct for the state.sync RPC method.

type StateSyncResult 

type StateSyncResult struct {
	Sessions        []SessionPayload `json:"sessions"`
	ActiveSessionID string           `json:"active_session_id,omitempty"`
	InstanceID      string           `json:"instance_id"`
}

StateSyncResult is the response for state.sync.

type ToolEndPayload 

type ToolEndPayload struct {
	SessionID string `json:"session_id"`
	ToolName  string `json:"tool_name"`
	CallID    string `json:"call_id"`
	IsError   bool   `json:"is_error"`
	Result    string `json:"result"` // short summary of result
}

ToolEndPayload is published on tool.end when tool execution completes.

type ToolStartPayload 

type ToolStartPayload struct {
	SessionID string `json:"session_id"`
	ToolName  string `json:"tool_name"`
	CallID    string `json:"call_id"`
	Params    string `json:"params"` // JSON params as string
}

ToolStartPayload is published on tool.start when tool execution begins.

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.