client

package
v0.5.36-beta Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2026 License: MIT Imports: 47 Imported by: 0

Documentation

Overview

Package client implements the workspace-bound side of the runner protocol.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrActiveLocalCredential indicates that a new enrollment was refused because the workspace already has a credential and replacement was not requested.
	ErrActiveLocalCredential = errors.New("runner already has an active local credential")
	// ErrEnrollmentDenied indicates that the control plane denied the pending enrollment.
	ErrEnrollmentDenied = errors.New("runner enrollment was denied")
	// ErrEnrollmentExpired indicates that the pending enrollment expired before approval.
	ErrEnrollmentExpired = errors.New("runner enrollment expired")
	// ErrEnrollmentSuperseded indicates that newer local enrollment state replaced this flow.
	ErrEnrollmentSuperseded = errors.New("runner enrollment was superseded by a newer local enrollment")
)

Functions

This section is empty.

Types

type ConfigLoader 

type ConfigLoader func(profile string) (llmtypes.Config, error)

ConfigLoader loads runner-owned configuration for an optional conversation profile.

type DirectWorkspaceInstanceProvider 

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

DirectWorkspaceInstanceProvider creates per-run handles backed by the runner's registered workspace. It provides lifecycle symmetry for future providers but no filesystem, process, network, or port isolation.

func NewDirectWorkspaceInstanceProvider 

func NewDirectWorkspaceInstanceProvider(workspace string) (*DirectWorkspaceInstanceProvider, error)

NewDirectWorkspaceInstanceProvider creates the initial non-isolating execution-instance provider.

func (*DirectWorkspaceInstanceProvider) Create 

func (p *DirectWorkspaceInstanceProvider) Create(ctx context.Context, _ ExecutionInstanceSpec) (ExecutionInstance, error)

Create returns a fresh lifecycle handle to the same direct workspace.

type EnrollmentAPIError 

type EnrollmentAPIError struct {
	Operation  string
	StatusCode int
	Message    string
}

EnrollmentAPIError is a non-successful response returned by a runner enrollment endpoint.

func (*EnrollmentAPIError) Error 

func (e *EnrollmentAPIError) Error() string

type EnrollmentConfig 

type EnrollmentConfig struct {
	Server                 string
	Workspace              string
	DisplayName            string
	Store                  *localstate.Store
	HTTPClient             *http.Client
	ReplaceLocalCredential bool
	// OnPending is called after pending state is securely persisted and before polling begins.
	// It is also called when an unexpired enrollment is resumed from local state.
	OnPending func(EnrollmentInfo)
}

EnrollmentConfig configures one runner device-enrollment operation.

type EnrollmentInfo 

type EnrollmentInfo struct {
	Server                  string
	Workspace               string
	UserCode                string
	VerificationURL         string
	VerificationURLComplete string
	Fingerprint             string
	ExpiresAt               time.Time
	PollInterval            time.Duration
	Resumed                 bool
}

EnrollmentInfo is the non-secret enrollment metadata suitable for display to a user.

type EnrollmentResult 

type EnrollmentResult struct {
	Info         EnrollmentInfo
	CredentialID string
	RunnerID     string
	Fingerprint  string
}

EnrollmentResult identifies the approved credential and runner registration saved locally.

func EnrollRunner 

func EnrollRunner(ctx context.Context, config EnrollmentConfig) (EnrollmentResult, error)

EnrollRunner starts or resumes device enrollment and polls until it reaches a terminal state.

type EnvironmentFactory 

type EnvironmentFactory func(workingDirectory string, runtime *extensions.Runtime) agentenv.Environment

EnvironmentFactory creates one agent environment inside a provisioned execution instance.

type ExecutionInstance 

type ExecutionInstance interface {
	WorkingDirectory() string
	Close(ctx context.Context) error
}

ExecutionInstance is the concrete filesystem/process/network backing for one runner environment. The direct-workspace implementation is not isolated; future providers can provision ephemeral backing.

type ExecutionInstanceProvider 

type ExecutionInstanceProvider interface {
	Create(ctx context.Context, spec ExecutionInstanceSpec) (ExecutionInstance, error)
}

ExecutionInstanceProvider creates the backing used before runner configuration, extensions, and tools are discovered.

type ExecutionInstanceSpec 

type ExecutionInstanceSpec struct {
	RunID          string
	ConversationID string
	Probe          bool
}

ExecutionInstanceSpec identifies one run or idle manifest probe that needs runner-side resources.

type Peer 

type Peer interface {
	Call(ctx context.Context, method string, params any, result any) error
	Notify(ctx context.Context, method string, params any) error
	NotifyUpdate(method string, params any) error
}

Peer is the symmetric runner connection used for updates and reverse UI calls.

type Runner 

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

Runner maintains one workspace lock, stable identity, and reconnecting control connection.

func NewRunner 

func NewRunner(ctx context.Context, config RunnerConfig) (*Runner, error)

NewRunner validates configuration and acquires no external resources.

func (*Runner) AcquireWorkspaceLock 

func (r *Runner) AcquireWorkspaceLock() error

AcquireWorkspaceLock claims this host workspace before it is registered.

func (*Runner) Close 

func (r *Runner) Close() error

Close releases runner-owned local resources. It must not race with Run.

func (*Runner) Commands 

func (r *Runner) Commands(ctx context.Context, environmentProfile string) ([]slashcommands.Command, error)

Commands discovers workspace and extension slash commands for an optional environment profile.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context) error

Run acquires the workspace lock and keeps the runner connected until cancellation.

type RunnerConfig 

