nodes

package
v0.1.0-p8a.2 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultChallengeTTL       = 30 * time.Second
	DefaultMaxChallenges      = 1024
	DefaultMaxPendingPairings = 128
)
View Source 
const (
	BrowserDriverPlaywrightMCP = "playwright_mcp"
	BrowserProfileManaged      = "managed"
	BrowserNetworkExactOrigins = "exact_origins"
	BrowserNetworkPublicWeb    = "public_web"
	BrowserNetworkAnyHTTP      = "any_http"

	MaxBrowserProfiles        = 8
	MaxBrowserActions         = 6
	MaxBrowserScrollAmount    = 5
	MaxBrowserSessions        = 1
	MaxBrowserTabs            = 4
	MaxBrowserSessionSeconds  = 60 * 60
	MaxBrowserIdleSeconds     = 10 * 60
	MaxBrowserPreparedSeconds = 5 * 60
	MaxBrowserActionSeconds   = 60
	MaxBrowserURLBytes        = 16 * 1024
	MaxBrowserTitleBytes      = 4 * 1024
	MaxBrowserSnapshotBytes   = 256 * 1024
	MaxBrowserScreenshotBytes = 8 * 1024 * 1024
	MaxBrowserUploadBytes     = 32 * 1024 * 1024
	MaxBrowserDownloadBytes   = 32 * 1024 * 1024
	MaxBrowserSnapshotRefs    = 500
	MaxBrowserTextInputBytes  = 16 * 1024
	// JSON can encode one accepted input byte as a six-byte Unicode escape.
	// The fixed allowance covers the transport-only {"value": ...} wrapper.
	MaxBrowserEphemeralInputBytes = MaxBrowserTextInputBytes*6 + 128
	MaxBrowserToolResultBytes     = 320 * 1024
	MaxBrowserRetentionSeconds    = 7 * 24 * 60 * 60
	MinBrowserToolResultBytes     = 64 * 1024
)
View Source 
const (
	BrowserCommandSessionOpen   = "browser.session.open.v1"
	BrowserCommandSessionStatus = "browser.session.status.v1"
	BrowserCommandObserve       = "browser.observe.v1"
	BrowserCommandAct           = "browser.act.v1"
	BrowserCommandSessionClose  = "browser.session.close.v1"
)
View Source 
const (
	ProtocolV1            = 1
	MaxIDLength           = 128
	MaxAliasLength        = 64
	MaxCommandNameLen     = 128
	MaxSchemaBytes        = 64 * 1024
	MaxCatalogCommands    = 128
	MaxCatalogBytes       = 512 * 1024
	MaxModelContractBytes = 32 * 1024
	MaxModelGuidanceBytes = 2 * 1024
	MaxModelExamples      = 4
	MaxModelExampleBytes  = 8 * 1024
)
View Source 
const (
	DefaultGatewayInvocationLimit      = 256
	DefaultGatewayInvocationStoreBytes = 32 * 1024 * 1024
	DefaultGatewayInvocationRetention  = 7 * 24 * time.Hour
)
View Source 
const (
	DefaultGatewayTerminalLimit      = 256
	DefaultGatewayTerminalStoreBytes = 4 * 1024 * 1024
	DefaultGatewayTerminalRetention  = 30 * 24 * time.Hour
)
View Source 
const (
	MaxClientVersionLength = 128
	MaxPlatformLength      = 64
	MaxArchitectureLength  = 64
	MaxRoleLength          = 32
)
View Source 
const (
	MaxInvocationInputBytes = 512 * 1024
	MaxInvocationTimeout    = 60 * 60
	// MaxInvocationOutput leaves room for protocol envelope and recovery-record
	// metadata inside the 1 MiB WebSocket frame. Larger data uses artifacts.
	MaxInvocationOutput     = 512 * 1024
	MaxPolicyRevisionLength = 128
	MaxExecutionPlanTTL     = 5 * time.Minute
	MaxExecutionPlanSkew    = 30 * time.Second
)
View Source 
const (
	InvocationDispatchCommandDenied       = "COMMAND_DENIED"
	InvocationDispatchCommandUnavailable  = "COMMAND_UNAVAILABLE"
	InvocationDispatchExecutionFailed     = "EXECUTION_FAILED"
	InvocationDispatchIdempotencyConflict = "IDEMPOTENCY_CONFLICT"
	InvocationDispatchInvalidPlan         = "INVALID_PLAN"
	InvocationDispatchNodeBusy            = "NODE_BUSY"
	InvocationDispatchCanceled            = "INVOCATION_CANCELED"
	InvocationDispatchUnknown             = "INVOCATION_UNKNOWN"
	InvocationDispatchRejected            = "DISPATCH_REJECTED"
)
View Source 
const (
	InvocationQueryNotFound             = "INVOCATION_NOT_FOUND"
	InvocationQueryLedgerUnavailable    = "LEDGER_UNAVAILABLE"
	InvocationQueryNodeUnavailable      = "NODE_UNAVAILABLE"
	InvocationQueryTimeout              = "STATUS_TIMEOUT"
	InvocationQueryCanceled             = "STATUS_CANCELED"
	InvocationQueryTransportUnavailable = "STATUS_TRANSPORT_UNAVAILABLE"
	InvocationQueryRejected             = "STATUS_REJECTED"
)
View Source 
const (
	JobCommandStart     = "job.start.v1"
	JobCommandStatus    = "job.status.v1"
	JobCommandLogs      = "job.logs.v1"
	JobCommandArtifacts = "job.artifacts.v1"
	JobCommandCancel    = "job.cancel.v1"

	MaxJobProfiles         = 8
	MaxJobConcurrency      = 32
	MaxJobLogBytes         = 64 * 1024 * 1024
	MaxJobLogChunkBytes    = 64 * 1024
	MaxJobArtifactCount    = 16
	MaxJobArtifactBytes    = 512 * 1024 * 1024
	MaxJobArtifactsTotal   = 1024 * 1024 * 1024
	MaxJobRetentionSeconds = 30 * 24 * 60 * 60
	MaxJobTimeoutSeconds   = 24 * 60 * 60

	// InternalJobArtifactDownloadCommand identifies the gateway-retained plan
	// behind nodes_download for an immutable job artifact. It is never
	// advertised as a companion invocation command or exposed as a model tool.
	InternalJobArtifactDownloadCommand = "job.artifact.download.v1"
	JobArtifactTransferSourceKind      = "node_job_artifact"
)
View Source 
const (
	MaxServiceProfiles    = 32
	MaxServicesPerProfile = 64
	MaxServiceDescription = 256
	// MaxServiceDescriptionProjectionBytes bounds the aggregate JSON-encoded
	// description values in one target profile so its complete model contract
	// remains within MaxModelContractBytes at maximum service authority.
	MaxServiceDescriptionProjectionBytes = 4 * 1024
	MaxServiceLogEntries                 = 500
	MaxServiceLogRecordBytes             = 16 * 1024
	MaxServiceLogBytes                   = 256 * 1024
	MaxServiceLogAge                     = 7 * 24 * 60 * 60
)
View Source 
const (
	MaxShellExecScriptBytes      = 64 * 1024
	MaxShellExecEnvironmentBytes = 8 * 1024
)
View Source 
const (
	MaxTerminalOpenPlanTTL          = 5 * time.Minute
	MaxTerminalTransportFrameBytes  = 32 * 1024
	MaxTerminalTransportBuffer      = 1024 * 1024
	MinTerminalTransportEventCharge = 256
	TerminalProtocolVersion         = 1
)
View Source 
const (
	TransferArtifactRefPrefix       = "transfer-artifact://"
	DefaultGatewayTransferLimit     = 256
	DefaultGatewayTransferSpoolSize = int64(4 * 1024 * 1024 * 1024)
	DefaultGatewayTransferRetention = 24 * time.Hour
	MaxGatewayActiveTransfers       = 8
	MaxTargetProfileActiveTransfers = 2
	MaxGatewayTransferRetention     = 7 * 24 * time.Hour
	MaxGatewayTransferLifetime      = time.Hour
	MaxTransferArtifactBytes        = int64(1024 * 1024 * 1024)
	MaxTransferArtifactChunkBytes   = 256 * 1024
)
View Source 
const (
	MaxUpdateProfiles        = 16
	MaxUpdateReleases        = 16
	MaxUpdateVersionBytes    = 64
	MaxUpdateDescriptionSize = 256
)
View Source 
const (
	WorkspaceCommandRead   = "workspace.read.v1"
	WorkspaceCommandSearch = "workspace.search.v1"
	WorkspaceCommandWrite  = "workspace.write.v1"
	WorkspaceCommandPatch  = "workspace.patch.v1"

	MaxWorkspaceReadBytes    = 512 * 1024
	MaxWorkspaceWriteBytes   = 256 * 1024
	MaxWorkspacePatchBytes   = 256 * 1024
	MaxWorkspacePatchFiles   = 32
	MaxWorkspacePatchTotal   = 1024 * 1024
	MaxWorkspaceSearchResult = 64 * 1024
	MaxWorkspaceSearchFiles  = 10000
	MaxWorkspaceSearchLimit  = 500
)
View Source 
const MaxInvocationFailureMessage = 512

