client

package
v0.2.17 Latest Latest
Warning

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

 Go to latest Published: Aug 19, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	FeatureApprovalV1          = protocol.FeatureApprovalV1
	FeatureExecutionProtocolV1 = protocol.FeatureExecutionProtocolV1
	FeatureOperationLedgerV1   = protocol.FeatureOperationLedgerV1
	FeatureTaskBridgeV1        = protocol.FeatureTaskBridgeV1
	ExecutionProtocolVersion   = protocol.ExecutionProtocolVersion
)

Variables

View Source 
var DefaultClient = NewClient()
View Source 
var ErrInvalidOperationID = errors.New("invalid operation id")
View Source 
var ErrProjectNotFound = errors.New("unity project not found")

Functions

func ArgumentsHash added in v0.1.0 

func ArgumentsHash(params any) (string, error)

func ClearInstanceCache 

func ClearInstanceCache()

ClearInstanceCache delegates to DefaultClient.ClearInstanceCache.

func IsPortReachable added in v0.1.0 

func IsPortReachable(ctx context.Context, port int) bool

func IsProcessDead 

func IsProcessDead(pid int) bool

IsProcessDead delegates to DefaultClient.IsProcessDead.

Types

type AmbiguousProjectError added in v0.1.0 

type AmbiguousProjectError struct {
	Query   string
	Matches []string
}

func (*AmbiguousProjectError) Error added in v0.1.0 

func (err *AmbiguousProjectError) Error() string

type ApprovalPreflight added in v0.1.0 

type ApprovalPreflight struct {
	Token       string          `json:"token"`
	OperationID OperationID     `json:"operation_id"`
	ExpiresAtMS int64           `json:"expires_at_ms"`
	Summary     ApprovalSummary `json:"summary"`
}

type ApprovalPreflightRequest added in v0.1.0 

type ApprovalPreflightRequest struct {
	Command     string
	Action      string
	Params      any
	OperationID OperationID
	TimeoutMS   int
}

type ApprovalSummary added in v0.1.0 

type ApprovalSummary struct {
	Tool            string      `json:"tool"`
	Action          string      `json:"action,omitempty"`
	Target          string      `json:"target"`
	SideEffect      string      `json:"side_effect"`
	Reversible      bool        `json:"reversible"`
	MayReloadDomain bool        `json:"may_reload_domain"`
	ExternalImpact  bool        `json:"external_impact"`
	OperationID     OperationID `json:"operation_id"`
}

type BatchCommandItem 

type BatchCommandItem struct {
	Command string `json:"command"`
	Params  any    `json:"params,omitempty"`
}

type BatchCommandRequest 

type BatchCommandRequest struct {
	Commands []BatchCommandItem `json:"commands"`
	Options  BatchOptions       `json:"options"`
}

type BatchCommandResponse 

type BatchCommandResponse struct {
	Success   bool              `json:"success"`
	Message   string            `json:"message"`
	Code      string            `json:"code,omitempty"`
	Data      json.RawMessage   `json:"data,omitempty"`
	Results   []CommandResponse `json:"results"`
	Completed int               `json:"completed"`
	Failed    int               `json:"failed"`
}

func SendBatch 

func SendBatch(ctx context.Context, inst *Instance, req BatchCommandRequest, timeoutMs int) (*BatchCommandResponse, error)

type BatchOptions 

type BatchOptions struct {
	FailFast bool `json:"fail_fast"`
	Atomic   bool `json:"atomic"`
}

type Client added in v0.0.15 

type Client struct {
	Debug bool
	// contains filtered or unexported fields
}

func NewClient added in v0.0.15 

func NewClient() *Client

func (*Client) ClearInstanceCache added in v0.0.15 

func (c *Client) ClearInstanceCache()

ClearInstanceCache discards the cached scan result so the next call to ScanInstances reads from disk again. Useful in tests and after explicit install/uninstall flows where the cache could mask new state.

func (*Client) DiscoverInstance added in v0.0.15 

func (c *Client) DiscoverInstance(project string, port int) (*Instance, error)

DiscoverInstance finds a running Unity instance from ~/.hera-agent-unity/instances/. If port > 0, matches an active instance by port and verifies project when set. If project is set, prefers an exact normalized path and accepts a unique substring match for backward compatibility. Otherwise returns the most recently active instance.

func (*Client) DiscoverInstanceFresh added in v0.0.40 

func (c *Client) DiscoverInstanceFresh(project string, port int) (*Instance, error)

DiscoverInstanceFresh resolves an instance directly from heartbeat files. Normal command setup remains cached; this is for reload retry and polling.

func (*Client) FindActiveByPort added in v0.0.15 

func (c *Client) FindActiveByPort(port int) (*Instance, error)

