workspace

package
v0.0.2 Latest Latest
Warning

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

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

Documentation

Overview

Package workspace resolves local programming projects to stable OSS workspace identities. Explicit and deployment-pinned identities take precedence; automatic discovery uses a canonical Git root or directory and persists the assignment under the harness state directory.

Index

Constants

View Source 
const (
	ExecutionViewResourceType  = "workspace-execution/view"
	ExecutionViewBindOperation = "bind"

	ExecutionViewReadAccess  = int32(10)
	ExecutionViewWriteAccess = int32(20)
)
View Source 
const (
	// ViewObservationLeaseDuration is the validity window published by a live
	// tool host. It is intentionally longer than the shared renewal cadence.
	ViewObservationLeaseDuration = 5 * time.Minute
	// ViewObservationRenewInterval is shared by client and worker hosts so both
	// remain discoverable without transport-specific magic numbers.
	ViewObservationRenewInterval = 2 * time.Minute
)
View Source 
const ExecutionViewPolicyMetaKey = "scitrera.execution_view_policy"

Variables

View Source 
var (
	// ErrWorkspaceUnavailable indicates that no explicit, pinned, discovered,
	// or default workspace can be selected.
	ErrWorkspaceUnavailable = errors.New("workspace unavailable")
	// ErrStateDirRequired indicates that automatic project discovery would be
	// unstable because no location was supplied for the durable path index.
	ErrStateDirRequired = errors.New("state directory required for automatic workspace discovery")
)
View Source 
var ErrInvalidIndex = errors.New("invalid workspace index")

ErrInvalidIndex indicates that the persisted workspace index cannot be used safely. Callers should surface the error instead of silently replacing the index and changing existing project identities.

View Source 
var WorkspaceToolCapabilities = []string{
	"command.run",
	"directory.list",
	"file.inspect",
	"file.read",
	"file.write",
	"python.run",
	spec.ToolCancelCapability,
}

WorkspaceToolCapabilities is the deterministic capability set advertised by a Sahara client that hosts the built-in workspace tools.

Functions

func EncodeExecutionViewPolicy 

func EncodeExecutionViewPolicy(policy ExecutionViewPolicy) (json.RawMessage, error)

func ExecutionScopesEqual 

func ExecutionScopesEqual(left, right *ExecutionScope) bool

func ExecutionViewRequiredAccess 

func ExecutionViewRequiredAccess(policy ExecutionViewPolicy) (int32, error)

ExecutionViewRequiredAccess maps Sahara's local write ceiling to Aether's ordinary numeric access level. The operation remains the stable verb "bind"; grants can narrow read/write with their access ceiling.

func ExecutionViewResourceID 

func ExecutionViewResourceID(binding spec.ExecutionBinding) (string, error)

ExecutionViewResourceID returns the canonical Aether identity of one exact MemoryLayer workspace view hosted by one exact execution provider. Local roots and root_ref values are deliberately absent.

func IsMonotonicScopeNarrowing 

func IsMonotonicScopeNarrowing(parent, child *ExecutionScope) bool

IsMonotonicScopeNarrowing permits only an exact scope or a read-write to read-only reduction on the same binding. Every binding change or write-access expansion requires a composition-provided authorizer.

func PathSegment 

func PathSegment(id string) string

PathSegment produces a filesystem-safe, injective segment for ordinary opaque identifiers. Very large IDs use a full digest so the component remains below common filesystem limits.

func PutExecutionScope 

func PutExecutionScope(message *spec.ChatMessage, scope ExecutionScope) error

PutExecutionScope stores the portable binding plus Sahara's private policy extension on a message.

func StateDir 

func StateDir(base, workspaceID string) string

StateDir returns the per-workspace child of base. Empty workspaceID preserves the legacy unscoped directory.

func WithExecutionScope 

func WithExecutionScope(ctx context.Context, scope ExecutionScope) context.Context

Types

type Config 

type Config struct {
	StateDir         string
	PinnedWorkspace  string
	DefaultWorkspace string
	Detector         ProjectDetector
}

Config controls workspace precedence and local project indexing.

type Entry 

type Entry struct {
	WorkspaceID string      `json:"workspace_id"`
	ProjectRoot string      `json:"project_root"`
	Kind        ProjectKind `json:"kind"`
}

Entry is a durable canonical-project-root to workspace-ID assignment.

type ExecutionBindingAuthorizationRequest 

type ExecutionBindingAuthorizationRequest struct {
	Binding     spec.ExecutionBinding
	ViewPolicy  ExecutionViewPolicy
	SourceTopic string
	// RequestUserID is an application-level claim from the message address. It
	// is useful for audit/correlation but MUST NOT be treated as authenticated
	// identity. SourceTopic and OnBehalfOf are transport-authenticated.
	RequestUserID string
	OnBehalfOf    Principal
}

