workspace

package
v0.1.9 Latest Latest
Warning

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

 Go to latest Published: May 27, 2026 License: Apache-2.0 Imports: 16 Imported by: 2

Documentation

Overview

Package workspace defines workspace roots, kinds, and storage abstractions.

It provides root/runtime/state path resolution and common interfaces used by loaders, repositories, and runtime composition.

Index

Constants

View Source 
const (
	KindAgent            = "agents"
	KindModel            = "models"
	KindEmbedder         = "embedders"
	KindMCP              = "mcp"
	KindWorkflow         = "workflows"
	KindSkill            = "skills"
	KindTool             = "tools"
	KindToolBundle       = "tools/bundles"
	KindToolInstructions = "tools/instructions"
	KindTemplate         = "templates"
	KindPrompt           = "prompts"
	KindTemplateBundle   = "templates/bundles"
	KindOAuth            = "oauth"
	KindFeeds            = "feeds"
	KindA2A              = "a2a"
	KindCallback         = "callbacks"

	// DataSources / pickers (extension/forge/*). These kinds extend the
	// forge metadata vocabulary; grouping them under extension/forge/
	// keeps ownership obvious at a glance and leaves headroom for other
	// extension/<tool>/… subtrees in the future.
	KindForgeDataSource = "extension/forge/datasources"
	KindForgeDialog     = "extension/forge/dialogs"
	KindForgeLookup     = "extension/forge/lookups"
	KindForgeWindow     = "extension/forge/windows"
)

Predefined kinds. Callers may still supply arbitrary sub-folder names when they need custom separation.

Variables

This section is empty.

Functions

func AllKinds 

func AllKinds() []string

AllKinds returns all predefined resource kinds.

func EnsureDefault 

func EnsureDefault(fs afs.Service)

EnsureDefault bootstraps minimal workspace defaults.

func EnsureDefaultAt 

func EnsureDefaultAt(ctx context.Context, fs afs.Service, root string)

EnsureDefaultAt ensures workspace root exists with a baseline config file. It intentionally does not seed agent/model catalogs yet.

func IsEmptyWorkspace 

func IsEmptyWorkspace(fs afs.Service) (bool, error)

IsEmptyWorkspace reports whether the active workspace contains no meaningful files. It ignores placeholder .keep files and empty directories.

func IsEmptyWorkspaceAt 

func IsEmptyWorkspaceAt(ctx context.Context, fs afs.Service, root string) (bool, error)

IsEmptyWorkspaceAt reports whether the supplied workspace root contains no meaningful files. It ignores placeholder .keep files and empty directories.

func Path 

func Path(kind string) string

Path returns a sub-path under the root for the given kind (e.g. "agents").

func ResolvePathTemplate 

func ResolvePathTemplate(value string) string

ResolvePathTemplate expands supported macros in a path template. Supported macros: ${workspaceRoot}, ${runtimeRoot}.

func Root 

func Root() string

Root returns the absolute path to the Agently workspace directory. The lookup order is:

  1. Explicit path set via SetRoot (e.g. CLI --workspace flag)
  2. $AGENTLY_WORKSPACE environment variable, if set and non-empty
  3. ./.agently under the current working directory

The result is cached for the lifetime of the process.

func RuntimeRoot 

func RuntimeRoot() string

RuntimeRoot returns the runtime root path. It defaults to the workspace root unless overridden via AGENTLY_RUNTIME_ROOT or SetRuntimeRoot.

func SeedFromFS 

func SeedFromFS(ctx context.Context, afsSvc afs.Service, root string, srcFS iofs.FS, prefix string, vars ...map[string]string) error

SeedFromFS copies files from srcFS/prefix into workspace root when the target file does not already exist. Existing files are never overwritten.

func SetBootstrapAssetsFS added in v0.1.8 

func SetBootstrapAssetsFS(srcFS iofs.FS, prefix string)

SetBootstrapAssetsFS overrides the embedded bootstrap assets source. This keeps bootstrap logic generic while allowing callers to provide their own embedded defaults (agents, wrappers, templates, etc.) without changing core bootstrap code.

func SetBootstrapHook 

func SetBootstrapHook(hook BootstrapHook)

SetBootstrapHook sets a process-wide workspace bootstrap hook. When set, default bootstrapping is skipped and the hook is responsible for creating any required workspace files/directories.

func SetBootstrapTemplateVars added in v0.1.8 

func SetBootstrapTemplateVars(vars map[string]string)

SetBootstrapTemplateVars sets caller-provided template variables that are available to embedded bootstrap assets via `.Vars`.

func SetRoot 

func SetRoot(path string)

SetRoot overrides the workspace root for this process. Call this before any other workspace function (e.g. from CLI --workspace flag parsing). When set it takes precedence over $AGENTLY_WORKSPACE.

func SetRuntimeRoot 

func SetRuntimeRoot(path string)

SetRuntimeRoot overrides the runtime root path for this process.

func SetStateRoot 

func SetStateRoot(path string)

SetStateRoot overrides the state root path for this process.

func StateRoot 

func StateRoot() string

StateRoot returns the state root path. It defaults to RuntimeRoot()/state unless overridden.

Types

type BootstrapHook 

type BootstrapHook func(store *BootstrapStore) error

BootstrapHook customizes workspace bootstrap behavior. It receives a store helper bound to the resolved workspace root.

type BootstrapStore 

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

BootstrapStore provides hook helpers expected by bootstrap callers. It intentionally exposes only operations needed during bootstrap.

func (*BootstrapStore) Root 

func (s *BootstrapStore) Root() string