FindActiveByPort is like FindByPort but skips stopped or incomplete instances. Used by polling paths (waitForAlive, waitForReady) that only care about live instances.

func (*Client) FindActiveByPortFresh added in v0.0.40 

func (c *Client) FindActiveByPortFresh(port int) (*Instance, error)

func (*Client) FindByPort added in v0.0.15 

func (c *Client) FindByPort(port int) (*Instance, error)

FindByPort scans instance files and returns the instance matching the given port. If multiple instances share the same port, the one with the most recent timestamp wins.

func (*Client) FindByPortFresh added in v0.0.40 

func (c *Client) FindByPortFresh(port int) (*Instance, error)

FindByPortFresh finds an instance from the current heartbeat files. It is reserved for state-transition polling where a cached heartbeat may hide a new port or state.

func (*Client) IsProcessDead added in v0.0.15 

func (c *Client) IsProcessDead(pid int) bool

IsProcessDead is the public probe used by polling commands that want to detect a crashed Unity Editor without waiting for the heartbeat to stale. Returns true only when the OS confirms the process is gone.

func (*Client) PreflightApproval added in v0.1.0 

func (c *Client) PreflightApproval(
	ctx context.Context,
	instance *Instance,
	request ApprovalPreflightRequest,
) (*ApprovalPreflight, error)

func (*Client) ScanInstances added in v0.0.15 

func (c *Client) ScanInstances() ([]Instance, error)

ScanInstances reads all instance files from ~/.hera-agent-unity/instances/. Stale files whose PID is no longer running are automatically removed. Results are cached for instanceCacheTTL to keep multi-step workflows (batch, exec → console → exec, etc.) from re-stat'ing the dir on every hop.

func (*Client) ScanInstancesFresh added in v0.0.40 

func (c *Client) ScanInstancesFresh() ([]Instance, error)

ScanInstancesFresh reads instance files directly instead of using the short-lived process cache. Transition polling and reload retry use this path so they can observe a new heartbeat or port binding immediately.

func (*Client) Send added in v0.0.15 

func (c *Client) Send(ctx context.Context, inst *Instance, command string, params any, timeoutMs int) (*CommandResponse, error)

func (*Client) SendBatch added in v0.0.15 

func (c *Client) SendBatch(ctx context.Context, inst *Instance, req BatchCommandRequest, timeoutMs int) (*BatchCommandResponse, error)

func (*Client) SendWithOptions added in v0.1.0 

func (c *Client) SendWithOptions(
	ctx context.Context,
	inst *Instance,
	command string,
	params any,
	timeoutMs int,
	options SendOptions,
) (*CommandResponse, error)

type CommandRequest 

type CommandRequest struct {
	Command string      `json:"command"`
	Params  any         `json:"params"`
	Meta    RequestMeta `json:"meta"`
}

type CommandResponse 

type CommandResponse struct {
	Success     bool             `json:"success"`
	Message     string           `json:"message"`
	Code        string           `json:"code,omitempty"`
	Suggestions []string         `json:"suggestions,omitempty"`
	AgentHint   string           `json:"agent_hint,omitempty"`
	Data        json.RawMessage  `json:"data,omitempty"`
	Timings     map[string]int64 `json:"timings,omitempty"`
}

func Send 

func Send(ctx context.Context, inst *Instance, command string, params any, timeoutMs int) (*CommandResponse, error)

type CompilerInfo added in v0.0.33 

type CompilerInfo struct {
	CscPath     string `json:"cscPath,omitempty"`
	CscKind     string `json:"cscKind,omitempty"`
	CscFound    bool   `json:"cscFound,omitempty"`
	DotnetPath  string `json:"dotnetPath,omitempty"`
	DotnetKind  string `json:"dotnetKind,omitempty"`
	DotnetFound bool   `json:"dotnetFound,omitempty"`
	Error       string `json:"error,omitempty"`
}

type Instance 

type Instance struct {
	State         string        `json:"state"`
	ProjectPath   string        `json:"projectPath"`
	Port          int           `json:"port"`
	PID           int           `json:"pid"`
	UnityVersion  string        `json:"unityVersion,omitempty"`
	DocsVersion   string        `json:"docsVersion,omitempty"`
	Compiler      *CompilerInfo `json:"compiler,omitempty"`
	DomainEpoch   string        `json:"domainEpoch,omitempty"`
	Features      []string      `json:"features,omitempty"`
	Timestamp     int64         `json:"timestamp,omitempty"`
	CompileErrors bool          `json:"compileErrors,omitempty"`
}

func DiscoverInstance 

func DiscoverInstance(project string, port int) (*Instance, error)

DiscoverInstance delegates to DefaultClient.DiscoverInstance.

func DiscoverInstanceFresh added in v0.0.40 

func DiscoverInstanceFresh(project string, port int) (*Instance, error)