ExecutionBindingAuthorizationRequest gives a durable authority enough trusted transport context to apply same-window, same-user, named-principal, or workspace-member policy. OSS uses the strict same-window policy.

type ExecutionScope 

type ExecutionScope struct {
	Binding spec.ExecutionBinding `json:"binding"`
	Policy  ExecutionViewPolicy   `json:"policy"`
}

ExecutionScope binds filesystem authority and its write ceiling. A binding is a resource selector, not a grant; transport and host authorizers still decide whether the current principal may use it.

func ExecutionScopeFrom 

func ExecutionScopeFrom(ctx context.Context) (ExecutionScope, bool)

func GetExecutionScope 

func GetExecutionScope(message spec.ChatMessage) (*ExecutionScope, error)

GetExecutionScope requires a policy whenever a binding is present. The scope contract is unreleased, so missing authority is rejected rather than mapped through a transitional default.

func NewExecutionScope 

func NewExecutionScope(binding spec.ExecutionBinding, policy ExecutionViewPolicy) (ExecutionScope, error)

func (ExecutionScope) ReadOnly 

func (s ExecutionScope) ReadOnly() ExecutionScope

func (ExecutionScope) Validate 

func (s ExecutionScope) Validate() error

type ExecutionViewPolicy 

type ExecutionViewPolicy struct {
	WriteAccess      ViewWriteAccess `json:"write_access"`
	AllowMutableView bool            `json:"allow_mutable_view,omitempty"`
	AllowDirtyView   bool            `json:"allow_dirty_view,omitempty"`
}

ExecutionViewPolicy is the authority carried with an exact view selector. WriteAccess is always explicit on newly created scopes. The mutable/dirty flags retain the admission constraints used by durable worker views.

func DecodeExecutionViewPolicy 

func DecodeExecutionViewPolicy(data []byte) (ExecutionViewPolicy, error)

func (ExecutionViewPolicy) Validate 

func (p ExecutionViewPolicy) Validate() error

type Principal 

type Principal struct {
	Type string
	ID   string
}

Principal is a transport-authenticated actor or on-behalf-of subject. The empty value means no OBO subject was asserted by the transport.

type Project 

type Project struct {
	Root string
	Git  bool
}

Project is the canonical local root discovered for a programming project.

type ProjectDetector 

type ProjectDetector interface {
	Detect(ctx context.Context, cwd string) (Project, error)
}

ProjectDetector finds the canonical project containing cwd. The default detector prefers a Git worktree root and falls back to the canonical cwd.

type ProjectKind 

type ProjectKind string

ProjectKind describes the local evidence used to identify a project root. It is intentionally local metadata, not part of the ecosystem wire protocol. 

const (
	ProjectKindGit       ProjectKind = "git"
	ProjectKindDirectory ProjectKind = "directory"
)

type Request 

type Request struct {
	WorkspaceID string
	CWD         string
}

Request contains per-attachment workspace inputs. WorkspaceID is an explicit caller selection. CWD enables automatic programming-project discovery.

type Resolution 

type Resolution struct {
	WorkspaceID string
	ProjectRoot string
	Source      Source
	Git         bool
}

Resolution is the selected workspace and its local resolution provenance. ProjectRoot is only populated for automatically discovered workspaces.

type Resolver 

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

Resolver applies deterministic precedence and owns a durable local project index when StateDir is configured.

func NewResolver 

func NewResolver(config Config) (*Resolver, error)

NewResolver constructs a resolver and validates any existing project index.

func (*Resolver) List 

func (r *Resolver) List() []Entry

List returns a workspace-ID-sorted snapshot of automatically indexed local projects. Explicit, pinned, and fallback IDs are not index entries.

func (*Resolver) Resolve 

func (r *Resolver) Resolve(ctx context.Context, request Request) (Resolution, error)

Resolve selects a workspace in this order: explicit request, pinned process configuration, persisted/discovered project, then configured default.

type Source 

type Source string

Source records how a workspace was selected. 

const (
	SourceExplicit  Source = "explicit"
	SourcePinned    Source = "pinned"
	SourceGitRoot   Source = "git_root"
	SourceDirectory Source = "directory"
	SourceDefault   Source = "default"
)

type VCSObservation 

type VCSObservation struct {
	Kind         string
	RepositoryID string
	WorktreeID   string
	HeadRevision string
	Branch       string
	Dirty        bool
	Detached     bool
}

VCSObservation is the portable Git state published for a local view. IDs are hashes of local Git identities; host-local paths never leave this process.

type View 

type View struct {
	Descriptor spec.WorkspaceViewDescriptor
	Root       string
	RootRef    string
	VCS        *VCSObservation
}