Root returns the workspace root path used by this bootstrap store.

func (*BootstrapStore) SeedFromFS 

func (s *BootstrapStore) SeedFromFS(ctx context.Context, srcFS iofs.FS, prefix string) error

SeedFromFS copies files from srcFS/prefix into workspace root when missing.

type BootstrapTemplateContext added in v0.1.8 

type BootstrapTemplateContext struct {
	WorkspaceRoot string
	RuntimeRoot   string
	StateRoot     string
	HomeDir       string
	TmpDir        string
	OS            string
	Arch          string
	PathSeparator string
	Vars          map[string]string
}

type Entry 

type Entry struct {
	Kind      string
	Name      string
	Data      []byte
	UpdatedAt time.Time
}

Entry holds metadata about a workspace resource, used by polling watchers.

type KnowledgeStore 

type KnowledgeStore interface {
	// IndexBasePath returns the base path/URI for a user's embedding index.
	IndexBasePath(ctx context.Context, user string) (string, error)

	// SnapshotBasePath returns the base path/URI for MCP snapshot caches.
	SnapshotBasePath(ctx context.Context) (string, error)

	// DBPath returns the application database path.
	DBPath(ctx context.Context) (string, error)
}

KnowledgeStore abstracts paths/URIs for embedding indexes, vector storage, and snapshot caches. FS implementations return local paths; a DB implementation could return dsn:// URIs.

type StateStore 

type StateStore interface {
	// StatePath returns the resolved state directory for a scope
	// (e.g. "mcp/<server>/<user>").
	StatePath(ctx context.Context, scope string) (string, error)

	// StateRoot returns the root state directory.
	StateRoot(ctx context.Context) (string, error)
}

StateStore abstracts per-machine state (auth tokens, cookies, etc.). State is always local and is not shared across machines.

type Store 

type Store interface {
	// Root returns a canonical workspace identifier (FS path, DB URI, etc.).
	Root() string

	// List returns the names of all resources of the given kind.
	List(ctx context.Context, kind string) ([]string, error)

	// Load returns the raw bytes for a single resource.
	Load(ctx context.Context, kind, name string) ([]byte, error)

	// Save creates or overwrites a resource.
	Save(ctx context.Context, kind, name string, data []byte) error

	// Delete removes a resource. It is not an error if the resource does not exist.
	Delete(ctx context.Context, kind, name string) error

	// Exists reports whether a resource exists.
	Exists(ctx context.Context, kind, name string) (bool, error)

	// Entries returns metadata-enriched listings (for polling watchers).
	Entries(ctx context.Context, kind string) ([]Entry, error)
}

Store is the workspace resource persistence abstraction. Implementations may store data on the local filesystem, in a database, or any other backend. Callers handle marshal/unmarshal — the Store works with raw []byte payloads.

Source Files

View all Source files

Directories

Path Synopsis
Package hotswap provides workspace change detection and live reload hooks.
 Package hotswap provides workspace change detection and live reload hooks.
Package loader contains workspace resource loading subpackages.
 Package loader contains workspace resource loading subpackages.
embedder
Package embedder loads embedder provider configurations from workspace resources.
 Package embedder loads embedder provider configurations from workspace resources.
fs
Package fs provides generic filesystem-backed decoding/loading helpers.
 Package fs provides generic filesystem-backed decoding/loading helpers.
model
Package model loads model provider configurations from workspace resources.
 Package model loads model provider configurations from workspace resources.
Package overlay provides in-memory overlay loading on top of workspace files.
 Package overlay provides in-memory overlay loading on top of workspace files.
Package repository contains typed workspace persistence adapters.
 Package repository contains typed workspace persistence adapters.
base
Package base provides common repository helpers over workspace stores.
 Package base provides common repository helpers over workspace stores.
callback
Package callback is the workspace repository for callback definitions.
 Package callback is the workspace repository for callback definitions.
embedder
Package embedder provides workspace repository access for embedder configs.
 Package embedder provides workspace repository access for embedder configs.
forgedatasource
Package forgedatasource loads extension/forge/datasources/*.yaml workspace resources.
 Package forgedatasource loads extension/forge/datasources/*.yaml workspace resources.
forgelookup
Package forgelookup loads extension/forge/lookups/*.yaml overlay files.
 Package forgelookup loads extension/forge/lookups/*.yaml overlay files.
forgewindow
mcp
Package mcp provides workspace repository access for MCP client definitions.
 Package mcp provides workspace repository access for MCP client definitions.
model
Package model provides workspace repository access for model configs.
 Package model provides workspace repository access for model configs.
prompt
skill
template
templatebundle
toolbundle
Package toolbundle provides workspace repository access for tool bundle specs.
 Package toolbundle provides workspace repository access for tool bundle specs.
toolplaybook
Package toolplaybook provides workspace repository access for tool instructions/playbooks.
 Package toolplaybook provides workspace repository access for tool instructions/playbooks.
Package service contains workspace-facing service adapters.
 Package service contains workspace-facing service adapters.
meta
Package meta provides workspace metadata discovery for loaders and handlers.
 Package meta provides workspace metadata discovery for loaders and handlers.
meta/yml
Package yml provides YAML node helpers used by workspace metadata services.
 Package yml provides YAML node helpers used by workspace metadata services.
Package store contains workspace storage backend implementations.
 Package store contains workspace storage backend implementations.
fs
Package fs provides filesystem-backed workspace stores.
 Package fs provides filesystem-backed workspace stores.
Package transfer provides import/export helpers for workspace resources.
 Package transfer provides import/export helpers for workspace resources.

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.