Variables

View Source 
var (
	ErrChallengeExpired = errors.New("node admission challenge expired")
	ErrChallengeUnknown = errors.New("node admission challenge is unknown or already used")
	ErrAdmissionBusy    = errors.New("node admission capacity reached")
	ErrAdmissionRevoked = errors.New("node identity is revoked")
)
View Source 
var (
	ErrBrowserHostDenied   = errors.New("companion browser authority denied")
	ErrBrowserHostBusy     = errors.New("companion browser profile is busy")
	ErrBrowserHostNotFound = errors.New("companion browser session not found")
	ErrBrowserHostStale    = errors.New("companion browser state is stale")
	ErrBrowserHostLost     = errors.New("companion browser session is lost")
)
View Source 
var (
	ErrInvalidNode       = errors.New("invalid node")
	ErrInvalidCapability = errors.New("invalid node capability")
)
View Source 
var (
	ErrGatewayInvocationConflict      = errors.New("gateway node invocation conflicts with durable state")
	ErrGatewayInvocationDispatched    = errors.New("gateway node invocation was already dispatched")
	ErrGatewayInvocationNotDispatched = errors.New("gateway node invocation was not dispatched")
	ErrGatewayInvocationNotFound      = errors.New("gateway node invocation not found")
	ErrGatewayInvocationStoreFull     = errors.New("gateway node invocation store is full")
)
View Source 
var (
	ErrGatewayTerminalConflict  = errors.New("gateway terminal conflicts with durable state")
	ErrGatewayTerminalNotFound  = errors.New("gateway terminal not found")
	ErrGatewayTerminalStoreFull = errors.New("gateway terminal store is full")
)
View Source 
var (
	ErrInvalidInvocation = errors.New("invalid node invocation")
	ErrCommandDenied     = errors.New("node command denied")
)
View Source 
var (
	ErrTransferArtifactConflict = errors.New("transfer artifact conflicts with durable state")
	ErrTransferArtifactNotFound = errors.New("transfer artifact not found")
	ErrTransferSpoolFull        = errors.New("transfer spool is full")
	ErrTransferSpoolInUse       = errors.New("transfer spool is already in use")
	ErrTransferSpoolClosed      = errors.New("transfer spool is closed")
	ErrTransferChunkSequence    = errors.New("transfer chunk sequence is invalid")
	ErrTransferSizeExceeded     = errors.New("transfer artifact exceeds declared size")
	ErrTransferDigestMismatch   = errors.New("transfer artifact digest mismatch")
)
View Source 
var ErrInvalidIdentityProof = errors.New("invalid node identity proof")
View Source 
var (
	ErrInvalidInvocationRecord = errors.New("invalid node invocation record")
)
View Source 
var ErrInvalidTerminal = errors.New("invalid node terminal request")

Functions

func BrowserApprovalDigest 

func BrowserApprovalDigest(input BrowserActInput) (string, error)

BrowserApprovalDigest binds one approval-gated companion action to its complete typed input without forwarding human approval authority.

func BrowserApprovalDigestMatches 

func BrowserApprovalDigestMatches(input BrowserActInput) bool

BrowserApprovalDigestMatches verifies the action's supplied digest without exposing or reconstructing human approval credentials.

func BrowserClickEffect 

func BrowserClickEffect(role string) string

BrowserClickEffect returns the conservative trusted effect for semantic click revalidation on both sides of the companion boundary.

func BrowserCommandInputSchema 

func BrowserCommandInputSchema(command string, profiles []BrowserProfileDescriptor) json.RawMessage

func BrowserCommandOutputSchema 

func BrowserCommandOutputSchema(
	command string,
	profiles []BrowserProfileDescriptor,
) json.RawMessage

func BrowserInputDigest 

func BrowserInputDigest(value string) string

func BrowserInputDigestMatches 

func BrowserInputDigestMatches(digest string, value string) bool

func BrowserPressKeyValid 

func BrowserPressKeyValid(key string) bool

BrowserPressKeyValid admits only document-scoped keys that cannot express browser chrome, operating-system, or arbitrary modifier shortcuts.

func GatewayInvocationStorePath 

func GatewayInvocationStorePath(workspace string) string

func GatewayTerminalStorePath 

func GatewayTerminalStorePath(workspace string) string

func GatewayTransferSpoolPath 

func GatewayTransferSpoolPath(workspace string) string

func InvocationDispatchErrorCode 

func InvocationDispatchErrorCode(err error) (string, bool)

func InvocationQueryErrorCode 

func InvocationQueryErrorCode(err error) (string, bool)

func IsBrowserCommand 

func IsBrowserCommand(name string) bool

func IsJobCommand 

func IsJobCommand(name string) bool

func IsServiceCommand 

func IsServiceCommand(name string) bool

func IsWorkspaceCommand 

func IsWorkspaceCommand(command string) bool

func JobCommandInputSchema 

func JobCommandInputSchema(command string, profiles []JobProfileDescriptor) json.RawMessage

func JobCommandOutputSchema 

func JobCommandOutputSchema(command string) json.RawMessage

func NewInvocationDispatchError 

func NewInvocationDispatchError(code string, cause error) error

func NewInvocationQueryError 

func NewInvocationQueryError(code string, cause error) error

func NodeUpdateInputSchema 

func NodeUpdateInputSchema(profiles []UpdateProfileDescriptor) json.RawMessage

func RegistryPath 

func RegistryPath(workspacePath string) string

RegistryPath returns the canonical per-workspace node registry location.

func ServiceCommandInputSchema 

func ServiceCommandInputSchema(
	command string,
	profiles []ServiceProfileDescriptor,
) json.RawMessage

ServiceCommandInputSchema derives the exact command schema from an already narrowed profile projection. Action authority is encoded as alias/action pairs rather than independent enums that could imply a forbidden pair.

func ServiceCommandOutputSchema 

func ServiceCommandOutputSchema(command string) json.RawMessage

func ShellExecModelInputSchema 

func ShellExecModelInputSchema(
	contract CommandModelContract,
) (json.RawMessage, error)

ShellExecModelInputSchema returns the model-visible shell.exec.v1 schema. Only operator-authored aliases and permitted environment names are projected. Shell paths, identities, environment values, and raw working paths remain node-local authority.

func SystemExecModelInputSchema 

func SystemExecModelInputSchema(
	contract CommandModelContract,
) (json.RawMessage, error)

SystemExecModelInputSchema returns the model-visible system.exec.v1 schema. It names only operator-authored aliases and visible environment names; raw enforcement paths remain accepted by the companion but are never projected.

func ValidateInvocationOutput 

func ValidateInvocationOutput(
	descriptor CommandDescriptor,
	raw json.RawMessage,
	limit int,
) (json.RawMessage, error)

ValidateInvocationOutput validates and canonicalizes a command result before it crosses the node transport boundary.

func ValidateShellExecModelInput 

func ValidateShellExecModelInput(input map[string]any) error

ValidateShellExecModelInput enforces byte ceilings that JSON Schema maxLength cannot express because maxLength counts Unicode code points.

func ValidateShellExecModelInputSchema 

func ValidateShellExecModelInputSchema(
	contract CommandModelContract,
	input map[string]any,
) error

ValidateShellExecModelInputSchema validates an invocation against the model-visible schema rather than the node-private descriptor schema.

Types

type Admission 

type Admission struct {
	Result AdmissionResult
	// contains filtered or unexported fields
}

Admission is a verified identity decision. Connected decisions become durable only through Connect, after the transport has claimed ownership.

type AdmissionConfig 

type AdmissionConfig struct {
	ChallengeTTL  time.Duration
	MaxChallenges int
	Random        io.Reader
	Now           func() time.Time
}

type AdmissionResult 

type AdmissionResult struct {
	NodeID ID    `json:"node_id"`
	State  State `json:"state"`
}

type Alias 

type Alias string

func (Alias) Validate 

func (alias Alias) Validate() error

type Authenticator 

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

func NewAuthenticator 

func NewAuthenticator(registry PairingRegistry, cfg AdmissionConfig) (*Authenticator, error)

func (*Authenticator) ApprovedCommand 

func (auth *Authenticator) ApprovedCommand(id ID, command string) (CommandApproval, error)

ApprovedCommand resolves the durable operator-approved command surface for a currently connected node.

func (*Authenticator) Authenticate 

func (auth *Authenticator) Authenticate(proof IdentityProof) (Admission, error)

func (*Authenticator) Connect 

func (auth *Authenticator) Connect(admission Admission) error

func (*Authenticator) DiscardChallenge 

func (auth *Authenticator) DiscardChallenge(nonce string)

DiscardChallenge releases an issued challenge when its connection ends before a complete proof can be admitted.

func (*Authenticator) Disconnect 

func (auth *Authenticator) Disconnect(id ID, reason string) error

func (*Authenticator) Heartbeat 

func (auth *Authenticator) Heartbeat(id ID) error

func (*Authenticator) IssueChallenge 

func (auth *Authenticator) IssueChallenge() (Challenge, error)

func (*Authenticator) WithApprovedCommand 

