workspace

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: May 27, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package workspace defines workspace domain models, sentinel errors, and resolver contracts used across AGH runtime packages.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrWorkspaceNotFound reports that no registered workspace matched the lookup.
	ErrWorkspaceNotFound = errors.New("workspace not found")
	// ErrWorkspaceRootMissing reports that the registered workspace root no longer exists on disk.
	ErrWorkspaceRootMissing = errors.New("workspace root directory no longer exists")
	// ErrAgentNotAvailable reports that the requested agent cannot be resolved in the workspace.
	ErrAgentNotAvailable = errors.New("agent not available in workspace")
	// ErrWorkspaceResolverUnavailable reports that workspace resolution cannot run because its dependency is absent.
	ErrWorkspaceResolverUnavailable = errors.New("workspace resolver unavailable")
	// ErrWorkspaceNameTaken reports that a workspace name is already registered.
	ErrWorkspaceNameTaken = errors.New("workspace name already in use")
	// ErrWorkspacePathTaken reports that a workspace root path is already registered.
	ErrWorkspacePathTaken = errors.New("workspace path already registered")
	// ErrWorkspaceHasSessions reports that a workspace cannot be deleted because sessions still reference it.
	ErrWorkspaceHasSessions = errors.New("workspace has sessions")
	// ErrWorkspaceIdentityInvalid reports a malformed .agh/workspace.toml identity file.
	ErrWorkspaceIdentityInvalid = errors.New("workspace identity invalid")
	// ErrWorkspaceIdentityPermissionDenied reports a fail-closed identity file permission failure.
	ErrWorkspaceIdentityPermissionDenied = errors.New("workspace identity permission denied")
)

Functions

func IsWorkspaceID

func IsWorkspaceID(value string) bool

IsWorkspaceID reports whether value is a canonical workspace ULID.

func NewWorkspaceID

func NewWorkspaceID() string

NewWorkspaceID returns a ULID formatted for durable workspace identity.

func UniqueWorkspaceName

func UniqueWorkspaceName(rootDir string, taken map[string]struct{}) string

UniqueWorkspaceName derives a stable workspace name from the root path and appends numeric suffixes until it no longer collides with the taken set.

Types

type AgentDiagnostic

type AgentDiagnostic struct {
	Name      string
	Path      string
	ErrorKind string
	Message   string
}

AgentDiagnostic reports one workspace-visible AGENT.md file that could not be loaded.

type ChangeHook

type ChangeHook func(context.Context) error

ChangeHook runs after persisted workspace mutations that affect resolved runtime state.

type ConfigLoader

type ConfigLoader func(rootDir string) (aghconfig.Config, error)

ConfigLoader loads the effective configuration for a workspace root.

type Identity

type Identity struct {
	WorkspaceID        string
	CreatedAt          time.Time
	RealpathAtCreation string
	Path               string
}

Identity is the stable workspace identity stored in <workspace>/.agh/workspace.toml.

func EnsureIdentity

func EnsureIdentity(ctx context.Context, rootDir string) (Identity, error)

EnsureIdentity loads or creates <workspace>/.agh/workspace.toml.

type Option

type Option func(*resolverOptions)

Option customizes a Resolver instance.

func WithCacheTTL

func WithCacheTTL(ttl time.Duration) Option

WithCacheTTL overrides the idle cache eviction window.

func WithChangeHook

func WithChangeHook(hook ChangeHook) Option

WithChangeHook installs a post-mutation hook for derived runtime projections.

func WithConfigLoader

func WithConfigLoader(loader ConfigLoader) Option

WithConfigLoader overrides the configuration loader used during workspace resolution.

func WithHomePaths

func WithHomePaths(homePaths aghconfig.HomePaths) Option

WithHomePaths overrides the global AGH home layout used for agent and skill discovery.

func WithIDGenerator

func WithIDGenerator(generator func(prefix string) string) Option

