Help us shape the future of Go! Take the 2026 Go Developer Survey

workspace

package
v0.13.4 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ModeHostPrepared = sdk.WorkspaceModeHostPrepared
	ModeRepository   = sdk.WorkspaceModeRepository
	AccessReadOnly   = "read_only"
	AccessReadWrite  = "read_write"

	CleanupAlways     = sdk.CleanupAlways
	CleanupOnTerminal = sdk.CleanupOnTerminal
	CleanupManual     = sdk.CleanupManual

	RepositoryFinalizeNone        = sdk.RepositoryFinalizeNone
	RepositoryFinalizeLocalCommit = sdk.RepositoryFinalizeLocalCommit
	RepositoryFinalizePushBranch  = sdk.RepositoryFinalizePushBranch
	RepositoryFinalizeOpenPR      = sdk.RepositoryFinalizeOpenPR
)
View Source 
const EphemeralRootEnv = "AGENT_RUNTIME_EPHEMERAL_ROOT"
View Source 
const RecoveryMetadataKey = "workspace_recovery_id"
View Source 
const RepositoryCacheModeEnv = "AGENT_RUNTIME_REPOSITORY_CACHE_MODE"
View Source 
const RepositoryCacheNamespaceEnv = "AGENT_RUNTIME_REPOSITORY_CACHE_NAMESPACE"
View Source 
const RepositoryCacheRootEnv = "AGENT_RUNTIME_REPOSITORY_CACHE_ROOT"
View Source 
const ScratchLimitBytes int64 = 512 << 20

ScratchLimitBytes bounds retained analysis data and its private package cache.

View Source 
const SessionMetadataKey = "execution_session"
View Source 
const StorageModeEnv = "AGENT_RUNTIME_WORKSPACE_STORAGE"

Variables

View Source 
var ErrDirectPublicationUnsupported = errors.New("repository provider does not support direct publication")

ErrDirectPublicationUnsupported reports a workspace provider that cannot refresh credentials for a direct push. Callers fall back to publishing with the credentials already present in the prepared checkout.

Functions

func AccessMode 

func AccessMode(agent *agentcore.Agent) string

AccessMode returns the repository access policy from an agent's execution config. An empty value preserves the runtime's legacy read-write behavior.

func AccessModeFromConfig 

func AccessModeFromConfig(config json.RawMessage) string

AccessModeFromConfig returns workspace.access from a raw execution config.

func AcquireRepositoryCache added in v0.13.0 

func AcquireRepositoryCache(ctx context.Context, root string) (func(), error)

AcquireRepositoryCache holds a shared cross-worker usage lease until the command exits. Package managers may execute concurrently; GC needs an exclusive lease.

func AcquireRunLock added in v0.11.2 

func AcquireRunLock(ctx context.Context, appID, runID string, heartbeat func()) (func(), error)

AcquireRunLock takes an exclusive advisory lock fencing a run's workspace so that two execution workers never write the same checkout concurrently. The lock lives on the workspace volume, so on a cluster-wide filesystem it is cluster-wide as well. While another holder keeps the lock the call waits, invoking heartbeat on every retry, and gives up after ten minutes. The returned release drops the lock; the lock file itself is never removed.

func CheckScratchSize added in v0.11.2 

func CheckScratchSize(root string) error

CheckScratchSize never follows symlinks. This is a storage guard, not a sandbox.

func CleanupScratch added in v0.11.2 

func CleanupScratch(appID, runID string) error

CleanupScratch removes only the deterministic scratch path for this app/run.

func CleanupScratchInSession added in v0.13.0 

func CleanupScratchInSession(ctx context.Context, appID, runID string) error

func CleanupToolState added in v0.11.2 

func CleanupToolState(workspaceRoot string) error

CleanupToolState removes only the deterministic state directory for one run. Workspace-local state remains owned by the workspace provider.

func ConfinementRoot added in v0.11.2 

func ConfinementRoot(root string) string

ConfinementRoot widens a repository checkout to the run directory shared by all of that run's repositories. Other workspace layouts remain unchanged.

func EphemeralWorkspaces added in v0.13.0 

func EphemeralWorkspaces() bool

func LeaseInSession added in v0.13.0 

func LeaseInSession(ctx context.Context, lease *agentcore.WorkspaceLease) bool

func MaintainRepositoryCaches added in v0.13.0 

func MaintainRepositoryCaches(ctx context.Context)

MaintainRepositoryCaches runs bounded background maintenance, never delaying worker startup. Only one scanner per volume runs at a time.