func (auth *Authenticator) WithApprovedCommand(
	id ID,
	command string,
	operation func(CommandApproval) error,
) (CommandApproval, error)

WithApprovedCommand keeps the durable command authority unchanged while operation commits and writes one invocation.

func (*Authenticator) WithResolvedApprovedCommand 

func (auth *Authenticator) WithResolvedApprovedCommand(
	ref string,
	command string,
	operation func(Registration, CommandApproval) error,
) (CommandApproval, error)

WithResolvedApprovedCommand resolves an operator-owned node reference and keeps its durable identity and command authority unchanged while operation performs one atomic gateway mutation.

type BrowserActInput 

type BrowserActInput struct {
	SessionID             string        `json:"session_id"`
	TabID                 string        `json:"tab_id"`
	SnapshotGeneration    uint64        `json:"snapshot_generation"`
	ActionInvocationID    string        `json:"action_invocation_id"`
	Action                BrowserAction `json:"action"`
	Effect                string        `json:"effect"`
	CurrentOrigin         string        `json:"current_origin"`
	PreparedActionHash    string        `json:"prepared_action_hash"`
	BrowserPolicyRevision string        `json:"browser_policy_revision"`
	ProfileRevision       string        `json:"profile_revision"`
	ExpectedRole          string        `json:"expected_role,omitempty"`
	ExpectedName          string        `json:"expected_name,omitempty"`
	InputDigest           string        `json:"input_digest,omitempty"`
	InputBytes            int           `json:"input_bytes,omitempty"`
	ApprovalDigest        string        `json:"approval_digest,omitempty"`
}

func (*BrowserActInput) UnmarshalJSON 

func (input *BrowserActInput) UnmarshalJSON(data []byte) error

type BrowserActResult 

type BrowserActResult struct {
	ActionInvocationID string                    `json:"action_invocation_id"`
	State              string                    `json:"state"`
	Reason             string                    `json:"reason,omitempty"`
	Observation        *BrowserObservationResult `json:"observation,omitempty"`
}

type BrowserAction 

type BrowserAction struct {
	Kind      string `json:"kind"`
	URL       string `json:"url,omitempty"`
	Ref       string `json:"ref,omitempty"`
	Target    string `json:"target,omitempty"`
	Value     string `json:"value,omitempty"`
	Key       string `json:"key,omitempty"`
	Direction string `json:"direction,omitempty"`
	Amount    int    `json:"amount,omitempty"`
}

func (*BrowserAction) UnmarshalJSON 

func (action *BrowserAction) UnmarshalJSON(data []byte) error

type BrowserElement 

type BrowserElement struct {
	Ref  string `json:"ref"`
	Role string `json:"role"`
	Name string `json:"name"`
}

type BrowserHostActRequest 

type BrowserHostActRequest struct {
	SessionID             string
	RoutedSessionID       string
	TabID                 string
	SnapshotGeneration    uint64
	ActionInvocationID    string
	Action                BrowserAction
	Effect                string
	CurrentOrigin         string
	PreparedActionHash    string
	BrowserPolicyRevision string
	ProfileRevision       string
	ApprovalDigest        string
	ExpectedRole          string
	ExpectedName          string
	AgentID               string
	ActorID               string
}

type BrowserHostFeatures 

type BrowserHostFeatures struct {
	Observe    bool `json:"observe"`
	Navigate   bool `json:"navigate"`
	Screenshot bool `json:"screenshot"`
	Download   bool `json:"download"`
}

type BrowserHostObserveRequest 

type BrowserHostObserveRequest struct {
	SessionID          string
	RoutedSessionID    string
	TabID              string
	SnapshotGeneration uint64
	Screenshot         bool
	AgentID            string
	ActorID            string
}

type BrowserHostOpenRequest 

type BrowserHostOpenRequest struct {
	SessionID             string
	RoutedSessionID       string
	Profile               string
	ProfileRevision       string
	BrowserPolicyRevision string
	AgentID               string
	ActorID               string
	DryRun                bool
	Limits                BrowserLimits
}

type BrowserHostStatusRequest 

type BrowserHostStatusRequest struct {
	SessionID       string
	RoutedSessionID string
	ProfileRevision string
	AgentID         string
	ActorID         string
}

type BrowserLimits 

type BrowserLimits struct {
	Sessions        int `json:"sessions"`
	Tabs            int `json:"tabs"`
	SessionSeconds  int `json:"session_seconds"`
	IdleSeconds     int `json:"idle_seconds"`
	PreparedSeconds int `json:"prepared_seconds"`
	ActionSeconds   int `json:"action_seconds"`
	SnapshotBytes   int `json:"snapshot_bytes"`
	ScreenshotBytes int `json:"screenshot_bytes"`
	UploadBytes     int `json:"upload_bytes"`
	DownloadBytes   int `json:"download_bytes"`
	SnapshotRefs    int `json:"snapshot_refs"`
	TextInputBytes  int `json:"text_input_bytes"`
	ToolResultBytes int `json:"tool_result_bytes"`
	RetentionSecs   int `json:"retention_seconds"`
}

func (BrowserLimits) Effective 

func (limits BrowserLimits) Effective() BrowserLimits

func (BrowserLimits) Validate 

func (limits BrowserLimits) Validate() error

type BrowserObservationResult 

type BrowserObservationResult struct {
	SessionID          string           `json:"session_id"`
	TabID              string           `json:"tab_id"`
	SnapshotGeneration uint64           `json:"snapshot_generation"`
	URL                string           `json:"url"`
	Origin             string           `json:"origin"`
	Title              string           `json:"title,omitempty"`
	Snapshot           string           `json:"snapshot"`
	Elements           []BrowserElement `json:"elements"`
	Truncated          bool             `json:"truncated"`
}

func (*BrowserObservationResult) UnmarshalJSON 

func (result *BrowserObservationResult) UnmarshalJSON(data []byte) error

type BrowserObserveInput 

type BrowserObserveInput struct {
	SessionID          string `json:"session_id"`
	TabID              string `json:"tab_id"`
	SnapshotGeneration uint64 `json:"snapshot_generation"`
	Screenshot         bool   `json:"screenshot"`
}

func (*BrowserObserveInput) UnmarshalJSON 

func (input *BrowserObserveInput) UnmarshalJSON(data []byte) error

type BrowserProfileDescriptor 

type BrowserProfileDescriptor struct {
	Alias                string        `json:"alias"`
	Revision             string        `json:"revision"`
	Driver               string        `json:"driver"`
	Mode                 string        `json:"mode"`
	NetworkMode          string        `json:"network_mode"`
	DryRun               bool          `json:"dry_run"`
	AllowApprovedActions bool          `json:"allow_approved_actions,omitempty"`
	Headed               bool          `json:"headed"`
	Actions              []string      `json:"actions"`
	Limits               BrowserLimits `json:"limits"`
}

BrowserProfileDescriptor is the model-safe projection of companion-local browser authority. Driver commands, endpoints, profile paths, lock paths, environment, and credentials intentionally never cross the node boundary.

func CloneBrowserProfileDescriptors 

func CloneBrowserProfileDescriptors(profiles []BrowserProfileDescriptor) []BrowserProfileDescriptor

func (BrowserProfileDescriptor) Validate 

func (profile BrowserProfileDescriptor) Validate() error

type BrowserSessionOpenInput 

type BrowserSessionOpenInput struct {
	SessionID             string        `json:"session_id"`
	Profile               string        `json:"profile"`
	ProfileRevision       string        `json:"profile_revision"`
	BrowserPolicyRevision string        `json:"browser_policy_revision"`
	DryRun                bool          `json:"dry_run"`
	Limits                BrowserLimits `json:"limits"`
}

Browser command payloads are the typed internal gateway-to-companion contract. They intentionally contain no transport endpoints, driver commands, profile paths, credentials, or model-selected node identity.

func (*BrowserSessionOpenInput) UnmarshalJSON 

func (input *BrowserSessionOpenInput) UnmarshalJSON(data []byte) error

type BrowserSessionResult 

type BrowserSessionResult struct {
	SessionID     string              `json:"session_id"`
	State         string              `json:"state"`
	Reason        string              `json:"reason,omitempty"`
	Recovery      string              `json:"recovery,omitempty"`
	TabID         string              `json:"tab_id,omitempty"`
	Controller    string              `json:"controller,omitempty"`
	Features      BrowserHostFeatures `json:"features,omitempty"`
	ExpiresAt     int64               `json:"expires_at,omitempty"`
	IdleExpiresAt int64               `json:"idle_expires_at,omitempty"`
}

func (BrowserSessionResult) MarshalJSON 

func (result BrowserSessionResult) MarshalJSON() ([]byte, error)

func (*BrowserSessionResult) UnmarshalJSON 

func (result *BrowserSessionResult) UnmarshalJSON(data []byte) error

type BrowserSessionStatusInput 

type BrowserSessionStatusInput struct {
	SessionID       string `json:"session_id"`
	ProfileRevision string `json:"profile_revision"`
}

type CapabilityCatalog 

type CapabilityCatalog struct {
	Commands []CommandDescriptor `json:"commands"`
}

func (CapabilityCatalog) Hash 

func (catalog CapabilityCatalog) Hash() (string, error)