WithIDGenerator overrides workspace ID generation.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger overrides the structured logger used for resolver diagnostics.

type RegisterOptions

type RegisterOptions struct {
	RootDir        string
	Name           string
	AdditionalDirs []string
	DefaultAgent   string
	SandboxRef     string
}

RegisterOptions describes a workspace registration request.

type ResolvedWorkspace

type ResolvedWorkspace struct {
	Workspace
	WorkspaceID      string
	Config           aghconfig.Config
	Agents           []aghconfig.AgentDef
	AgentDiagnostics []AgentDiagnostic
	Skills           []SkillPath
	Sandbox          sandbox.Resolved
	ResolvedAt       time.Time
}

ResolvedWorkspace is the computed workspace snapshot returned by a resolver.

type Resolver

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

Resolver resolves persisted workspaces into runtime workspace snapshots.

func NewResolver

func NewResolver(store Store, opts ...Option) (*Resolver, error)

NewResolver constructs a workspace resolver backed by the supplied store.

func (*Resolver) Get

func (r *Resolver) Get(ctx context.Context, idOrNameOrPath string) (Workspace, error)

Get resolves a persisted workspace registration without computing a full snapshot.

func (*Resolver) Invalidate

func (r *Resolver) Invalidate(workspaceID string)

Invalidate deletes one workspace snapshot from the in-memory cache.

func (*Resolver) List

func (r *Resolver) List(ctx context.Context) ([]Workspace, error)

List returns every registered workspace in stable store order.

func (*Resolver) Register

func (r *Resolver) Register(ctx context.Context, opts RegisterOptions) (Workspace, error)

Register persists a workspace registration hint and eagerly resolves it.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, idOrNameOrPath string) (resolved ResolvedWorkspace, err error)

Resolve loads and caches the effective runtime snapshot for a workspace.

func (*Resolver) ResolveOrRegister

func (r *Resolver) ResolveOrRegister(ctx context.Context, path string) (ResolvedWorkspace, error)

ResolveOrRegister resolves an existing workspace by canonical path or auto-registers it.

func (*Resolver) Unregister

func (r *Resolver) Unregister(ctx context.Context, id string) error

Unregister removes a persisted workspace registration and its cached snapshot.

func (*Resolver) Update

func (r *Resolver) Update(ctx context.Context, id string, opts UpdateOptions) error

Update mutates an existing workspace registration.

type RuntimeResolver

type RuntimeResolver interface {
	Resolve(ctx context.Context, idOrPath string) (ResolvedWorkspace, error)
	ResolveOrRegister(ctx context.Context, path string) (ResolvedWorkspace, error)
}

RuntimeResolver resolves persisted workspaces into computed runtime snapshots.

type SkillPath

type SkillPath struct {
	Dir    string
	Source string
}

SkillPath identifies a discovered skill directory and its origin.

type Store

type Store interface {
	InsertWorkspace(ctx context.Context, ws Workspace) error
	UpdateWorkspace(ctx context.Context, ws Workspace) error
	DeleteWorkspace(ctx context.Context, id string) error
	GetWorkspace(ctx context.Context, id string) (Workspace, error)
	GetWorkspaceByPath(ctx context.Context, rootDir string) (Workspace, error)
	GetWorkspaceByName(ctx context.Context, name string) (Workspace, error)
	ListWorkspaces(ctx context.Context) ([]Workspace, error)
}

Store persists and looks up registered workspaces.

type UpdateOptions

type UpdateOptions struct {
	Name           *string
	AdditionalDirs *[]string
	DefaultAgent   *string
	SandboxRef     *string
}

UpdateOptions describes mutable workspace registration fields.

type Workspace

type Workspace struct {
	ID             string
	RootDir        string
	AdditionalDirs []string
	Name           string
	DefaultAgent   string
	SandboxRef     string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

Workspace is the persisted workspace registration stored in the global database.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL