client

package
v0.5.43-beta Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 48 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")
)
View Source 
var ErrInvalidWorkingDirectory = errors.New("invalid runner working directory")

ErrInvalidWorkingDirectory identifies a caller-provided working directory that cannot be used.

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 directories on the runner host. The registered workspace is the default; no filesystem, process, network, or port isolation is provided.

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, spec ExecutionInstanceSpec) (ExecutionInstance, error)

Create returns a fresh lifecycle handle rooted at the requested host directory.

func (*DirectWorkspaceInstanceProvider) ResolveWorkingDirectory 

func (p *DirectWorkspaceInstanceProvider) ResolveWorkingDirectory(ctx context.Context, requestedCWD string) (string, error)

ResolveWorkingDirectory resolves a request using runner-host path semantics.

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 {
	ResolveWorkingDirectory(ctx context.Context, requestedCWD string) (string, error)
	Create(ctx context.Context, spec ExecutionInstanceSpec) (ExecutionInstance, error)
}

ExecutionInstanceProvider resolves and creates the backing used before runner configuration, extensions, and tools are discovered. Create must return an instance whose working directory exactly matches the canonical path returned by ResolveWorkingDirectory. ResolveWorkingDirectory should wrap ErrInvalidWorkingDirectory when the requested path is invalid.

type ExecutionInstanceSpec 

type ExecutionInstanceSpec struct {
	RunID          string
	ConversationID string
	CWD            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) (runErr 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) AcquireBackgroundTask 

func (s *Service) AcquireBackgroundTask(ctx context.Context, source extensions.UIExtensionSource, request extensions.BackgroundTaskAcquireRequest) (extensions.BackgroundTaskAcquireResponse, error)

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) CleanupBackgroundTasks 

func (s *Service) CleanupBackgroundTasks(owner extensions.UIExtensionOwner)

func (*Service) CleanupExtensionUI 

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

CleanupExtensionUI is best-effort. Runner-proxied widgets are conversation-scoped and remain owned by the control plane after a top-level 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) ExtensionUIHostCapabilities 

func (s *Service) ExtensionUIHostCapabilities(ctx context.Context) extensions.ExtensionUIHostCapabilities

ExtensionUIHostCapabilities reports the persistent UI features available to the client attached to the active runner run.

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) ReleaseBackgroundTask 

func (s *Service) ReleaseBackgroundTask(_ context.Context, source extensions.UIExtensionSource, request extensions.BackgroundTaskReleaseRequest) (extensions.BackgroundTaskReleaseResponse, error)

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.