messages

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: May 22, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package messages defines the typed payload structs for every ARCP wire type. Each file registers its concrete payloads against the root arcp envelope registry in an init() block; importing this package transitively registers every supported type.

The init-time registration is the only sanctioned package-level side effect across the SDK. The wire-type string is owned by the payload struct's ARCPType method, so registration sits next to the struct that owns the key — the same pattern used by image and database/sql for format/driver registration.

Index

Constants

View Source 
const (
	TypeSessionHello    = "session.hello"
	TypeSessionWelcome  = "session.welcome"
	TypeSessionError    = "session.error"
	TypeSessionBye      = "session.bye"
	TypeSessionPing     = "session.ping"
	TypeSessionPong     = "session.pong"
	TypeSessionAck      = "session.ack"
	TypeSessionListJobs = "session.list_jobs"
	TypeSessionJobs     = "session.jobs"

	TypeJobSubmit      = "job.submit"
	TypeJobAccepted    = "job.accepted"
	TypeJobEvent       = "job.event"
	TypeJobResult      = "job.result"
	TypeJobError       = "job.error"
	TypeJobCancel      = "job.cancel"
	TypeJobSubscribe   = "job.subscribe"
	TypeJobSubscribed  = "job.subscribed"
	TypeJobUnsubscribe = "job.unsubscribe"
)

Wire-type tokens. The constants below are the canonical strings used in Envelope.Type. Group, payload struct, and registration table all key off these.

View Source 
const (
	KindLog         = "log"
	KindThought     = "thought"
	KindToolCall    = "tool_call"
	KindToolResult  = "tool_result"
	KindStatus      = "status"
	KindMetric      = "metric"
	KindArtifactRef = "artifact_ref"
	KindDelegate    = "delegate"
	KindProgress    = "progress"
	KindResultChunk = "result_chunk"
)

Event kinds carried inside JobEvent.Kind. The eight reserved kinds (per spec §8.2) plus the v1.1 additions (progress, result_chunk).

View Source 
const (
	StatusPending   = "pending"
	StatusRunning   = "running"
	StatusSuccess   = "success"
	StatusError     = "error"
	StatusCancelled = "cancelled"
	StatusTimedOut  = "timed_out"
)

JobStatus values used in session.jobs and job.subscribed payloads.

View Source 
const (
	PhaseCredentialRotated = "credential_rotated"
)

Reserved status event phases.

Variables

This section is empty.

Functions

func DecodeEventBody 

func DecodeEventBody(e *JobEvent) (any, error)

DecodeEventBody unmarshals e.Body into the kind-specific struct. Unknown kinds return the raw json.RawMessage unchanged.

func NewEventBody 

func NewEventBody(v any) (json.RawMessage, error)

NewEventBody wraps a typed body value into a JobEvent body field.

Types

type AgentEntry 

type AgentEntry struct {
	Name     string   `json:"name"`
	Versions []string `json:"versions,omitempty"`
	Default  string   `json:"default,omitempty"`
}

AgentEntry is one entry in the agent inventory advertised in session.welcome.

type AgentRef 

type AgentRef struct {
	Name    string
	Version string
}

AgentRef is a parsed agent identifier ("name" or "name@version").

func ParseAgentRef 

func ParseAgentRef(s string) (AgentRef, error)

ParseAgentRef parses an agent identifier per the spec grammar: 

agent   ::= name | name "@" version
name    ::= [a-z0-9][a-z0-9._-]*
version ::= [a-zA-Z0-9.+_-]+

func (AgentRef) String 

func (a AgentRef) String() string

String returns the canonical "name@version" or bare "name" form.

type ArtifactRefBody 

type ArtifactRefBody struct {
	URI         string `json:"uri"`
	ContentType string `json:"content_type"`
	ByteSize    uint64 `json:"byte_size,omitempty"`
	SHA256      string `json:"sha256,omitempty"`
}

ArtifactRefBody is the body of an "artifact_ref" event.

type AuthInfo 

type AuthInfo struct {
	Scheme string `json:"scheme"`
	Token  string `json:"token,omitempty"`
}

AuthInfo carries handshake-time authentication. Bearer is the only scheme defined by the protocol; deployment policy may extend it.

type ClientInfo 

type ClientInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

ClientInfo identifies the dialing client.

type Credential 

type Credential struct {
	ID          string                 `json:"id"`
	Scheme      string                 `json:"scheme"`
	Value       string                 `json:"value"`
	Endpoint    string                 `json:"endpoint"`
	Profile     string                 `json:"profile,omitempty"`
	Constraints *CredentialConstraints `json:"constraints,omitempty"`
}