View binds one local directory root to a durable logical workspace view. Root is host-private. RootRef is the opaque value peers may echo back only to this exact tool host.

type ViewObservation 

type ViewObservation struct {
	ObserverID    string
	Generation    string
	Sequence      int64
	ToolHostID    string
	ExecutionSite spec.ExecutionSite
	RootRef       string
	Capabilities  []string
	VCS           *VCSObservation
	ExpiresAt     time.Time
}

ViewObservation is the latest host observation published to the durable workspace authority.

type ViewPublisher 

type ViewPublisher interface {
	PublishWorkspaceView(ctx context.Context, view View, observation ViewObservation) error
}

ViewPublisher stores durable view identity and latest observed state. A nil publisher leaves the registry fully useful in standalone OSS mode.

type ViewRegistry 

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

ViewRegistry discovers project roots, assigns logical workspaces, and keeps the host-private mapping needed to execute a logical binding safely.

func NewViewRegistry 

func NewViewRegistry(ctx context.Context, cfg ViewRegistryConfig) (*ViewRegistry, error)

NewViewRegistry creates a registry and publishes its initial view when a publisher is configured.

func (*ViewRegistry) ExecutionBindingForDirectory 

func (r *ViewRegistry) ExecutionBindingForDirectory(ctx context.Context, dir string) (spec.ExecutionBinding, error)

ExecutionBindingForDirectory returns an exact-host logical binding for dir.

func (*ViewRegistry) GrantWorkingDirectory 

func (r *ViewRegistry) GrantWorkingDirectory(dir string) error

GrantWorkingDirectory registers the project/view containing dir. It matches the TUI DirectoryAccess seam.

func (*ViewRegistry) RenewRegisteredViews 

func (r *ViewRegistry) RenewRegisteredViews(ctx context.Context) error

RenewRegisteredViews republishes current observations without changing view identity. Worker processes call it before MemoryLayer's observation lease expires so durable selectors remain live.

func (*ViewRegistry) ResolveBinding 

func (r *ViewRegistry) ResolveBinding(binding spec.ExecutionBinding) (View, error)

ResolveBinding returns the host-private view selected by a validated binding. Every identity component is checked; callers must not fall back on failure.

func (*ViewRegistry) ResolveCurrentBinding 

func (r *ViewRegistry) ResolveCurrentBinding(ctx context.Context, binding spec.ExecutionBinding) (View, error)

ResolveCurrentBinding performs the exact-host identity checks and verifies a pinned VCS revision against the execution host immediately before use. This closes the admission-to-execution gap if another process switches worktrees.

func (*ViewRegistry) ResolveWorkspaceForDirectory 

func (r *ViewRegistry) ResolveWorkspaceForDirectory(ctx context.Context, dir string) (string, error)

ResolveWorkspaceForDirectory returns the logical project identity while retaining distinct registered views for separate worktrees of that project.

func (*ViewRegistry) ScheduledExecutionBindingForDirectory 

func (r *ViewRegistry) ScheduledExecutionBindingForDirectory(
	ctx context.Context,
	dir string,
	allowMutable bool,
	allowDirty bool,
) (spec.ExecutionBinding, error)

ScheduledExecutionBindingForDirectory pins a background turn to the latest observed revision. Mutable directories and dirty worktrees require explicit opt-in because they cannot otherwise be reproduced after a delayed fire.

func (*ViewRegistry) SetPublisher 

func (r *ViewRegistry) SetPublisher(ctx context.Context, publisher ViewPublisher) error

SetPublisher publishes every currently registered view, then installs the publisher for future observations. It supports transports that must connect before their remote MemoryLayer path is usable while still allowing worker assignment handlers to be registered before that connection starts.

func (*ViewRegistry) ValidateScheduledBinding 

func (r *ViewRegistry) ValidateScheduledBinding(
	ctx context.Context,
	binding spec.ExecutionBinding,
	allowMutable bool,
	allowDirty bool,
) error

ValidateScheduledBinding rechecks reproducibility policy immediately before admission or execution. Unlike interactive views, a scheduled clean Git view must stay clean for the full task; dirty or non-VCS views are usable only under the explicit policy captured in the versioned schedule envelope.

type ViewRegistryConfig 

type ViewRegistryConfig struct {
	InitialWorkspaceID string
	InitialRoot        string
	StateDir           string
	ToolHostID         string
	ExecutionSite      spec.ExecutionSite
	Publisher          ViewPublisher
}

ViewRegistryConfig configures a client-local workspace/view registry.

type ViewWriteAccess 

type ViewWriteAccess string
const (
	ViewWriteAccessReadOnly  ViewWriteAccess = "read_only"
	ViewWriteAccessReadWrite ViewWriteAccess = "read_write"
)

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.