Hash returns a stable digest regardless of descriptor or schema key order.

func (CapabilityCatalog) Validate 

func (catalog CapabilityCatalog) Validate() error

type Challenge 

type Challenge struct {
	Nonce       string `json:"nonce"`
	MinProtocol int    `json:"min_protocol"`
	MaxProtocol int    `json:"max_protocol"`
	ExpiresAt   int64  `json:"expires_at"`
}

type CommandApproval 

type CommandApproval struct {
	Descriptor  CommandDescriptor
	CatalogHash string
}

CommandApproval binds one command descriptor to the exact capability catalog approved for the connected node.

type CommandDescriptor 

type CommandDescriptor struct {
	Name             string                     `json:"name"`
	InputSchema      json.RawMessage            `json:"input_schema"`
	OutputSchema     json.RawMessage            `json:"output_schema"`
	Risk             Risk                       `json:"risk"`
	SupportsProgress bool                       `json:"supports_progress,omitempty"`
	SupportsCancel   bool                       `json:"supports_cancel,omitempty"`
	ModelContract    *CommandModelContract      `json:"model_contract,omitempty"`
	FileProfiles     []FileProfileDescriptor    `json:"file_profiles,omitempty"`
	ServiceProfiles  []ServiceProfileDescriptor `json:"service_profiles,omitempty"`
	BrowserProfiles  []BrowserProfileDescriptor `json:"browser_profiles,omitempty"`
	UpdateProfiles   []UpdateProfileDescriptor  `json:"update_profiles,omitempty"`
	JobProfiles      []JobProfileDescriptor     `json:"job_profiles,omitempty"`
}

func BrowserCommandDescriptors 

func BrowserCommandDescriptors(profiles []BrowserProfileDescriptor) ([]CommandDescriptor, error)

BrowserCommandDescriptors returns the internal typed capability catalog for one or more already-normalized companion profiles. It intentionally omits a model contract: the gateway browser broker, not nodes_invoke, is the only model-facing surface.

func JobCommandDescriptors 

func JobCommandDescriptors(profiles []JobProfileDescriptor) ([]CommandDescriptor, error)

func ProjectFileDescriptorForProfile 

func ProjectFileDescriptorForProfile(
	descriptor CommandDescriptor,
	profileAlias string,
) (CommandDescriptor, bool)

ProjectFileDescriptorForProfile narrows one authenticated file-capability descriptor to the operator-selected profile used by an execution target. The input schema remains the catalog schema; the prepared input binds the exact profile revision separately.

func ProjectJobDescriptorForProfile 

func ProjectJobDescriptorForProfile(
	descriptor CommandDescriptor,
	profileAlias string,
) (CommandDescriptor, bool)

func ProjectServiceDescriptorForProfile 

func ProjectServiceDescriptorForProfile(
	descriptor CommandDescriptor,
	profileAlias string,
) (CommandDescriptor, bool)

ProjectServiceDescriptorForProfile narrows a companion-authenticated service descriptor to the one operator-configured target profile. The projected descriptor is the exact authority that discovery, approval, the execution plan, and companion authorization must bind.

func ProjectUpdateDescriptorForProfile 

func ProjectUpdateDescriptorForProfile(
	descriptor CommandDescriptor,
	profileAlias string,
) (CommandDescriptor, bool)

func WorkspaceDescriptors 

func WorkspaceDescriptors(
	profiles []FileProfileDescriptor,
	workingScopes []string,
) ([]CommandDescriptor, error)

WorkspaceDescriptors returns node-internal command contracts. They stay model-unavailable in generic nodes discovery; the gateway P8a router binds profile, scope, and workspace revision before preparing an invocation.

func (CommandDescriptor) Capability 

func (descriptor CommandDescriptor) Capability() string

func (CommandDescriptor) Hash 

func (descriptor CommandDescriptor) Hash() (string, error)

Hash returns the canonical identity of one command contract.

func (CommandDescriptor) Validate 

func (descriptor CommandDescriptor) Validate() error

type CommandModelConstraints 

type CommandModelConstraints struct {
	ExecutableAliases []string `json:"executable_aliases,omitempty"`
	ProfileAliases    []string `json:"profile_aliases,omitempty"`
	WorkingScopes     []string `json:"working_scopes,omitempty"`
	EnvironmentNames  []string `json:"environment_names,omitempty"`
}

type CommandModelContract 

type CommandModelContract struct {
	Availability      ModelAvailability       `json:"availability"`
	TimeoutSecondsMax int                     `json:"timeout_seconds_max"`
	OutputBytesMax    int                     `json:"output_bytes_max"`
	ResultKind        string                  `json:"result_kind"`
	AuthorityDigest   string                  `json:"authority_digest,omitempty"`
	ApprovalMode      string                  `json:"approval_mode,omitempty"`
	Constraints       CommandModelConstraints `json:"constraints"`
	Guidance          []string                `json:"guidance"`
	Examples          []json.RawMessage       `json:"examples"`
}

func (CommandModelContract) Validate 

func (contract CommandModelContract) Validate(inputSchema json.RawMessage) error

type Disconnect 

type Disconnect struct {
	Reason string
	At     int64
}

type ExecutionPlan 

type ExecutionPlan struct {
	InvocationRequest
	Risk           Risk   `json:"risk"`
	DescriptorHash string `json:"descriptor_hash"`
	Executor       string `json:"executor"`
	PolicyRevision string `json:"policy_revision"`
	PreparedAt     int64  `json:"prepared_at"`
	ExpiresAt      int64  `json:"expires_at"`
	PlanHash       string `json:"plan_hash"`
}

ExecutionPlan is the canonical authority reviewed before dispatch. PlanHash is a binding digest, not proof of origin; approval and ledger records retain the expected digest independently and compare it before dispatch.

func PrepareExecutionPlan 

func PrepareExecutionPlan(
	request InvocationRequest,
	descriptor CommandDescriptor,
	executor string,
	policyRevision string,
	preparedAt time.Time,
	ttl time.Duration,
) (ExecutionPlan, error)

func (ExecutionPlan) Validate 

func (plan ExecutionPlan) Validate() error

func (ExecutionPlan) ValidateAgainstHash 

func (plan ExecutionPlan) ValidateAgainstHash(expected string) error

ValidateAgainstHash verifies both plan self-consistency and the binding to a digest retained outside the mutable plan, such as an approval record.

type ExecutionProfile 

type ExecutionProfile struct {
	Executor       string `json:"executor,omitempty"`
	PolicyRevision string `json:"policy_revision,omitempty"`
}

ExecutionProfile is the node-authenticated authority required to prepare an execution plan. Both fields are absent for legacy discovery-only sessions.

func (ExecutionProfile) Validate 

func (profile ExecutionProfile) Validate() error

func (ExecutionProfile) ValidateOptional 

func (profile ExecutionProfile) ValidateOptional() error

type FileProfileApproval 

type FileProfileApproval struct {
	Metadata string `json:"metadata"`
	Read     string `json:"read"`
	Write    string `json:"write"`
}

type FileProfileDescriptor 

type FileProfileDescriptor struct {
	Alias          string              `json:"alias"`
	Revision       string              `json:"revision"`
	ReadableRoots  []string            `json:"readable_roots,omitempty"`
	WritableRoots  []string            `json:"writable_roots,omitempty"`
	AllowCreate    bool                `json:"allow_create,omitempty"`
	AllowOverwrite bool                `json:"allow_overwrite,omitempty"`
	MaxFileBytes   int64               `json:"max_file_bytes"`
	Approval       FileProfileApproval `json:"approval"`
}

FileProfileDescriptor is the authenticated, model-safe projection of one node-local regular-file profile. The gateway selects it only through operator-owned target configuration; model tool input never carries Alias, Revision, roots, approval, or limits.

func (FileProfileDescriptor) Validate 

func (profile FileProfileDescriptor) Validate() error

type FileRegistry 

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

func NewFileRegistry 

func NewFileRegistry(path string, maxPending int) (*FileRegistry, error)

func (*FileRegistry) Approve 

func (registry *FileRegistry) Approve(id ID, approval PairingApproval) (Registration, error)

Approve pairs a pending identity or renews an existing command-surface approval. It records only commands present in the authenticated catalog.

func (*FileRegistry) Deny 

func (registry *FileRegistry) Deny(id ID, revocation Revocation) (Registration, error)

Deny transitions a pending identity to revoked so reconnecting with the same key cannot recreate an operator prompt indefinitely.

func (*FileRegistry) List 

func (registry *FileRegistry) List(filter Filter) ([]Snapshot, error)

func (*FileRegistry) MarkDisconnected 

func (registry *FileRegistry) MarkDisconnected(id ID, disconnect Disconnect) error

func (*FileRegistry) Pending 

func (registry *FileRegistry) Pending(id ID) (PendingPairing, bool, error)

func (*FileRegistry) Registration 

func (registry *FileRegistry) Registration(id ID) (Registration, bool, error)

Registration returns the durable operator and authentication state for one node. Callers receive copies and cannot mutate registry-owned slices.

func (*FileRegistry) Resolve 

func (registry *FileRegistry) Resolve(ref string) (Snapshot, bool, error)

