Documentation
¶
Overview ¶
Package workdir manages named per-bot working directories. A workdir is a (workspace target, absolute directory path) pair: the target says which machine the directory lives on (the native container workspace or a user-owned remote runtime), the path says where. Sessions bind to a workdir immutably at creation time and derive their working directory from it for their whole life.
The UI calls these Folders; the domain, API, and database call them workdirs. The name Project is deliberately avoided here — it belongs to the Team-level collaboration container (docs, issues, resources).
Index ¶
- Constants
- Variables
- type CreateRequest
- type DirectoriesResponse
- type Directory
- type GitBranchResponse
- type Resolved
- type Service
- func (s *Service) Archive(ctx context.Context, botID, workdirID string) error
- func (s *Service) Create(ctx context.Context, botID, userID string, req CreateRequest) (Workdir, error)
- func (s *Service) Directories(ctx context.Context, botID, targetID, rawPath string) (DirectoriesResponse, error)
- func (s *Service) Get(ctx context.Context, botID, workdirID string) (Workdir, error)
- func (s *Service) GitBranch(ctx context.Context, botID, workdirID string) (GitBranchResponse, error)
- func (s *Service) List(ctx context.Context, botID string, includeArchived bool) ([]Workdir, error)
- func (s *Service) Rename(ctx context.Context, botID, workdirID, name string) (Workdir, error)
- func (s *Service) RequireActive(ctx context.Context, botID, workdirID string) (Workdir, error)
- func (s *Service) ResolveForSession(ctx context.Context, botID, workdirID string) (Resolved, error)
- func (s *Service) SwitchGitBranch(ctx context.Context, botID, workdirID, branch string) (GitBranchResponse, error)
- type SwitchGitBranchRequest
- type UpdateRequest
- type Workdir
- type WorkdirsResponse
Constants ¶
const ( TargetKindNative = workspace.WorkspaceTargetNative TargetKindRemote = workspace.WorkspaceTargetRemote )
Target kinds. These are the workspace target kinds on purpose: a workdir does not invent its own notion of location.
Variables ¶
var ( ErrWorkdirNotFound = errors.New("workdir not found") ErrWorkdirArchived = errors.New("workdir is archived") ErrNameRequired = errors.New("workdir name is required") ErrPathRequired = errors.New("workdir path is required") ErrInvalidPath = errors.New("invalid workdir path") ErrPathNotFound = errors.New("workdir path does not exist") ErrPathNotDirectory = errors.New("workdir path is not a directory") ErrPathForbidden = errors.New("workdir path is not readable") ErrDuplicatePath = errors.New("a workdir for this directory already exists") ErrGitBusy = errors.New("an agent is using this Git working directory") ErrGitSwitchFailed = errors.New("git branch switch failed") )
Functions ¶
This section is empty.
Types ¶
type CreateRequest ¶
type CreateRequest struct {
Name string `json:"name" validate:"required"`
WorkspaceTargetID string `json:"workspace_target_id,omitempty"`
Path string `json:"path" validate:"required"`
}
CreateRequest creates a workdir. An empty WorkspaceTargetID means the native workspace: workdir targets are explicit on purpose, so they never drift when the bot's primary target changes.
type DirectoriesResponse ¶ added in v0.21.0
type DirectoriesResponse struct {
WorkspaceTargetID string `json:"workspace_target_id"`
Path string `json:"path"`
Directories []Directory `json:"directories"`
}
DirectoriesResponse lists the child directories of Path on one workspace target. Path is the normalized directory that was listed; with an empty request path it is the target's default directory.
type Directory ¶ added in v0.21.0
Directory is one child directory offered while choosing a workdir path. Path is absolute and already joined for the target's OS, so clients never guess the separator.
type GitBranchResponse ¶ added in v0.20.0
type GitBranchResponse struct {
Branch string `json:"branch,omitempty"`
Branches []string `json:"branches"`
Busy bool `json:"busy"`
}
GitBranchResponse contains a branch only when the directory has an attached Git HEAD.
type Resolved ¶
Resolved is the per-session resolution of a workdir binding: which target the session is pinned to and the working directory tools and runtimes use. It reads only stored state — target liveness stays with the turn path.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service owns per-bot working directories.
func NewService ¶
func NewService(store dbstore.BotWorkdirStore, manager *workspace.Manager) *Service
func (*Service) Archive ¶
Archive soft-deletes the workdir. Bound sessions keep their working directory (the row stays); only new bindings are refused from here on.
func (*Service) Create ¶
func (s *Service) Create(ctx context.Context, botID, userID string, req CreateRequest) (Workdir, error)
Create validates the target and directory, then persists the workdir. The directory must already exist on the target: a mistyped path should fail here, at the creation site, not on the first agent turn.
func (*Service) Directories ¶ added in v0.21.0
func (s *Service) Directories(ctx context.Context, botID, targetID, rawPath string) (DirectoriesResponse, error)
Directories lists the child directories of rawPath on a workspace target, so a workdir path can be picked instead of typed. An empty rawPath starts at the target's default directory. It goes through the same target resolution and path normalization as Create, so whatever it offers, Create accepts. Hidden directories are included; hiding them is a presentation choice.
func (*Service) Get ¶
Get returns the workdir regardless of archive state: sessions bound to an archived workdir keep resolving their working directory.
func (*Service) GitBranch ¶ added in v0.20.0
func (s *Service) GitBranch(ctx context.Context, botID, workdirID string) (GitBranchResponse, error)
GitBranch reports the actual working directory, never a per-thread branch.
func (*Service) RequireActive ¶
RequireActive is Get plus an archive check — the gate for binding new sessions to a workdir.
func (*Service) ResolveForSession ¶
ResolveForSession resolves a session's workdir binding to the target it pins and the working directory it dictates. It reads only stored state — no bridge round-trip — so it is safe on the turn hot path. Archived workdirs still resolve: a session's working directory never changes underneath it.
func (*Service) SwitchGitBranch ¶ added in v0.20.0
type SwitchGitBranchRequest ¶ added in v0.20.0
type SwitchGitBranchRequest struct {
Branch string `json:"branch" validate:"required"`
}
type UpdateRequest ¶
type UpdateRequest struct {
Name string `json:"name" validate:"required"`
}
UpdateRequest renames a workdir. The target and path are immutable: they are already baked into the working directory of every session bound to this workdir.
type Workdir ¶
type Workdir struct {
ID string `json:"id"`
BotID string `json:"bot_id"`
Name string `json:"name"`
TargetKind string `json:"target_kind"`
WorkspaceTargetID string `json:"workspace_target_id"`
Path string `json:"path"`
CreatedByUserID string `json:"created_by_user_id,omitempty"`
Archived bool `json:"archived,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
} // @name workdir.Workdir
Workdir is the API shape of a workdir. WorkspaceTargetID is the derived target address: the native sentinel for native workdirs, the remote binding UUID otherwise.
type WorkdirsResponse ¶
type WorkdirsResponse struct {
Workdirs []Workdir `json:"workdirs"`
}
Source Files