DiscoverInstanceFresh delegates to DefaultClient.DiscoverInstanceFresh.

func FindActiveByPort 

func FindActiveByPort(port int) (*Instance, error)

FindActiveByPort delegates to DefaultClient.FindActiveByPort.

func FindActiveByPortFresh added in v0.0.40 

func FindActiveByPortFresh(port int) (*Instance, error)

func FindByPort 

func FindByPort(port int) (*Instance, error)

FindByPort delegates to DefaultClient.FindByPort.

func FindByPortFresh added in v0.0.40 

func FindByPortFresh(port int) (*Instance, error)

FindByPortFresh delegates to DefaultClient.FindByPortFresh.

func ScanInstances 

func ScanInstances() ([]Instance, error)

ScanInstances delegates to DefaultClient.ScanInstances.

func ScanInstancesFresh added in v0.0.40 

func ScanInstancesFresh() ([]Instance, error)

ScanInstancesFresh delegates to DefaultClient.ScanInstancesFresh.

type InstanceCache added in v0.0.15 

type InstanceCache struct {
	// contains filtered or unexported fields
}

InstanceCache stores the last ScanInstances result for process-level reuse. A 5-second TTL is short enough that a stopped editor disappears quickly, but long enough that batch / multi-step workflows don't re-stat the dir on every hop.

func NewInstanceCache added in v0.0.15 

func NewInstanceCache() *InstanceCache

NewInstanceCache creates a cache with the default 5-second TTL.

func (*InstanceCache) Clear added in v0.0.15 

func (c *InstanceCache) Clear()

Clear discards the cached data so the next call reads from disk again.

func (*InstanceCache) Get added in v0.0.15 

func (c *InstanceCache) Get() ([]Instance, bool)

Get returns a shallow copy of the cached instances if they are still valid. The second return value reports whether the cache hit.

func (*InstanceCache) Set added in v0.0.15 

func (c *InstanceCache) Set(instances []Instance)

Set stores a copy of the given instances and refreshes the timestamp.

type OperationID added in v0.1.0 

type OperationID string

func NewOperationID added in v0.1.0 

func NewOperationID() (OperationID, error)

func ParseOperationID added in v0.1.0 

func ParseOperationID(value string) (OperationID, error)

type OperationOutcomeUnknownError added in v0.1.0 

type OperationOutcomeUnknownError struct {
	Code        string
	OperationID OperationID
	Command     string
	Project     string
	Port        int
	Cause       error
}

func (*OperationOutcomeUnknownError) Error added in v0.1.0 

func (err *OperationOutcomeUnknownError) Error() string

func (*OperationOutcomeUnknownError) Unwrap added in v0.1.0 

func (err *OperationOutcomeUnknownError) Unwrap() error

type RequestMeta added in v0.1.0 

type RequestMeta struct {
	ProtocolVersion string      `json:"protocol_version,omitempty"`
	OperationID     OperationID `json:"operation_id"`
	ArgumentsHash   string      `json:"arguments_hash"`
	ApprovalToken   *string     `json:"approval_token"`
	ClientKind      string      `json:"client_kind"`
	CatalogHash     string      `json:"catalog_hash,omitempty"`
}

type SendOptions added in v0.1.0 

type SendOptions struct {
	OperationID   OperationID
	ApprovalToken string
	Idempotent    bool
	ClientKind    string
	CatalogHash   string
}

type TargetLostError added in v0.1.0 

type TargetLostError struct {
	Project      string
	PreviousPort int
	Cause        error
}

func (*TargetLostError) Error added in v0.1.0 

func (err *TargetLostError) Error() string

func (*TargetLostError) Unwrap added in v0.1.0 

func (err *TargetLostError) Unwrap() error

type TargetMismatchError added in v0.1.0 

type TargetMismatchError struct {
	Port            int
	ExpectedProject string
	ActualProject   string
}

func (*TargetMismatchError) Error added in v0.1.0 

func (err *TargetMismatchError) Error() string

type TargetRestartedError added in v0.1.0 

type TargetRestartedError struct {
	Project     string
	PreviousPID int
	CurrentPID  int
	Port        int
	State       string
	Cause       error
}

func (*TargetRestartedError) Error added in v0.1.0 

func (err *TargetRestartedError) Error() string

func (*TargetRestartedError) Unwrap added in v0.1.0 

func (err *TargetRestartedError) Unwrap() error

type TargetUnresponsiveError added in v0.1.0 

type TargetUnresponsiveError struct {
	Project string
	Port    int
	PID     int
	State   string
	Cause   error
}

func (*TargetUnresponsiveError) Error added in v0.1.0 

func (err *TargetUnresponsiveError) Error() string

func (*TargetUnresponsiveError) Unwrap added in v0.1.0 

func (err *TargetUnresponsiveError) Unwrap() error

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.