func (*FileRegistry) Revoke 

func (registry *FileRegistry) Revoke(id ID, revocation Revocation) (Registration, error)

Revoke removes all approved command authority from an already paired node.

func (*FileRegistry) Upsert 

func (registry *FileRegistry) Upsert(snapshot Snapshot) error

func (*FileRegistry) UpsertPending 

func (registry *FileRegistry) UpsertPending(pairing PendingPairing) error

type Filter 

type Filter struct {
	States []State
	Alias  Alias
}

type GatewayInvocationCancellation 

type GatewayInvocationCancellation struct {
	RequestedAt int64 `json:"requested_at"`
}

type GatewayInvocationOwner 

type GatewayInvocationOwner struct {
	Target      string
	AgentID     string
	SessionID   string
	ActorID     string
	ToolCallID  string
	WorkspaceID string
	ExecutionID string
}

type GatewayInvocationPrincipal 

type GatewayInvocationPrincipal struct {
	AgentID     string
	SessionID   string
	ActorID     string
	WorkspaceID string
	ExecutionID string
}

type GatewayInvocationRecord 

type GatewayInvocationRecord struct {
	Target           string                         `json:"target"`
	ToolCallID       string                         `json:"tool_call_id"`
	Plan             ExecutionPlan                  `json:"plan"`
	Descriptor       CommandDescriptor              `json:"descriptor"`
	ExpectedPlanHash string                         `json:"expected_plan_hash"`
	State            GatewayInvocationState         `json:"state"`
	CreatedAt        int64                          `json:"created_at"`
	UpdatedAt        int64                          `json:"updated_at"`
	DispatchedAt     int64                          `json:"dispatched_at,omitempty"`
	WorkspaceID      string                         `json:"workspace_id,omitempty"`
	ExecutionID      string                         `json:"execution_id,omitempty"`
	Cancellation     *GatewayInvocationCancellation `json:"cancellation,omitempty"`
}

GatewayInvocationRecord is the gateway-owned authority that links one model tool call to one immutable execution plan. ExpectedPlanHash is stored separately so a mutated plan cannot validate itself.

type GatewayInvocationState 

type GatewayInvocationState string
const (
	GatewayInvocationPrepared   GatewayInvocationState = "prepared"
	GatewayInvocationDispatched GatewayInvocationState = "dispatched"
)

type GatewayInvocationStore 

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

GatewayInvocationStore persists prepared plan ownership across gateway restarts. A cross-instance file lock keeps the snapshot canonical while atomic replacement prevents crash recovery from observing a partial write.

func NewGatewayInvocationStore 

func NewGatewayInvocationStore(
	path string,
	maxRecords int,
	maxBytes int,
) (*GatewayInvocationStore, error)

func (*GatewayInvocationStore) ByToolCall 

func (store *GatewayInvocationStore) ByToolCall(
	principal GatewayInvocationPrincipal,
	toolCallID string,
) (GatewayInvocationRecord, bool, error)

func (*GatewayInvocationStore) Close 

func (store *GatewayInvocationStore) Close() error

Close releases the retained file identity. It is safe to call repeatedly; no store operation is admitted after the first close.

func (*GatewayInvocationStore) Lookup 

func (store *GatewayInvocationStore) Lookup(
	principal GatewayInvocationPrincipal,
	invocationID string,
) (GatewayInvocationRecord, bool, error)

func (*GatewayInvocationStore) MarkDispatched 

func (store *GatewayInvocationStore) MarkDispatched(
	owner GatewayInvocationOwner,
	invocationID string,
	expectedPlanHash string,
) (GatewayInvocationRecord, bool, error)

func (*GatewayInvocationStore) Prepare 

func (store *GatewayInvocationStore) Prepare(
	target string,
	toolCallID string,
	plan ExecutionPlan,
	descriptor CommandDescriptor,
) (GatewayInvocationRecord, bool, error)

func (*GatewayInvocationStore) PrepareOwned 

func (store *GatewayInvocationStore) PrepareOwned(
	principal GatewayInvocationPrincipal,
	target string,
	toolCallID string,
	plan ExecutionPlan,
	descriptor CommandDescriptor,
) (GatewayInvocationRecord, bool, error)

func (*GatewayInvocationStore) RequestCancellation 

func (store *GatewayInvocationStore) RequestCancellation(
	principal GatewayInvocationPrincipal,
	invocationID string,
) (GatewayInvocationRecord, bool, error)

type GatewayTerminalRecord 

type GatewayTerminalRecord struct {
	Plan                 TerminalOpenPlan     `json:"plan"`
	ExpectedPlanHash     string               `json:"expected_plan_hash"`
	TerminalID           string               `json:"terminal_id,omitempty"`
	State                GatewayTerminalState `json:"state"`
	Reason               string               `json:"reason,omitempty"`
	CreatedAt            int64                `json:"created_at"`
	UpdatedAt            int64                `json:"updated_at"`
	DispatchedAt         int64                `json:"dispatched_at,omitempty"`
	StartedAt            int64                `json:"started_at,omitempty"`
	CompletedAt          int64                `json:"completed_at,omitempty"`
	ExitCode             int                  `json:"exit_code,omitempty"`
	Signal               string               `json:"signal,omitempty"`
	TerminationConfirmed bool                 `json:"termination_confirmed,omitempty"`
}

GatewayTerminalRecord is the gateway-owned durable authority for one attached terminal. It intentionally retains no terminal input or output.

type GatewayTerminalState 

type GatewayTerminalState string
const (
	GatewayTerminalPrepared      GatewayTerminalState = "prepared"
	GatewayTerminalDispatched    GatewayTerminalState = "dispatched"
	GatewayTerminalPendingAttach GatewayTerminalState = "pending_attach"
	GatewayTerminalLive          GatewayTerminalState = "live"
	GatewayTerminalClosing       GatewayTerminalState = "closing"
	GatewayTerminalClosed        GatewayTerminalState = "closed"
	GatewayTerminalUnknown       GatewayTerminalState = "unknown"
)

type GatewayTerminalStore 

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

GatewayTerminalStore persists terminal plans and redacted lifecycle metadata. Opening the store converts any previously active terminal to unknown because P1 deliberately has no reconnect or replay.

func NewGatewayTerminalStore 

func NewGatewayTerminalStore(path string, maxRecords, maxBytes int) (*GatewayTerminalStore, error)

func OpenExistingGatewayTerminalStore 

func OpenExistingGatewayTerminalStore(
	path string,
	maxRecords int,
	maxBytes int,
) (*GatewayTerminalStore, bool, error)

OpenExistingGatewayTerminalStore recovers an existing lifecycle document without creating one. The leaf is opened atomically without following symlinks and must be a regular file.

func (*GatewayTerminalStore) Lookup 

func (store *GatewayTerminalStore) Lookup(
	owner TerminalOwner,
	terminalRef string,
) (GatewayTerminalRecord, bool, error)

func (*GatewayTerminalStore) MarkDispatched 

func (store *GatewayTerminalStore) MarkDispatched(
	owner TerminalOwner,
	openID string,
	expectedPlanHash string,
) (GatewayTerminalRecord, bool, error)

func (*GatewayTerminalStore) Prepare 

func (store *GatewayTerminalStore) Prepare(
	plan TerminalOpenPlan,
) (GatewayTerminalRecord, bool, error)

func (*GatewayTerminalStore) ReconcileShutdown 

func (store *GatewayTerminalStore) ReconcileShutdown() error

ReconcileShutdown records that live gateway authority ended after the node transport was drained. It always rewrites the document so a caller can retry an earlier committed-but-not-confirmed atomic write.

func (*GatewayTerminalStore) RecordLifecycle 

func (store *GatewayTerminalStore) RecordLifecycle(
	owner TerminalOwner,
	terminalID string,
	metadata TerminalMetadata,
) (GatewayTerminalRecord, bool, error)

func (*GatewayTerminalStore) RecordOpened 

func (store *GatewayTerminalStore) RecordOpened(
	owner TerminalOwner,
	openID string,
	metadata TerminalMetadata,
) (GatewayTerminalRecord, bool, error)

type GatewayTransferSpool 

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

GatewayTransferSpool owns bounded gateway-side transfer bytes. One process holds the anchored directory lease at a time so restart reconciliation can classify staging records without racing another live writer.

func NewGatewayTransferSpool 

func NewGatewayTransferSpool(
	root string,
	maxRecords int,
	maxBytes int64,
	retention time.Duration,
) (*GatewayTransferSpool, error)

func (*GatewayTransferSpool) Begin 

func (store *GatewayTransferSpool) Begin(
	owner TransferArtifactOwner,
	spec TransferArtifactSpec,
) (*TransferArtifactWriter, TransferArtifactRecord, bool, error)

func (*GatewayTransferSpool) ClaimDelivery 

func (store *GatewayTransferSpool) ClaimDelivery(
	owner TransferArtifactOwner,
	ref string,
	mediaRef string,
	deliveryKey string,
) (TransferArtifactRecord, bool, error)

ClaimDelivery durably records the one permitted routed-delivery attempt for a committed artifact. A duplicate claim returns the original record without authorizing another outbound send.