Credential is the vendor-neutral credential shape carried in job.accepted for provisioned_credentials sessions.

type CredentialConstraints 

type CredentialConstraints struct {
	CostBudget []string   `json:"cost.budget,omitempty"`
	ModelUse   []string   `json:"model.use,omitempty"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
}

CredentialConstraints describes the lease-derived limits baked into a provisioned credential.

type DelegateBody 

type DelegateBody struct {
	ChildJobID string     `json:"child_job_id"`
	Agent      string     `json:"agent"`
	Lease      arcp.Lease `json:"lease,omitempty"`
}

DelegateBody is the body of a "delegate" event.

type HelloCapabilities 

type HelloCapabilities struct {
	Encodings []string `json:"encodings,omitempty"`
	Features  []string `json:"features,omitempty"`
}

HelloCapabilities is the capability advertisement sent in session.hello.payload.capabilities.

type JobAccepted 

type JobAccepted struct {
	JobID            string                    `json:"job_id"`
	Lease            arcp.Lease                `json:"lease,omitempty"`
	LeaseConstraints *LeaseConstraints         `json:"lease_constraints,omitempty"`
	Budget           map[arcp.Currency]float64 `json:"budget,omitempty"`
	Credentials      []Credential              `json:"credentials,omitempty"`
	AcceptedAt       time.Time                 `json:"accepted_at"`
	TraceID          string                    `json:"trace_id,omitempty"`
	ParentJobID      string                    `json:"parent_job_id,omitempty"`
	Agent            string                    `json:"agent,omitempty"`
}

JobAccepted echoes the effective lease and constraints back to the submitter.

func (*JobAccepted) ARCPType 

func (*JobAccepted) ARCPType() string

ARCPType returns the wire-type string for JobAccepted.

type JobCancel 

type JobCancel struct {
	Reason string `json:"reason,omitempty"`
}

JobCancel is the cancel request from the submitting session.

func (*JobCancel) ARCPType 

func (*JobCancel) ARCPType() string

ARCPType returns the wire-type string for JobCancel.

type JobError 

type JobError struct {
	FinalStatus string         `json:"final_status"`
	Code        arcp.ErrorCode `json:"code"`
	Message     string         `json:"message,omitempty"`
	Retryable   bool           `json:"retryable"`
	Details     map[string]any `json:"details,omitempty"`
}

JobError is the terminal failure payload.

func (*JobError) ARCPType 

func (*JobError) ARCPType() string

ARCPType returns the wire-type string for JobError.

type JobEvent 

type JobEvent struct {
	Kind string          `json:"kind"`
	TS   time.Time       `json:"ts"`
	Body json.RawMessage `json:"body,omitempty"`
}

JobEvent is one event in the job's event stream. Body is the kind-specific shape; decode it with EventBodyFor(kind).

func (*JobEvent) ARCPType 

func (*JobEvent) ARCPType() string

ARCPType returns the wire-type string for JobEvent.

type JobInfo 

type JobInfo struct {
	JobID        string          `json:"job_id"`
	Agent        string          `json:"agent"`
	Status       string          `json:"status"`
	Lease        arcp.Lease      `json:"lease,omitempty"`
	ParentJobID  string          `json:"parent_job_id,omitempty"`
	CreatedAt    time.Time       `json:"created_at"`
	TraceID      string          `json:"trace_id,omitempty"`
	LastEventSeq uint64          `json:"last_event_seq,omitempty"`
	Extra        json.RawMessage `json:"-"`
}

JobInfo describes one job in session.jobs / job.subscribed.

type JobResult 

type JobResult struct {
	FinalStatus string          `json:"final_status"`
	Output      json.RawMessage `json:"output,omitempty"`
	ResultID    string          `json:"result_id,omitempty"`
	ResultSize  uint64          `json:"result_size,omitempty"`
	Summary     string          `json:"summary,omitempty"`
}

JobResult is the terminal success payload.

func (*JobResult) ARCPType 

func (*JobResult) ARCPType() string

ARCPType returns the wire-type string for JobResult.

type JobSubmit 

type JobSubmit struct {
	Agent            string            `json:"agent"`
	Input            json.RawMessage   `json:"input,omitempty"`
	LeaseRequest     arcp.Lease        `json:"lease_request,omitempty"`
	LeaseConstraints *LeaseConstraints `json:"lease_constraints,omitempty"`
	IdempotencyKey   string            `json:"idempotency_key,omitempty"`
	MaxRuntimeSec    int               `json:"max_runtime_sec,omitempty"`
}

JobSubmit is the client request to create a new job.

func (*JobSubmit) ARCPType 

func (*JobSubmit) ARCPType() string

ARCPType returns the wire-type string for JobSubmit.

type JobSubscribe 

type JobSubscribe struct {
	JobID        string `json:"job_id"`
	FromEventSeq uint64 `json:"from_event_seq,omitempty"`
	History      bool   `json:"history,omitempty"`
}

JobSubscribe attaches the current session to an existing job.

func (*JobSubscribe) ARCPType 

func (*JobSubscribe) ARCPType() string

ARCPType returns the wire-type string for JobSubscribe.

type JobSubscribed 

type JobSubscribed struct {
	JobID          string     `json:"job_id"`
	CurrentStatus  string     `json:"current_status"`
	Agent          string     `json:"agent"`
	Lease          arcp.Lease `json:"lease,omitempty"`
	ParentJobID    string     `json:"parent_job_id,omitempty"`
	TraceID        string     `json:"trace_id,omitempty"`
	SubscribedFrom uint64     `json:"subscribed_from"`
	Replayed       bool       `json:"replayed"`
}

JobSubscribed acknowledges a subscription.

func (*JobSubscribed) ARCPType 

func (*JobSubscribed) ARCPType() string

ARCPType returns the wire-type string for JobSubscribed.

type JobUnsubscribe 

type JobUnsubscribe struct {
	JobID string `json:"job_id"`
}

JobUnsubscribe detaches a previously attached subscription.

func (*JobUnsubscribe) ARCPType 

func (*JobUnsubscribe) ARCPType() string

ARCPType returns the wire-type string for JobUnsubscribe.

type LeaseConstraints 

type LeaseConstraints struct {
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

LeaseConstraints carries optional runtime constraints attached to a lease, currently the expires_at deadline.

type ListJobsFilter 

type ListJobsFilter struct {
	Status        []string   `json:"status,omitempty"`
	Agent         string     `json:"agent,omitempty"`
	CreatedAfter  *time.Time `json:"created_after,omitempty"`
	CreatedBefore *time.Time `json:"created_before,omitempty"`
}

ListJobsFilter narrows the result set of session.list_jobs.

type LogBody 

type LogBody struct {
	Level   string `json:"level"`
	Message string `json:"message"`
}

LogBody is the body of a "log" event.

type MetricBody 

type MetricBody struct {
	Name       string            `json:"name"`
	Value      float64           `json:"value"`
	Unit       string            `json:"unit,omitempty"`
	Dimensions map[string]string `json:"dimensions,omitempty"`
}

MetricBody is the body of a "metric" event.

type ProgressBody 

type ProgressBody struct {
	Current uint64 `json:"current"`
	Total   uint64 `json:"total,omitempty"`
	Units   string `json:"units,omitempty"`
	Message string `json:"message,omitempty"`
}

ProgressBody is the body of a "progress" event.

func (ProgressBody) Validate 

func (b ProgressBody) Validate() error

Validate enforces non-negative current. Because Current is uint64, the only constraint is the optional current <= total when total is present and nonzero.

type ResultChunkBody 

type ResultChunkBody struct {
	ResultID string `json:"result_id"`
	ChunkSeq uint64 `json:"chunk_seq"`
	Data     string `json:"data"`
	Encoding string `json:"encoding"`
	More     bool   `json:"more"`
}

ResultChunkBody is the body of a "result_chunk" event.

func (ResultChunkBody) Validate 

func (b ResultChunkBody) Validate() error

Validate enforces the encoding values defined by the spec.

type ResumeRequest 

type ResumeRequest struct {
	SessionID    string `json:"session_id"`
	ResumeToken  string `json:"resume_token"`
	LastEventSeq uint64 `json:"last_event_seq"`
}

ResumeRequest is the optional resume block inside SessionHello.

type RuntimeInfo 

type RuntimeInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

RuntimeInfo identifies the responding runtime.

type SessionAck 

type SessionAck struct {
	LastProcessedSeq uint64 `json:"last_processed_seq"`
}

SessionAck declares the client's highest processed event_seq.

func (*SessionAck) ARCPType 

func (*SessionAck) ARCPType() string

ARCPType returns the wire-type string for SessionAck.

type SessionBye 

type SessionBye struct {
	Reason string `json:"reason,omitempty"`
}

SessionBye signals a polite session close.

func (*SessionBye) ARCPType 

func (*SessionBye) ARCPType() string

ARCPType returns the wire-type string for SessionBye.

type SessionError 

type SessionError struct {
	Code      arcp.ErrorCode `json:"code"`
	Message   string         `json:"message,omitempty"`
	Retryable bool           `json:"retryable"`
	Details   map[string]any `json:"details,omitempty"`
}

SessionError is a top-level session-scoped failure.

func (*SessionError) ARCPType 

func (*SessionError) ARCPType() string

ARCPType returns the wire-type string for SessionError.

type SessionHello 

type SessionHello struct {
	Client       ClientInfo        `json:"client"`
	Auth         AuthInfo          `json:"auth"`
	Capabilities HelloCapabilities `json:"capabilities"`
	Resume       *ResumeRequest    `json:"resume,omitempty"`
}

SessionHello is the first envelope a client sends after dialing.

func (*SessionHello) ARCPType 

func (*SessionHello) ARCPType() string

ARCPType returns the wire-type string for SessionHello.

type SessionJobs 

type SessionJobs struct {
	RequestID  string    `json:"request_id,omitempty"`
	Jobs       []JobInfo `json:"jobs"`
	NextCursor string    `json:"next_cursor,omitempty"`
}

SessionJobs is the response to session.list_jobs.

func (*SessionJobs) ARCPType 

func (*SessionJobs) ARCPType() string

ARCPType returns the wire-type string for SessionJobs.

type SessionListJobs 

type SessionListJobs struct {
	Filter ListJobsFilter `json:"filter,omitempty"`
	Limit  int            `json:"limit,omitempty"`
	Cursor string         `json:"cursor,omitempty"`
}

SessionListJobs is the read-only inventory request.

func (*SessionListJobs) ARCPType 

func (*SessionListJobs) ARCPType() string

ARCPType returns the wire-type string for SessionListJobs.

type SessionPing 

type SessionPing struct {
	Nonce  string    `json:"nonce"`
	SentAt time.Time `json:"sent_at"`
}

SessionPing is the heartbeat probe; the receiver must respond with SessionPong carrying PingNonce equal to Nonce.

func (*SessionPing) ARCPType 

func (*SessionPing) ARCPType() string

ARCPType returns the wire-type string for SessionPing.

type SessionPong 

type SessionPong struct {
	PingNonce  string    `json:"ping_nonce"`
	ReceivedAt time.Time `json:"received_at"`
}

SessionPong responds to a SessionPing.

func (*SessionPong) ARCPType 

func (*SessionPong) ARCPType() string

ARCPType returns the wire-type string for SessionPong.

type SessionWelcome 

type SessionWelcome struct {
	Runtime              RuntimeInfo         `json:"runtime"`
	ResumeToken          string              `json:"resume_token,omitempty"`
	ResumeWindowSec      int                 `json:"resume_window_sec,omitempty"`
	HeartbeatIntervalSec int                 `json:"heartbeat_interval_sec,omitempty"`
	Capabilities         WelcomeCapabilities `json:"capabilities"`
}

SessionWelcome is the runtime's response to session.hello.

func (*SessionWelcome) ARCPType 

func (*SessionWelcome) ARCPType() string

ARCPType returns the wire-type string for SessionWelcome.

type StatusBody 

type StatusBody struct {
	Phase   string         `json:"phase"`
	Message string         `json:"message,omitempty"`
	Details map[string]any `json:"details,omitempty"`
}

StatusBody is the body of a "status" event.

type ThoughtBody 

type ThoughtBody struct {
	Text string `json:"text"`
}

ThoughtBody is the body of a "thought" event.

type ToolCallBody 

type ToolCallBody struct {
	Tool   string          `json:"tool"`
	Args   json.RawMessage `json:"args,omitempty"`
	CallID string          `json:"call_id"`
}

ToolCallBody is the body of a "tool_call" event.

type ToolError 

type ToolError struct {
	Code      arcp.ErrorCode `json:"code"`
	Message   string         `json:"message,omitempty"`
	Retryable bool           `json:"retryable"`
	Details   map[string]any `json:"details,omitempty"`
}

ToolError describes a structured tool_result error body.

type ToolResultBody 

type ToolResultBody struct {
	CallID string          `json:"call_id"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  *ToolError      `json:"error,omitempty"`
}

ToolResultBody is the body of a "tool_result" event. Exactly one of Result and Error must be set.

func (ToolResultBody) Validate 

func (b ToolResultBody) Validate() error

Validate enforces the spec rule that result and error are mutually exclusive.

type WelcomeCapabilities 

type WelcomeCapabilities struct {
	Encodings []string     `json:"encodings,omitempty"`
	Features  []string     `json:"features,omitempty"`
	Agents    []AgentEntry `json:"agents,omitempty"`
}

WelcomeCapabilities is the response capability set returned in session.welcome.payload.capabilities.

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.