func NewScratch added in v0.11.2 

func NewScratch(appID, runID string) (*agentcore.WorkspaceLease, error)

NewScratch prepares run-local storage on the execution worker's writable volume.

func NewScratchInSession added in v0.13.0 

func NewScratchInSession(ctx context.Context, appID, runID string) (*agentcore.WorkspaceLease, error)

func NormalizeLease 

func NormalizeLease(lease *agentcore.WorkspaceLease)

func NormalizeRepositorySpec 

func NormalizeRepositorySpec(spec *RepositoryWorkspaceSpec)

func PruneRepositoryCaches added in v0.13.0 

func PruneRepositoryCaches(ctx context.Context, base string) error

PruneRepositoryCaches removes only idle, recognized cache directories. It never visits checkout trees and never follows symlinks while sizing/deleting.

func RegisterRepositoryCache added in v0.13.0 

func RegisterRepositoryCache(root, appID string, metadata map[string]interface{})

RegisterRepositoryCache binds a checkout to identities returned by the trusted repository spec provider. Missing identity removes the binding (private fallback). Callers must not pass agent-selected metadata here.

func RequiresHostPrepared 

func RequiresHostPrepared(agent *agentcore.Agent) bool

func ResetEphemeralRoot added in v0.11.2 

func ResetEphemeralRoot() error

ResetEphemeralRoot removes stale run directories after an execution worker restarts. It deliberately leaves unrelated entries untouched so a bad operator path cannot turn startup into a broad recursive deletion.

func Session added in v0.13.0 

func Session(ctx context.Context) string

func SessionLease added in v0.13.0 

func SessionLease(ctx context.Context, lease *agentcore.WorkspaceLease) *agentcore.WorkspaceLease

func SessionRoot added in v0.13.0 

func SessionRoot(ctx context.Context, root string) string

func SharedRepositoryCachePath added in v0.13.0 

func SharedRepositoryCachePath(root string) string

SharedRepositoryCachePath returns only the worker-authorized cache grant. No binding means no additional grant, even if the run fabricates cache metadata.

func ShouldCleanup 

func ShouldCleanup(lease *agentcore.WorkspaceLease, terminal bool) bool

func ToolStateRoot added in v0.11.2 

func ToolStateRoot(workspaceRoot string) (path string, ephemeral bool, err error)

ToolStateRoot returns the run-local directory used for regenerable toolchain state. Without an operator-configured ephemeral root it preserves the legacy workspace-local layout.

func UpdateRepositoryLeaseBranch added in v0.11.2 

func UpdateRepositoryLeaseBranch(lease *agentcore.WorkspaceLease, branch string) error

UpdateRepositoryLeaseBranch records a successful create_branch operation in every field used to validate the retained checkout on a later activity.

func UpdateRepositoryLeaseDetachedHead added in v0.11.2 

func UpdateRepositoryLeaseDetachedHead(lease *agentcore.WorkspaceLease, commit string) error

UpdateRepositoryLeaseDetachedHead records an intentional detached checkout without moving HEAD or reconstructing the prior branch on the next activity.

func ValidateToolCacheConfig added in v0.13.0 

func ValidateToolCacheConfig() error

ValidateToolCacheConfig rejects typos instead of silently disabling cache reuse. Cache lifetime depends on the selected storage, not just the mode name.

func ValidateWorkspaceStorage added in v0.13.0 

func ValidateWorkspaceStorage() error

func WithSession added in v0.13.0 

func WithSession(ctx context.Context, session string) context.Context

WithSession is only supplied by session-bound durable activities, never by caller metadata. A new session gets a distinct directory even on the same pod.

func WorkspaceMode 

func WorkspaceMode(agent *agentcore.Agent) string

func WorkspaceRoot added in v0.11.2 

func WorkspaceRoot() string

WorkspaceRoot returns the directory holding execution workspaces on this worker's writable volume.

Types

type CleanupRequest 

type CleanupRequest = sdk.CleanupWorkspaceRequest

type FinalizeRequest 

type FinalizeRequest = sdk.FinalizeWorkspaceRequest

type FinalizeResult 

type FinalizeResult = sdk.FinalizeWorkspaceResult

type GitIdentity 

type GitIdentity = sdk.GitIdentity

type HTTPProvider 

type HTTPProvider struct {
	BaseURL string
	Token   string
	Client  *http.Client
}

func (HTTPProvider) CleanupWorkspace 

func (p HTTPProvider) CleanupWorkspace(ctx context.Context, req CleanupRequest) error