func (*GatewayTransferSpool) Cleanup 

func (store *GatewayTransferSpool) Cleanup() (int, error)

func (*GatewayTransferSpool) Close 

func (store *GatewayTransferSpool) Close() error

func (*GatewayTransferSpool) LookupCommittedSource 

func (store *GatewayTransferSpool) LookupCommittedSource(
	sourceKind string,
	sourceID string,
) (TransferArtifactRecord, bool, error)

LookupCommittedSource returns the one committed artifact bound to an exact producer kind and source identifier. Source identifiers are durable, authority-derived correlations rather than bearer references.

func (*GatewayTransferSpool) LookupTransfer 

func (store *GatewayTransferSpool) LookupTransfer(
	owner TransferArtifactOwner,
	transferID string,
) (TransferArtifactRecord, bool, error)

LookupTransfer returns the artifact owned by one transfer identity without making the opaque reference bearer authority.

func (*GatewayTransferSpool) Release 

func (store *GatewayTransferSpool) Release(
	owner TransferArtifactOwner,
	spec TransferArtifactSpec,
	ref string,
) error

func (*GatewayTransferSpool) Resolve 

func (store *GatewayTransferSpool) Resolve(
	owner TransferArtifactOwner,
	spec TransferArtifactSpec,
	ref string,
) (*os.File, TransferArtifactRecord, error)

func (*GatewayTransferSpool) ResolveOwned 

func (store *GatewayTransferSpool) ResolveOwned(
	owner TransferArtifactOwner,
	ref string,
) (*os.File, TransferArtifactRecord, error)

ResolveOwned opens an already committed artifact only when the complete retained owner tuple matches. It is used when a durable transfer plan already binds the exact artifact specification and must not trust a model-supplied duplicate of that metadata.

func (*GatewayTransferSpool) ResolveRoutedDownload 

func (store *GatewayTransferSpool) ResolveRoutedDownload(
	owner TransferArtifactOwner,
	ref string,
) (*os.File, TransferArtifactRecord, error)

ResolveRoutedDownload opens a committed download for a later upload in the same durable routed authority. The originating and consuming tool calls are necessarily different, so the opaque reference is authorized by every retained owner dimension except ToolCallID. Upload artifacts are never reusable through this path.

type ID 

type ID string

func DeriveID 

func DeriveID(publicKey ed25519.PublicKey) (ID, error)

func (ID) Validate 

func (id ID) Validate() error

type IdentityProof 

type IdentityProof struct {
	Nonce          string            `json:"nonce"`
	NodeID         ID                `json:"node_id"`
	PublicKey      string            `json:"public_key"`
	Signature      string            `json:"signature"`
	MinProtocol    int               `json:"min_protocol"`
	MaxProtocol    int               `json:"max_protocol"`
	ClientVersion  string            `json:"client_version"`
	Platform       string            `json:"platform"`
	Architecture   string            `json:"architecture"`
	RequestedRole  string            `json:"requested_role"`
	CatalogHash    string            `json:"catalog_hash"`
	Catalog        CapabilityCatalog `json:"catalog"`
	Executor       string            `json:"executor,omitempty"`
	PolicyRevision string            `json:"policy_revision,omitempty"`
}

func NewIdentityProof 

func NewIdentityProof(
	privateKey ed25519.PrivateKey,
	nonce string,
	minProtocol, maxProtocol int,
	clientVersion, platform, architecture string,
	catalog CapabilityCatalog,
	profile ExecutionProfile,
) (IdentityProof, error)

func (IdentityProof) Verify 

func (proof IdentityProof) Verify() (ed25519.PublicKey, error)

type InvocationCancelRequest 

type InvocationCancelRequest struct {
	InvocationID string `json:"invocation_id"`
}

func (InvocationCancelRequest) Validate 

func (request InvocationCancelRequest) Validate() error

type InvocationCancellation 

type InvocationCancellation struct {
	RequestedAt          int64 `json:"requested_at"`
	TerminationConfirmed bool  `json:"termination_confirmed"`
}

InvocationCancellation records a durable cancellation request separately from its outcome. TerminationConfirmed becomes true only after the node can prove the cancel-capable command handler has stopped.

type InvocationDispatch 

type InvocationDispatch struct {
	Plan           ExecutionPlan   `json:"plan"`
	EphemeralInput json.RawMessage `json:"ephemeral_input,omitempty"`
}

InvocationDispatch is the transport-only envelope for an execution plan and an optional input that must never enter either durable invocation ledger. The durable plan binds the ephemeral bytes by digest and length; the command handler independently verifies that binding before ledger acceptance.

func (InvocationDispatch) Validate 

func (dispatch InvocationDispatch) Validate() error

type InvocationDispatchError 

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

InvocationDispatchError carries a bounded companion response classification across the WebSocket, gateway, and model-facing invocation boundary. Its Error output intentionally excludes the remote message and transport detail.

func (*InvocationDispatchError) Error 

func (err *InvocationDispatchError) Error() string

func (*InvocationDispatchError) Unwrap 

func (err *InvocationDispatchError) Unwrap() error

type InvocationFailure 

type InvocationFailure struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

func (InvocationFailure) Validate 

func (failure InvocationFailure) Validate() error

type InvocationQuery 

type InvocationQuery struct {
	InvocationID string `json:"invocation_id"`
}

func (InvocationQuery) Validate 

func (query InvocationQuery) Validate() error

type InvocationQueryError 

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

InvocationQueryError carries one bounded, safe classification across the companion, gateway, and model-facing recovery boundary without exposing a transport endpoint or remote error message.

func (*InvocationQueryError) Error 

func (err *InvocationQueryError) Error() string

func (*InvocationQueryError) Unwrap 

func (err *InvocationQueryError) Unwrap() error

type InvocationRecord 

type InvocationRecord struct {
	InvocationID   string                   `json:"invocation_id"`
	IdempotencyKey string                   `json:"idempotency_key"`
	PlanHash       string                   `json:"plan_hash"`
	NodeID         ID                       `json:"node_id"`
	CatalogHash    string                   `json:"catalog_hash"`
	Command        string                   `json:"command"`
	Risk           Risk                     `json:"risk"`
	Update         *NodeUpdatePlanAuthority `json:"update,omitempty"`
	State          InvocationState          `json:"state"`
	AcceptedAt     int64                    `json:"accepted_at"`
	UpdatedAt      int64                    `json:"updated_at"`
	ExpiresAt      int64                    `json:"expires_at"`
	CompletedAt    int64                    `json:"completed_at,omitempty"`
	Result         json.RawMessage          `json:"result,omitempty"`
	Failure        *InvocationFailure       `json:"failure,omitempty"`
	Cancellation   *InvocationCancellation  `json:"cancellation,omitempty"`
}

InvocationRecord is the durable companion-owned proof of one accepted logical invocation. Result bytes remain bounded by the execution plan.

func (InvocationRecord) Validate 

func (record InvocationRecord) Validate() error

type InvocationRequest 

type InvocationRequest struct {
	InvocationID     string                   `json:"invocation_id"`
	IdempotencyKey   string                   `json:"idempotency_key"`
	NodeID           ID                       `json:"node_id"`
	CatalogHash      string                   `json:"catalog_hash"`
	Command          string                   `json:"command"`
	ServiceProfile   string                   `json:"service_profile,omitempty"`
	JobProfile       string                   `json:"job_profile,omitempty"`
	Update           *NodeUpdatePlanAuthority `json:"update,omitempty"`
	Input            json.RawMessage          `json:"input"`
	AgentID          string                   `json:"agent_id"`
	SessionID        string                   `json:"session_id"`
	ActorID          string                   `json:"actor_id"`
	TimeoutSeconds   int                      `json:"timeout_seconds"`
	OutputLimitBytes int                      `json:"output_limit_bytes"`
}

InvocationRequest is the transport-neutral command request prepared by the gateway. It contains no connection details or shell-specific authority.

func (InvocationRequest) Validate 

func (request InvocationRequest) Validate() error

type InvocationState 

type InvocationState string
const (
	InvocationAccepted  InvocationState = "accepted"
	InvocationRunning   InvocationState = "running"
	InvocationSucceeded InvocationState = "succeeded"
	InvocationFailed    InvocationState = "failed"
	InvocationCanceled  InvocationState = "canceled"
	InvocationUnknown   InvocationState = "unknown"
)

func (InvocationState) Terminal 

func (state InvocationState) Terminal() bool

func (InvocationState) Valid 

func (state InvocationState) Valid() bool

type JobProfileApproval 

type JobProfileApproval struct {
	Start  string `json:"start"`
	Read   string `json:"read"`
	Cancel string `json:"cancel"`
}

type JobProfileDescriptor 

