Documentation
¶
Overview ¶
Package workspace defines workspace domain models, sentinel errors, and resolver contracts used across Compozy runtime packages.
Index ¶
- Constants
- Variables
- func IsWorkspaceID(value string) bool
- func NewWorkspaceID() string
- func NormalizeInvitationScope(scope string, workspaceID string, taskID string) (scopeKind string, scopeID string, err error)
- func UniqueWorkspaceName(rootDir string, taken map[string]struct{}) string
- type AgentDiagnostic
- type ChangeHook
- type ConfigLoader
- type CoordinationCommandStore
- type CoordinationCommands
- type CoordinationEligibility
- type CoordinationInvitation
- type CoordinationInvitations
- type CoordinationRef
- type CoordinationSetting
- type CoordinationSettings
- type CoordinationView
- type EnclosingRootCandidate
- type Identity
- type Option
- func WithCacheTTL(ttl time.Duration) Option
- func WithChangeHook(hook ChangeHook) Option
- func WithConfigLoader(loader ConfigLoader) Option
- func WithHomePaths(homePaths compozyconfig.HomePaths) Option
- func WithIDGenerator(generator func(prefix string) string) Option
- func WithLogger(logger *slog.Logger) Option
- type RegisterOptions
- type ResolvedWorkspace
- type Resolver
- func (r *Resolver) Get(ctx context.Context, idOrNameOrPath string) (Workspace, error)
- func (r *Resolver) Invalidate(workspaceID string)
- func (r *Resolver) InvalidateAll()
- func (r *Resolver) List(ctx context.Context) ([]Workspace, error)
- func (r *Resolver) Register(ctx context.Context, opts RegisterOptions) (Workspace, error)
- func (r *Resolver) Resolve(ctx context.Context, idOrNameOrPath string) (resolved ResolvedWorkspace, err error)
- func (r *Resolver) ResolveOrRegister(ctx context.Context, path string) (ResolvedWorkspace, error)
- func (r *Resolver) SetUnregisterPreparer(preparer UnregisterPreparer)
- func (r *Resolver) Unregister(ctx context.Context, id string) error
- func (r *Resolver) Update(ctx context.Context, id string, opts UpdateOptions) error
- type RuntimeResolver
- type SetCoordination
- type SetInvitation
- type SkillPath
- type Store
- type UnregisterPreparation
- type UnregisterPreparer
- type UpdateOptions
- type Workspace
Constants ¶
const ( InvitationScopeWorkspace = "workspace" InvitationScopeTask = "task" )
Variables ¶
var ( // ErrCoordinationScopeInvalid reports a workspace/task/run ownership mismatch. ErrCoordinationScopeInvalid = errors.New("workspace: network coordination scope invalid") // ErrCoordinationConflict reports a stale expected revision. ErrCoordinationConflict = errors.New("workspace: network coordination revision conflict") )
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 = 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") // ErrWorkspaceHasActiveSessions reports that a workspace cannot be deleted because active sessions are running. ErrWorkspaceHasActiveSessions = errors.New("workspace has active sessions") // ErrWorkspaceIdentityInvalid reports a malformed .compozy/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 ¶
IsWorkspaceID reports whether value is a canonical workspace ULID.
func NewWorkspaceID ¶
func NewWorkspaceID() string
NewWorkspaceID returns a ULID formatted for durable workspace identity.
func NormalizeInvitationScope ¶
func NormalizeInvitationScope( scope string, workspaceID string, taskID string, ) (scopeKind string, scopeID string, err error)
NormalizeInvitationScope validates and returns scope_kind plus durable scope_id.
func UniqueWorkspaceName ¶
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 ¶
AgentDiagnostic reports one workspace-visible AGENT.md file that could not be loaded.
type ChangeHook ¶
ChangeHook runs after persisted workspace mutations that affect resolved runtime state.
type ConfigLoader ¶
type ConfigLoader func(rootDir string) (compozyconfig.Config, error)
ConfigLoader loads the effective configuration for a workspace root.
type CoordinationCommandStore ¶
type CoordinationCommandStore interface {
GetCoordination(ctx context.Context, ref CoordinationRef) (CoordinationView, error)
SetCoordination(
ctx context.Context,
cmd SetCoordination,
actor taskpkg.ActorContext,
) (CoordinationView, error)
SetCoordinationInvitation(
ctx context.Context,
cmd SetInvitation,
actor taskpkg.ActorContext,
) (CoordinationView, error)
}
CoordinationCommandStore persists already-authorized coordination commands atomically.
type CoordinationCommands ¶
type CoordinationCommands interface {
Get(ctx context.Context, ref CoordinationRef, actor taskpkg.ActorContext) (CoordinationView, error)
Set(ctx context.Context, cmd SetCoordination, actor taskpkg.ActorContext) (CoordinationView, error)
SetInvitation(ctx context.Context, cmd SetInvitation, actor taskpkg.ActorContext) (CoordinationView, error)
}
CoordinationCommands owns public coordination reads and atomic mutations.
func NewCoordinationService ¶
func NewCoordinationService(store CoordinationCommandStore) CoordinationCommands
NewCoordinationService builds the application command boundary used by HTTP and UDS.
type CoordinationEligibility ¶
type CoordinationEligibility struct {
Eligible bool
Reason string
RunID string
Coordinator bool
WorkerCount int
}
CoordinationEligibility is daemon-owned invitation eligibility truth.
type CoordinationInvitation ¶
type CoordinationInvitation struct {
WorkspaceID string
ScopeKind string
ScopeID string
Dismissed bool
DismissedAt time.Time
DismissedBy string
}
CoordinationInvitation is one persisted dismissal row. Absent rows mean not dismissed.
type CoordinationInvitations ¶
type CoordinationInvitations interface {
GetInvitation(
ctx context.Context,
workspaceID string,
scopeKind string,
scopeID string,
) (CoordinationInvitation, error)
DismissInvitation(
ctx context.Context,
workspaceID string,
scopeKind string,
scopeID string,
actor string,
) (CoordinationInvitation, error)
ResetInvitation(ctx context.Context, workspaceID string, scopeKind string, scopeID string) error
}
CoordinationInvitations owns daemon-persisted invitation dismissal state.
type CoordinationRef ¶
CoordinationRef identifies one explicit workspace or task coordination scope.
func NormalizeCoordinationRef ¶
func NormalizeCoordinationRef(ref CoordinationRef) (CoordinationRef, error)
NormalizeCoordinationRef validates and canonicalizes one scope reference.
type CoordinationSetting ¶
type CoordinationSetting struct {
WorkspaceID string `json:"workspace_id"`
ScopeKind string `json:"scope_kind"`
ScopeID string `json:"scope_id"`
Enabled bool `json:"enabled"`
Revision int64 `json:"revision"`
UpdatedAt time.Time `json:"updated_at"`
UpdatedBy string `json:"updated_by"`
}
CoordinationSetting is the workspace-scoped, revisioned coordination state.
type CoordinationSettings ¶
type CoordinationSettings interface {
Get(ctx context.Context, workspaceID string) (CoordinationSetting, error)
}
CoordinationSettings owns the persisted workspace opt-in consulted by coordinated execution resolution. Public mutations go through CoordinationCommands so revision, provenance, events, and task intent stay in one command boundary.
type CoordinationView ¶
type CoordinationView struct {
Setting CoordinationSetting
Invitation CoordinationInvitation
Eligibility CoordinationEligibility
}
CoordinationView is one committed coordination setting, invitation, and eligibility projection.
type EnclosingRootCandidate ¶
EnclosingRootCandidate identifies a canonical workspace root for nearest-root selection.
func SelectNearestEnclosingRoot ¶
func SelectNearestEnclosingRoot( canonicalPath string, candidates []EnclosingRootCandidate, ) (EnclosingRootCandidate, bool)
SelectNearestEnclosingRoot returns the deepest enclosing root, breaking ties by ID.
type Identity ¶
type Identity struct {
WorkspaceID string
CreatedAt time.Time
RealpathAtCreation string
Path string
}
Identity is the stable workspace identity stored in <workspace>/.compozy/workspace.toml.
type Option ¶
type Option func(*resolverOptions)
Option customizes a Resolver instance.
func WithCacheTTL ¶
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 compozyconfig.HomePaths) Option
WithHomePaths overrides the global Compozy home layout used for agent and skill discovery.
func WithIDGenerator ¶
WithIDGenerator overrides workspace ID generation.
func WithLogger ¶
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 compozyconfig.Config
Agents []compozyconfig.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 ¶
NewResolver constructs a workspace resolver backed by the supplied store.
func (*Resolver) Get ¶
Get resolves a persisted workspace registration without computing a full snapshot.
func (*Resolver) Invalidate ¶
Invalidate deletes one workspace snapshot from the in-memory cache.
func (*Resolver) InvalidateAll ¶
func (r *Resolver) InvalidateAll()
InvalidateAll clears every cached runtime snapshot after a global dependency changes.
func (*Resolver) Register ¶
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 ¶
ResolveOrRegister resolves an existing workspace by canonical path or auto-registers it.
func (*Resolver) SetUnregisterPreparer ¶
func (r *Resolver) SetUnregisterPreparer(preparer UnregisterPreparer)
SetUnregisterPreparer installs the late-bound runtime owner for workspace state that lives outside the workspace store, such as session directories.
func (*Resolver) Unregister ¶
Unregister removes a persisted workspace registration and its cached snapshot.
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 SetCoordination ¶
type SetCoordination struct {
Ref CoordinationRef
Enabled bool
ExpectedRevision int64
}
SetCoordination is a compare-and-set mutation for one explicit scope.
type SetInvitation ¶
type SetInvitation struct {
Ref CoordinationRef
Dismissed bool
ExpectedRevision int64
}
SetInvitation is a compare-and-set dismissal/reset mutation for one explicit scope.
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 UnregisterPreparation ¶
type UnregisterPreparation interface {
BeforeDelete(ctx context.Context) error
Commit(ctx context.Context) error
Rollback(ctx context.Context) error
}
UnregisterPreparation owns reversible external state around deletion of a workspace row and its database-owned children.
type UnregisterPreparer ¶
type UnregisterPreparer func(ctx context.Context, workspace Workspace) (UnregisterPreparation, error)
UnregisterPreparer stages external state for one workspace deletion.