type RunnerConfig struct {
	Server               string
	AuthToken            string
	Workspace            string
	DisplayName          string
	ServiceOptions       ServiceOptions
	Store                *localstate.Store
	ReconnectMin         time.Duration
	ReconnectMax         time.Duration
	ManifestInterval     time.Duration
	ManifestProbeTimeout time.Duration
	OnRegistered         func(protocol.RegisterResult)
	OnRetry              func(error, time.Duration)
}

RunnerConfig configures one long-running workspace-bound runner process.

type RuntimeProvider 

type RuntimeProvider interface {
	RuntimeWithConfigAndCallContext(ctx context.Context, cwd, variant string, config extensions.Config, callContext extensions.ExtensionCallContext) (*extensions.Runtime, error)
}

RuntimeProvider supplies the persistent extension runtime for the bound workspace.

type Service 

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

Service handles control-plane requests for one workspace-bound runner process.

func NewService 

func NewService(parent context.Context, workspace string, options ServiceOptions) (*Service, error)

NewService creates a runner-side request handler bound to one canonical workspace.

func (*Service) AbortActiveRun 

func (s *Service) AbortActiveRun(ctx context.Context) error

AbortActiveRun releases all local run resources after a connection loss.

func (*Service) AppendTranscript 

func (s *Service) AppendTranscript(ctx context.Context, source extensions.UIExtensionSource, request extensions.UITranscriptAppendRequest) (extensions.UITranscriptAppendResponse, error)

func (*Service) Attach 

func (s *Service) Attach(peer Peer)

Attach installs the current symmetric connection used by runner-originated calls.

func (*Service) CleanupExtensionUI 

func (s *Service) CleanupExtensionUI(extensions.UIExtensionOwner)

CleanupExtensionUI is best-effort; the control plane also closes run-scoped UI when the run ends.

func (*Service) Close 

func (s *Service) Close() error

Close releases an active environment and any runtime manager owned by the service.

func (*Service) CloseSurface 

func (s *Service) CloseSurface(ctx context.Context, source extensions.UIExtensionSource, request extensions.UISurfaceCloseRequest) (extensions.UIFrameResponse, error)

func (*Service) Confirm 

func (s *Service) Confirm(ctx context.Context, request extensions.UIConfirmRequest) (extensions.UIInputResponse, error)

func (*Service) HandleNotification 

func (s *Service) HandleNotification(ctx context.Context, method string, params json.RawMessage)

HandleNotification implements protocol.NotificationHandler for client UI events.

func (*Service) HandleRequest 

func (s *Service) HandleRequest(ctx context.Context, method string, params json.RawMessage) (any, *protocol.RPCError)

HandleRequest implements protocol.RequestHandler for control-plane requests.

func (*Service) HeartbeatSnapshot 

func (s *Service) HeartbeatSnapshot() (protocol.RunnerState, string, string)

HeartbeatSnapshot returns the legacy singular-run heartbeat shape.

func (*Service) HeartbeatSnapshotRuns 

func (s *Service) HeartbeatSnapshotRuns() (protocol.RunnerState, []string, string)

HeartbeatSnapshotRuns returns current application health and all active run IDs.

func (*Service) Input 

func (s *Service) Input(ctx context.Context, request extensions.UIInputRequest) (extensions.UIInputResponse, error)

func (*Service) Notify 

func (s *Service) Notify(ctx context.Context, request extensions.UINotifyRequest) (extensions.UIInputResponse, error)

func (*Service) OpenSurface 

func (s *Service) OpenSurface(ctx context.Context, source extensions.UIExtensionSource, request extensions.UISurfaceOpenRequest) (extensions.UIFrameResponse, error)

func (*Service) ProbeManifest 

func (s *Service) ProbeManifest(ctx context.Context, environmentProfile string) (runnerpayload.Manifest, error)

ProbeManifest snapshots runner resources for command and capability discovery without reserving a control-plane run.

func (*Service) ProbeManifestDigest 

func (s *Service) ProbeManifestDigest(ctx context.Context) (string, error)

ProbeManifestDigest snapshots idle runner resources without reserving a control-plane run.

func (*Service) RemoveWidget 

func (s *Service) RemoveWidget(ctx context.Context, source extensions.UIExtensionSource, request extensions.UIWidgetRemoveRequest) (extensions.UIFrameResponse, error)

func (*Service) Select 

func (s *Service) Select(ctx context.Context, request extensions.UISelectRequest) (extensions.UIInputResponse, error)

func (*Service) SetRegistration 

func (s *Service) SetRegistration(result protocol.RegisterResult) error

SetRegistration applies the stable ID and generation returned by runner.register.

func (*Service) SetWidget 

func (s *Service) SetWidget(ctx context.Context, source extensions.UIExtensionSource, request extensions.UIWidgetSetRequest) (extensions.UIFrameResponse, error)

func (*Service) UpdateSurface 

func (s *Service) UpdateSurface(ctx context.Context, source extensions.UIExtensionSource, request extensions.UISurfaceFrameRequest) (extensions.UIFrameResponse, error)

func (*Service) UpdateWidget 

func (s *Service) UpdateWidget(ctx context.Context, source extensions.UIExtensionSource, request extensions.UIWidgetFrameRequest) (extensions.UIFrameResponse, error)

type ServiceOptions 

type ServiceOptions struct {
	RuntimeProvider           RuntimeProvider
	ConfigLoader              ConfigLoader
	EnvironmentFactory        EnvironmentFactory
	ExecutionInstanceProvider ExecutionInstanceProvider
	CleanupTimeout            time.Duration
	// SnapshotWaitTimeout optionally bounds admission to the serialized snapshot
	// pipeline. Zero lets the caller's context own the deadline.
	SnapshotWaitTimeout time.Duration
}

ServiceOptions configures the runner-side request service.

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.