Pixir.Subagents.WorkspaceSnapshot (pixir v0.1.8)

Copy Markdown View Source

BEAM-local physical workspace snapshots for isolated Subagents.

This module is the snapshot half of ADR 0011's isolated child workspace contract. It deliberately walks and copies with Elixir filesystem APIs instead of shelling out to git, find, or another host process. That keeps Subagent fanout aligned with ADR 0027: BEAM coordination can scale broadly, while host-boundary crossings stay scarce and explicit.

The first policy is intentionally conservative. It skips common dependency, build, cache, and Pixir runtime-state directories by basename at any depth, enforces copy limits, and returns string-keyed metadata/errors suitable for Tool results and Events.

The exclusion denylist is a policy carried in copier state: the built-in defaults are always in effect, and callers may only extend them, never remove them, via config :pixir, :subagents, snapshot_excluded_dir_names: [...] or the :excluded_dir_names copy option (project-specific bulk like a benchmark outputs/ directory is the motivating case, #221). Names are directory basenames matched byte-exactly at any depth: a regular file with an excluded name is still copied, and on case-insensitive or normalization-insensitive filesystems a case or Unicode variant of an excluded name is not matched (the failure mode is copying more, never escaping the workspace). The effective list is confessed in the snapshot metadata; when policy validation itself fails, no effective list is claimed. Symlinks are lstat-skipped before the policy is consulted, so custom exclusions never introduce traversal that follows them.

Summary

Functions

Copy a bounded, policy-filtered snapshot from src into existing directory dest.

Functions

copy(src, dest, opts \\ [])

Copy a bounded, policy-filtered snapshot from src into existing directory dest.

Returns {:ok, metadata} when copying succeeds, or {:error, details} where details is a string-keyed map ready to embed inside a structured Tool error.