type JobProfileDescriptor struct {
	Alias                  string             `json:"alias"`
	Revision               string             `json:"revision"`
	Executor               string             `json:"executor"`
	AuthorityDigest        string             `json:"authority_digest"`
	TimeoutSecondsMax      int                `json:"timeout_seconds_max"`
	ConcurrentJobs         int                `json:"concurrent_jobs"`
	StdoutBytesMax         int64              `json:"stdout_bytes_max"`
	StderrBytesMax         int64              `json:"stderr_bytes_max"`
	ArtifactCountMax       int                `json:"artifact_count_max"`
	ArtifactBytesMax       int64              `json:"artifact_bytes_max"`
	ArtifactsTotalBytesMax int64              `json:"artifacts_total_bytes_max"`
	RetentionSeconds       int                `json:"retention_seconds"`
	CancelGuarantee        string             `json:"cancel_guarantee"`
	ExecutableAliases      []string           `json:"executable_aliases"`
	WorkingScopes          []string           `json:"working_scopes"`
	EnvironmentNames       []string           `json:"environment_names"`
	Approval               JobProfileApproval `json:"approval"`
}

func CloneJobProfileDescriptors 

func CloneJobProfileDescriptors(profiles []JobProfileDescriptor) []JobProfileDescriptor

func (JobProfileDescriptor) Validate 

func (profile JobProfileDescriptor) Validate() error

type LocalCommandPolicy 

type LocalCommandPolicy struct {
	Revision          string   `json:"revision"`
	AllowedCommands   []string `json:"allowed_commands"`
	MaximumRisk       Risk     `json:"maximum_risk"`
	MaxTimeoutSeconds int      `json:"max_timeout_seconds"`
	MaxOutputBytes    int      `json:"max_output_bytes"`
}

LocalCommandPolicy is the companion-owned maximum authority. Empty command lists deny all commands, including commands approved by the gateway.

func (LocalCommandPolicy) Authorize 

func (policy LocalCommandPolicy) Authorize(
	plan ExecutionPlan,
	runtimeCatalog CapabilityCatalog,
	receivingNodeID ID,
	actualExecutor string,
	now time.Time,
) error

func (LocalCommandPolicy) AuthorizeReplay 

func (policy LocalCommandPolicy) AuthorizeReplay(
	plan ExecutionPlan,
	runtimeCatalog CapabilityCatalog,
	receivingNodeID ID,
	actualExecutor string,
) error

AuthorizeReplay verifies current local authority for returning a recorded invocation without requiring the original execution window to remain live.

func (LocalCommandPolicy) Validate 

func (policy LocalCommandPolicy) Validate() error

type ModelAvailability 

type ModelAvailability string
const (
	ModelAvailable          ModelAvailability = "available"
	ModelPartiallyDescribed ModelAvailability = "partially_described"
	ModelUnavailable        ModelAvailability = "unavailable"
)

func (ModelAvailability) Valid 

func (availability ModelAvailability) Valid() bool

type NodeUpdatePlanAuthority 

type NodeUpdatePlanAuthority struct {
	ExecutionID     string `json:"execution_id"`
	Profile         string `json:"profile"`
	ProfileRevision string `json:"profile_revision"`
	ReleaseAlias    string `json:"release_alias"`
	ReleaseVersion  string `json:"release_version"`
	CurrentVersion  string `json:"current_version"`
	Platform        string `json:"platform"`
	Architecture    string `json:"architecture"`
	ManifestSHA256  string `json:"manifest_sha256"`
	ArtifactSHA256  string `json:"artifact_sha256"`
	ArtifactSize    int64  `json:"artifact_size"`
	AuthorityHash   string `json:"authority_hash"`
}

NodeUpdatePlanAuthority is the bounded, non-secret update identity retained with an execution plan and invocation record. It lets a successor companion query or cancel the exact coordinator transaction without replaying it.

func NewNodeUpdatePlanAuthority 

func NewNodeUpdatePlanAuthority(
	executionID string,
	profile UpdateProfileDescriptor,
	releaseAlias string,
) (*NodeUpdatePlanAuthority, error)

func (NodeUpdatePlanAuthority) Validate 

func (authority NodeUpdatePlanAuthority) Validate() error

type PairingApproval 

type PairingApproval struct {
	Aliases         []Alias
	DisplayName     string
	AllowedCommands []string
	At              int64
}

PairingApproval is the operator-owned authority granted to a pending or already paired node. AllowedCommands must be a subset of the capability catalog presented during admission; an empty list grants no executable command surface.

type PairingRegistry 

type PairingRegistry interface {
	Registry
	UpsertPending(PendingPairing) error
	Pending(ID) (PendingPairing, bool, error)
	Registration(ID) (Registration, bool, error)
	// contains filtered or unexported methods
}

type PendingPairing 

type PendingPairing struct {
	Node          Snapshot `json:"node"`
	PublicKey     []byte   `json:"public_key"`
	RequestedRole string   `json:"requested_role"`
	RequestedAt   int64    `json:"requested_at"`
}

type Registration 

type Registration struct {
	Snapshot            Snapshot
	PublicKey           []byte
	RequestedRole       string
	RequestedAt         int64
	AllowedCommands     []string
	ApprovedCatalogHash string
	ApprovedAt          int64
	RevokedAt           int64
}

Registration is the durable operator view of a node identity. PublicKey is intentionally retained here so authentication can bind approval to the exact admitted device rather than to a mutable alias.

func (Registration) ApprovedCommand 

func (registration Registration) ApprovedCommand(name string) (CommandDescriptor, error)

ApprovedCommand applies the durable pairing command surface. It does not replace agent, approval, or node-local policy checks.

type Registry 

type Registry interface {
	List(Filter) ([]Snapshot, error)
	Resolve(string) (Snapshot, bool, error)
	Upsert(Snapshot) error
	MarkDisconnected(ID, Disconnect) error
}

Registry is the durable node-state boundary. Connection ownership remains in the gateway transport layer and is represented here only as snapshots.

type Revocation 

type Revocation struct {
	Reason string
	At     int64
}

Revocation records an operator decision that prevents an identity from returning to pending admission on its next connection.

type Risk 

type Risk string
const (
	RiskRead       Risk = "read"
	RiskWrite      Risk = "write"
	RiskPrivileged Risk = "privileged"
)

func (Risk) Valid 

func (risk Risk) Valid() bool

type ServiceAction 

type ServiceAction string
const (
	ServiceActionStart   ServiceAction = "start"
	ServiceActionStop    ServiceAction = "stop"
	ServiceActionRestart ServiceAction = "restart"
	ServiceActionReload  ServiceAction = "reload"
	ServiceActionEnable  ServiceAction = "enable"
	ServiceActionDisable ServiceAction = "disable"
)

func (ServiceAction) Valid 

func (action ServiceAction) Valid() bool

type ServiceDescriptor 

type ServiceDescriptor struct {
	Alias       string          `json:"alias"`
	Description string          `json:"description,omitempty"`
	Status      bool            `json:"status,omitempty"`
	Logs        bool            `json:"logs,omitempty"`
	Actions     []ServiceAction `json:"actions,omitempty"`
}

func (ServiceDescriptor) Validate 

func (service ServiceDescriptor) Validate() error

type ServiceLogLimits 

type ServiceLogLimits struct {
	EntriesMax    int `json:"entries_max"`
	BytesMax      int `json:"bytes_max"`
	AgeSecondsMax int `json:"age_seconds_max"`
}

func (ServiceLogLimits) Validate 

func (limits ServiceLogLimits) Validate() error

type ServiceProfileDescriptor 

type ServiceProfileDescriptor struct {
	Alias          string              `json:"alias"`
	Revision       string              `json:"revision"`
	Manager        string              `json:"manager"`
	Services       []ServiceDescriptor `json:"services"`
	LogLimits      ServiceLogLimits    `json:"log_limits"`
	ActionApproval string              `json:"action_approval"`
}

ServiceProfileDescriptor is the authenticated model-safe projection of a node-local system service profile. Raw unit names and manager connection details intentionally remain local to the companion and privileged helper.

func CloneServiceProfileDescriptors 

func CloneServiceProfileDescriptors(
	profiles []ServiceProfileDescriptor,
) []ServiceProfileDescriptor

func (ServiceProfileDescriptor) Validate 

func (profile ServiceProfileDescriptor) Validate() error

type Snapshot 

type Snapshot struct {
	ID               ID                `json:"id"`
	Aliases          []Alias           `json:"aliases,omitempty"`
	DisplayName      string            `json:"display_name,omitempty"`
	State            State             `json:"state"`
	ProtocolVersion  int               `json:"protocol_version,omitempty"`
	Platform         string            `json:"platform,omitempty"`
	Architecture     string            `json:"architecture,omitempty"`
	SoftwareVersion  string            `json:"software_version,omitempty"`
	CatalogHash      string            `json:"catalog_hash,omitempty"`
	Catalog          CapabilityCatalog `json:"catalog,omitempty"`
	Executor         string            `json:"executor,omitempty"`
	PolicyRevision   string            `json:"policy_revision,omitempty"`
	LastSeenAt       int64             `json:"last_seen_at,omitempty"`
	DisconnectReason string            `json:"disconnect_reason,omitempty"`
}

func (Snapshot) Validate 

func (snapshot Snapshot) Validate() error

type State 

type State string
const (
	StatePendingPairing State = "pending_pairing"
	StateConnected      State = "connected"
	StateDisconnected   State = "disconnected"
	StateRevoked        State = "revoked"
	StateIncompatible   State = "incompatible"
	StateDegraded       State = "degraded"
)

func (State) Valid 