func (HTTPProvider) FinalizeWorkspace 

func (p HTTPProvider) FinalizeWorkspace(ctx context.Context, req FinalizeRequest) (*FinalizeResult, error)

func (HTTPProvider) PrepareWorkspace 

func (p HTTPProvider) PrepareWorkspace(ctx context.Context, req PrepareRequest) (*agentcore.WorkspaceLease, error)

func (HTTPProvider) ResolveRepositoryWorkspace 

func (p HTTPProvider) ResolveRepositoryWorkspace(ctx context.Context, req PrepareRequest) (*RepositoryWorkspaceSpec, error)

type LeaseValidator 

type LeaseValidator interface {
	ValidateWorkspace(ctx context.Context, req PrepareRequest, lease agentcore.WorkspaceLease) (*agentcore.WorkspaceLease, bool, error)
}

type PrepareRequest 

type PrepareRequest = sdk.PrepareWorkspaceRequest

type Provider 

type Provider interface {
	PrepareWorkspace(ctx context.Context, req PrepareRequest) (*agentcore.WorkspaceLease, error)
	FinalizeWorkspace(ctx context.Context, req FinalizeRequest) (*FinalizeResult, error)
	CleanupWorkspace(ctx context.Context, req CleanupRequest) error
}

type Registry 

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

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Provider 

func (r *Registry) Provider(appID string) (Provider, bool)

func (*Registry) Register 

func (r *Registry) Register(appID string, provider Provider) error

type RepositoryAuth 

type RepositoryAuth = sdk.RepositoryAuth

type RepositoryProvider 

type RepositoryProvider struct {
	RootDir      string
	SpecProvider RepositorySpecProvider
}

func (RepositoryProvider) CleanupWorkspace 

func (p RepositoryProvider) CleanupWorkspace(ctx context.Context, req CleanupRequest) error

func (RepositoryProvider) FinalizeWorkspace 

func (p RepositoryProvider) FinalizeWorkspace(ctx context.Context, req FinalizeRequest) (*FinalizeResult, error)

func (RepositoryProvider) PrepareWorkspace 

func (p RepositoryProvider) PrepareWorkspace(ctx context.Context, req PrepareRequest) (*agentcore.WorkspaceLease, error)

func (RepositoryProvider) PushWorkspace added in v0.11.2 

func (p RepositoryProvider) PushWorkspace(ctx context.Context, req PrepareRequest, root, message string) (json.RawMessage, error)

PushWorkspace refreshes host-owned credentials for a directly authorized push.

func (RepositoryProvider) ValidateWorkspace 

func (p RepositoryProvider) ValidateWorkspace(ctx context.Context, req PrepareRequest, lease agentcore.WorkspaceLease) (*agentcore.WorkspaceLease, bool, error)

type RepositorySpecProvider 

type RepositorySpecProvider interface {
	ResolveRepositoryWorkspace(ctx context.Context, req PrepareRequest) (*RepositoryWorkspaceSpec, error)
}

type RepositoryWorkspaceSpec 

type RepositoryWorkspaceSpec = sdk.RepositoryWorkspaceSpec

func RepositorySpecFromLease 

func RepositorySpecFromLease(lease agentcore.WorkspaceLease) *RepositoryWorkspaceSpec

type ToolCacheRoot added in v0.13.0 

type ToolCacheRoot struct {
	*os.Root
	// contains filtered or unexported fields
}

ToolCacheRoot keeps the absolute tool-facing path alongside the confined filesystem handle. Go 1.25's Root.OpenRoot reports only the relative child name, so Root.Name must not be used to construct command environment paths.

func OpenPrivateToolCacheRoot added in v0.13.0 

func OpenPrivateToolCacheRoot(workspaceRoot string) (cache *ToolCacheRoot, persistent bool, err error)

OpenPrivateToolCacheRoot retains mutable environments within one run even when download/build caches are shared across runs. It never grants cross-run access.

func OpenToolCacheRoot added in v0.13.0 

func OpenToolCacheRoot(workspaceRoot string) (cache *ToolCacheRoot, persistent bool, err error)

OpenToolCacheRoot selects an authorized cross-run repository cache when bound, otherwise private workspace/ephemeral state. Shared callers must hold an AcquireRepositoryCache lease through use, including command execution. Create descendants through Root to reject symlink escapes.

func (*ToolCacheRoot) Name added in v0.13.0 

func (r *ToolCacheRoot) Name() string

Name returns the absolute cache path, independent of the Go toolchain.

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.