func (state State) Valid() bool

type TerminalControlRequest 

type TerminalControlRequest struct {
	TerminalSessionRequest
	Sequence       uint64 `json:"sequence"`
	IdempotencyKey string `json:"idempotency_key"`
	InputBase64    string `json:"input_base64,omitempty"`
	Columns        int    `json:"columns,omitempty"`
	Rows           int    `json:"rows,omitempty"`
	Signal         string `json:"signal,omitempty"`
	Close          bool   `json:"close,omitempty"`
}

func (TerminalControlRequest) Validate 

func (request TerminalControlRequest) Validate() error

type TerminalEvent 

type TerminalEvent struct {
	Version              int    `json:"version"`
	Type                 string `json:"type"`
	TerminalID           string `json:"terminal_id"`
	AcceptedSequence     uint64 `json:"accepted_sequence,omitempty"`
	Cursor               uint64 `json:"cursor,omitempty"`
	DataBase64           string `json:"data_base64,omitempty"`
	State                string `json:"state,omitempty"`
	Reason               string `json:"reason,omitempty"`
	ExitCode             int    `json:"exit_code,omitempty"`
	Signal               string `json:"signal,omitempty"`
	StartedAt            int64  `json:"started_at,omitempty"`
	CompletedAt          int64  `json:"completed_at,omitempty"`
	TerminationConfirmed bool   `json:"termination_confirmed,omitempty"`
}

TerminalEvent is the live transport shape. DataBase64 is present only for output events and must never be copied into passive records or logs.

func (TerminalEvent) Validate 

func (event TerminalEvent) Validate() (int, error)

Validate enforces the shared live-event contract at both sides of the authenticated transport. The returned size is the decoded output byte count and is zero for non-output events.

type TerminalMetadata 

type TerminalMetadata struct {
	TerminalID           string        `json:"terminal_id"`
	Owner                TerminalOwner `json:"owner"`
	State                string        `json:"state"`
	Reason               string        `json:"reason,omitempty"`
	StartedAt            int64         `json:"started_at"`
	CompletedAt          int64         `json:"completed_at,omitempty"`
	ExitCode             int           `json:"exit_code,omitempty"`
	Signal               string        `json:"signal,omitempty"`
	TerminationConfirmed bool          `json:"termination_confirmed,omitempty"`
}

type TerminalOpenPlan 

type TerminalOpenPlan struct {
	OpenID          string        `json:"open_id"`
	IdempotencyKey  string        `json:"idempotency_key"`
	NodeID          ID            `json:"node_id"`
	Owner           TerminalOwner `json:"owner"`
	CatalogHash     string        `json:"catalog_hash"`
	AuthorityDigest string        `json:"authority_digest"`
	WorkingScope    string        `json:"working_scope"`
	Columns         int           `json:"columns"`
	Rows            int           `json:"rows"`
	ApprovalMode    string        `json:"approval_mode"`
	PreparedAt      int64         `json:"prepared_at"`
	ExpiresAt       int64         `json:"expires_at"`
	PlanHash        string        `json:"plan_hash"`
}

TerminalOpenPlan is the immutable authority reviewed before a live PTY is allocated. AuthorityDigest is a safe binding to the node-local profile; it does not reveal that profile's identity, shell, paths, or environment.

func PrepareTerminalOpenPlan 

func PrepareTerminalOpenPlan(
	plan TerminalOpenPlan,
	preparedAt time.Time,
	ttl time.Duration,
) (TerminalOpenPlan, error)

func (TerminalOpenPlan) Validate 

func (plan TerminalOpenPlan) Validate() error

func (TerminalOpenPlan) ValidateAgainstHash 

func (plan TerminalOpenPlan) ValidateAgainstHash(expected string) error

type TerminalOwner 

type TerminalOwner struct {
	ActorID     string `json:"actor_id"`
	AgentID     string `json:"agent_id"`
	RouteID     string `json:"route_id"`
	SessionID   string `json:"session_id"`
	WorkspaceID string `json:"workspace_id"`
	Target      string `json:"target"`
	Profile     string `json:"profile"`
}

TerminalOwner is the complete authority tuple retained on every terminal operation. Terminal IDs are correlation values and grant no authority.

func (TerminalOwner) Validate 

func (owner TerminalOwner) Validate() error

type TerminalSessionRequest 

type TerminalSessionRequest struct {
	TerminalID string        `json:"terminal_id"`
	Owner      TerminalOwner `json:"owner"`
}

func (TerminalSessionRequest) Validate 

func (request TerminalSessionRequest) Validate() error

type TransferArtifactOwner 

type TransferArtifactOwner struct {
	WorkspaceID string `json:"workspace_id"`
	AgentID     string `json:"agent_id"`
	ActorID     string `json:"actor_id"`
	RouteID     string `json:"route_id"`
	SessionID   string `json:"session_id"`
	ToolCallID  string `json:"tool_call_id"`
}

TransferArtifactOwner is the complete gateway-side ownership tuple. The opaque artifact reference is only correlation and never bypasses this tuple.

func (TransferArtifactOwner) Validate 

func (owner TransferArtifactOwner) Validate() error

type TransferArtifactRecord 

type TransferArtifactRecord struct {
	ArtifactID   string                `json:"artifact_id"`
	Ref          string                `json:"ref"`
	Owner        TransferArtifactOwner `json:"owner"`
	Spec         TransferArtifactSpec  `json:"spec"`
	State        TransferArtifactState `json:"state"`
	StagingName  string                `json:"staging_name,omitempty"`
	DataName     string                `json:"data_name"`
	ObservedSize int64                 `json:"observed_size"`
	CreatedAt    int64                 `json:"created_at"`
	UpdatedAt    int64                 `json:"updated_at"`
	CommittedAt  int64                 `json:"committed_at,omitempty"`
	MediaRef     string                `json:"media_ref,omitempty"`
	DeliveryKey  string                `json:"delivery_key,omitempty"`
	DeliveryAt   int64                 `json:"delivery_at,omitempty"`
}

type TransferArtifactSpec 

type TransferArtifactSpec struct {
	TransferID      string            `json:"transfer_id"`
	Direction       TransferDirection `json:"direction"`
	Target          string            `json:"target"`
	ProfileRevision string            `json:"profile_revision"`
	SourceKind      string            `json:"source_kind,omitempty"`
	SourceScope     string            `json:"source_scope,omitempty"`
	SourceID        string            `json:"source_id,omitempty"`
	SourceRevision  uint64            `json:"source_revision,omitempty"`
	Filename        string            `json:"filename"`
	ContentType     string            `json:"content_type,omitempty"`
	DeclaredSize    int64             `json:"declared_size"`
	SHA256          string            `json:"sha256"`
	ExpiresAt       int64             `json:"expires_at"`
}

func (TransferArtifactSpec) Validate 

func (spec TransferArtifactSpec) Validate() error

type TransferArtifactState 

type TransferArtifactState string
const (
	TransferArtifactStaging   TransferArtifactState = "staging"
	TransferArtifactCommitted TransferArtifactState = "committed"
)

type TransferArtifactWriter 

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

func (*TransferArtifactWriter) Abort 

func (writer *TransferArtifactWriter) Abort() error

func (*TransferArtifactWriter) Commit 

func (writer *TransferArtifactWriter) Commit() (TransferArtifactRecord, error)

func (*TransferArtifactWriter) WriteChunk 

func (writer *TransferArtifactWriter) WriteChunk(sequence uint64, data []byte) error

type TransferDirection 

type TransferDirection string
const (
	TransferDirectionUpload   TransferDirection = "upload"
	TransferDirectionDownload TransferDirection = "download"
)

type UpdateProfileDescriptor 

type UpdateProfileDescriptor struct {
	Alias          string                    `json:"alias"`
	Revision       string                    `json:"revision"`
	Channel        string                    `json:"channel"`
	Approval       string                    `json:"approval"`
	CurrentVersion string                    `json:"current_version,omitempty"`
	Platform       string                    `json:"platform,omitempty"`
	Architecture   string                    `json:"architecture,omitempty"`
	Releases       []UpdateReleaseDescriptor `json:"releases"`
	Downgrade      bool                      `json:"downgrade,omitempty"`
}

func CloneUpdateProfileDescriptors 

func CloneUpdateProfileDescriptors(profiles []UpdateProfileDescriptor) []UpdateProfileDescriptor

func (UpdateProfileDescriptor) Validate 

func (profile UpdateProfileDescriptor) Validate() error

type UpdateReleaseDescriptor 

type UpdateReleaseDescriptor struct {
	Alias          string `json:"alias"`
	Version        string `json:"version"`
	Description    string `json:"description,omitempty"`
	ManifestSHA256 string `json:"manifest_sha256,omitempty"`
	ArtifactSHA256 string `json:"artifact_sha256,omitempty"`
	ArtifactSize   int64  `json:"artifact_size,omitempty"`
	AuthorityHash  string `json:"authority_hash,omitempty"`
}

func (UpdateReleaseDescriptor) Validate 

func (release UpdateReleaseDescriptor) Validate(channel string) error

Source Files

View all Source files

Directories

Path Synopsis
internal
jsonstrict
control
coordinator

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.