agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/artifact/artifacts/skill.py

@@ -0,0 +1,206 @@
+"""SkillArtifact — Agent Skills (agentskills.io) as first-class artifacts.
+
+A SkillArtifact references one FileArtifactUniverse bundling every file in the skill
+(SKILL.md + scripts/, references/, assets/, …) colocated under a single object-store prefix
+(`artifacts/skill/<key_segment(id)>/<version>/`). That prefix IS the bundle — no duplication, and
+the prefix is handed to deployed A2A agents as `skill_s3_url`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterator, Literal, Optional
+
+import yaml
+from pydantic import Field
+
+from agent_env.artifact.artifact import Artifact
+from agent_env.config import get_config
+from agent_env.store.base import ObjectNotFoundError
+from agent_env.store.ids import derive_id, key_segment
+
+if TYPE_CHECKING:
+    from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+
+
+AGENT_SKILLS_SPEC_VERSION = "0.1"
+
+_SKILL_NAME_RE = re.compile(r"^(?!-)(?!.*--)[a-z0-9-]{1,64}(?<!-)$")
+_SKILL_MD_FILENAME = "SKILL.md"
+_MAX_DESCRIPTION_LEN = 1024
+_MAX_COMPATIBILITY_LEN = 500
+
+
+class SkillArtifact(Artifact):
+    type: Literal["skill"] = "skill"
+
+    skill_files_id: str = Field(description="ID of the FileArtifactUniverse bundling every file in the skill")
+    skill_object_url: str = Field(alias="skill_s3_url", description="Object-store prefix where the skill bundle lives (handed to agents)")
+    agent_skills_spec_version: str = Field(description="agentskills.io spec revision this skill was validated under")
+
+    skill_name: str = Field(description="Skill name from SKILL.md frontmatter; equals the artifact id")
+    description: str = Field(description="Skill description from SKILL.md frontmatter")
+    license: Optional[str] = Field(default=None)
+    compatibility: Optional[str] = Field(default=None)
+    allowed_tools: Optional[str] = Field(default=None)
+    skill_metadata: Optional[dict[str, str]] = Field(default=None)
+
+    @classmethod
+    def validate(
+        cls,
+        *,
+        skill_md: Optional[bytes] = None,
+        s3_url: Optional[str] = None,
+        expected_name: str,
+    ) -> None:
+        if (skill_md is None) == (s3_url is None):
+            raise ValueError("specify exactly one of skill_md or s3_url")
+        if s3_url is not None:
+            skill_md = _fetch_skill_md(s3_url)
+        frontmatter, _body = _parse_skill_md(skill_md)
+        _validate_frontmatter(frontmatter, expected_name=expected_name)
+
+    @classmethod
+    def put(cls, id: str, *, skill_dir: Path) -> "SkillArtifact":
+        from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+        from agent_env.artifact.store import get_artifact_store
+
+        skill_md_path = skill_dir / _SKILL_MD_FILENAME
+        if not skill_md_path.is_file():
+            raise ValueError(f"{_SKILL_MD_FILENAME} not found at {skill_md_path}")
+
+        skill_md_bytes = skill_md_path.read_bytes()
+        cls.validate(skill_md=skill_md_bytes, expected_name=id)
+        frontmatter, _body = _parse_skill_md(skill_md_bytes)
+
+        files: dict[str, Path] = {}
+        for p in sorted(skill_dir.rglob("*")):
+            if p.is_file():
+                files[p.relative_to(skill_dir).as_posix()] = p
+
+        store = get_artifact_store()
+        version = store.next_version(id)
+        key = f"{get_config().get_artifact_key_prefix()}artifacts/skill/{key_segment(id)}/{version}/"
+        skill_s3_url = get_config().get_object_store_for(id).object_url(key)
+
+        universe = FileArtifactUniverse.put_bundled(
+            id=derive_id(id, "files"),
+            files=files,
+            s3_url=skill_s3_url,
+        )
+
+        instance = cls(
+            id=id,
+            version=version,
+            skill_files_id=universe.id,
+            skill_s3_url=skill_s3_url,
+            agent_skills_spec_version=AGENT_SKILLS_SPEC_VERSION,
+            skill_name=frontmatter["name"],
+            description=frontmatter["description"],
+            license=frontmatter.get("license"),
+            compatibility=frontmatter.get("compatibility"),
+            allowed_tools=frontmatter.get("allowed-tools"),
+            skill_metadata=frontmatter.get("metadata"),
+        )
+        return store.put_document(instance)
+
+    def get_skill_files(self) -> "FileArtifactUniverse":
+        from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+        return FileArtifactUniverse.get(self.skill_files_id)
+
+
+def _parse_skill_md(data: bytes) -> tuple[dict, str]:
+    text = data.decode("utf-8")
+    if not text.startswith("---"):
+        raise ValueError("SKILL.md must begin with a YAML frontmatter block delimited by '---'")
+    after_open = text[3:]
+    if after_open.startswith("\n"):
+        after_open = after_open[1:]
+    end_match = re.search(r"^---\s*$", after_open, flags=re.MULTILINE)
+    if end_match is None:
+        raise ValueError("SKILL.md frontmatter is not closed with '---'")
+    frontmatter_text = after_open[: end_match.start()]
+    body = after_open[end_match.end():].lstrip("\n")
+    parsed = yaml.safe_load(frontmatter_text) or {}
+    if not isinstance(parsed, dict):
+        raise ValueError("SKILL.md frontmatter must be a YAML mapping")
+    return parsed, body
+
+
+def _validate_frontmatter(fm: dict, expected_name: str) -> None:
+    name = fm.get("name")
+    if not isinstance(name, str) or not name:
+        raise ValueError("SKILL.md frontmatter 'name' is required and must be a non-empty string")
+    if not _SKILL_NAME_RE.match(name):
+        raise ValueError(
+            f"SKILL.md frontmatter 'name' {name!r} does not match the spec: 1-64 chars, lowercase "
+            "alphanumerics and hyphens only, no leading/trailing or consecutive hyphens"
+        )
+    if name != expected_name:
+        raise ValueError(
+            f"SKILL.md frontmatter 'name' {name!r} must equal the SkillArtifact id {expected_name!r}"
+        )
+
+    description = fm.get("description")
+    if not isinstance(description, str) or not description:
+        raise ValueError("SKILL.md frontmatter 'description' is required and must be a non-empty string")
+    if len(description) > _MAX_DESCRIPTION_LEN:
+        raise ValueError(
+            f"SKILL.md frontmatter 'description' is {len(description)} chars; max {_MAX_DESCRIPTION_LEN}"
+        )
+
+    compatibility = fm.get("compatibility")
+    if compatibility is not None:
+        if not isinstance(compatibility, str) or not compatibility:
+            raise ValueError("SKILL.md frontmatter 'compatibility' must be a non-empty string if present")
+        if len(compatibility) > _MAX_COMPATIBILITY_LEN:
+            raise ValueError(
+                f"SKILL.md frontmatter 'compatibility' is {len(compatibility)} chars; max {_MAX_COMPATIBILITY_LEN}"
+            )
+
+    license_ = fm.get("license")
+    if license_ is not None and (not isinstance(license_, str) or not license_):
+        raise ValueError("SKILL.md frontmatter 'license' must be a non-empty string if present")
+
+    allowed_tools = fm.get("allowed-tools")
+    if allowed_tools is not None and (not isinstance(allowed_tools, str) or not allowed_tools):
+        raise ValueError("SKILL.md frontmatter 'allowed-tools' must be a non-empty string if present")
+
+    metadata = fm.get("metadata")
+    if metadata is not None:
+        if not isinstance(metadata, dict):
+            raise ValueError("SKILL.md frontmatter 'metadata' must be a mapping if present")
+        for k, v in metadata.items():
+            if not isinstance(k, str) or not isinstance(v, str):
+                raise ValueError("SKILL.md frontmatter 'metadata' must map strings to strings")
+
+
+def _fetch_skill_md(object_url: str) -> bytes:
+    prefix = object_url if object_url.endswith("/") else object_url + "/"
+    skill_md_url = prefix + _SKILL_MD_FILENAME
+    try:
+        return get_config().get_object_store_at(skill_md_url).get(skill_md_url)
+    except ObjectNotFoundError as e:
+        raise ValueError(f"{_SKILL_MD_FILENAME} not found at {object_url}") from e
+
+
+@contextlib.contextmanager
+def download_skill(object_url: str) -> Iterator[Path]:
+    """Download an object-store prefix into a local tempdir; yields the dir, cleans up on exit."""
+    store = get_config().get_object_store_at(object_url)
+    prefix = object_url if object_url.endswith("/") else object_url + "/"
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        count = 0
+        for obj_url in store.list_at(prefix):
+            rel = obj_url[len(prefix):]
+            if not rel or obj_url.endswith("/"):
+                continue
+            store.download_to_file(obj_url, str(tmp_path / rel))
+            count += 1
+        if count == 0:
+            raise ValueError(f"No objects found under {object_url}")
+        yield tmp_path

agent_env/artifact/artifacts/vm_image.py

@@ -0,0 +1,95 @@
+"""VM image artifact for referencing pre-built VM images."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import Field, model_validator
+
+from agent_env.artifact.artifact import Artifact
+
+
+class VMImageArtifact(Artifact):
+    """A VM image artifact that references a pre-built VM image.
+
+    Supports ECR containerdisk images (Ubuntu/Windows) and non-ECR images
+    (e.g. macOS). At least one of ecr_url or image_name
+    must be provided.
+
+    Unlike DockerImageArtifact, this does not upload anything to S3.
+
+    Examples:
+        # ECR-based (Ubuntu/Windows)
+        VMImageArtifact.put(id="ubuntu-vm", description="...", ecr_url="<account>.dkr.ecr.<region>.amazonaws.com/ubuntu-vm:1.0.4")
+
+        # Non-ECR (macOS)
+        VMImageArtifact.put(id="macos-vm", description="...", image_name="macos-base", os="macos")
+    """
+
+    type: Literal["vm_image"] = "vm_image"
+    description: str = Field(description="Human-readable description of the VM image")
+    ecr_url: Optional[str] = Field(default=None, description="Full ECR URL for the containerdisk image")
+    image_name: Optional[str] = Field(default=None, description="Image name for non-ECR registries")
+    os: Optional[str] = Field(default=None, description="OS identifier (e.g. 'macos') — only needed when the sandbox API requires it")
+    disk_size_gb: Optional[float] = Field(
+        default=None,
+        description=(
+            "Root disk size in GiB for this VM image. MUST be >= the disk size the image was "
+            "baked with; if it is smaller the guest cannot find its root filesystem and drops "
+            "to the initramfs shell (\"Gave up waiting for root file system device\" / "
+            "\"ALERT! UUID=... does not exist\"). Keep this in sync with the image build. "
+            "None -> falls back to the deploying env's default."
+        ),
+    )
+    cpu: Optional[float] = Field(default=None, description="vCPU count for the VM; None -> falls back to the deploying env's default")
+    memory_mb: Optional[int] = Field(default=None, description="Memory in MiB for the VM; None -> falls back to the deploying env's default")
+    sandbox_type: Optional[str] = Field(
+        default=None,
+        description=(
+            "Sandbox backend this image deploys to (e.g. 'modal_vm', or a name from [sandbox.providers])"
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_image_source(self):
+        if not self.ecr_url and not self.image_name:
+            raise ValueError("At least one of ecr_url or image_name must be provided")
+        return self
+
+    @property
+    def image(self) -> str:
+        """Return the image reference (ECR URL or image name)."""
+        return self.ecr_url or self.image_name
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        description: str,
+        ecr_url: Optional[str] = None,
+        image_name: Optional[str] = None,
+        os: Optional[str] = None,
+        disk_size_gb: Optional[float] = None,
+        cpu: Optional[float] = None,
+        memory_mb: Optional[int] = None,
+        sandbox_type: Optional[str] = None,
+    ) -> "VMImageArtifact":
+        from agent_env.artifact.store import get_artifact_store
+
+        store = get_artifact_store()
+        version = store.next_version(id)
+
+        instance = cls(
+            id=id,
+            version=version,
+            description=description,
+            ecr_url=ecr_url,
+            image_name=image_name,
+            os=os,
+            disk_size_gb=disk_size_gb,
+            cpu=cpu,
+            memory_mb=memory_mb,
+            sandbox_type=sandbox_type,
+        )
+        return store.put_document(instance)

agent_env/artifact/ref.py

@@ -0,0 +1,15 @@
+"""ArtifactRef — a pinned reference to a specific (id, version) of an artifact."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ArtifactRef(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1, description="Artifact id")
+    version: int = Field(ge=1, description="Pinned artifact version")
+
+    def __str__(self) -> str:
+        return f"{self.id}:{self.version}"

agent_env/artifact/registry.py

@@ -0,0 +1,251 @@
+"""Artifact registry for AgentEnv.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from pydantic import TypeAdapter, ValidationError
+
+from agent_env.plugins import _registration, _report
+from agent_env.artifact.artifact import Artifact
+from agent_env.artifact.artifacts.cli import CliArtifact
+from agent_env.artifact.artifacts.docker_image import DockerImageArtifact
+from agent_env.artifact.artifacts.file import FileArtifact
+from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+from agent_env.artifact.artifacts.environment import EnvironmentArtifact
+from agent_env.artifact.artifacts.environment_universe import EnvironmentUniverseArtifact
+from agent_env.artifact.artifacts.skill import SkillArtifact
+from agent_env.artifact.artifacts.vm_image import VMImageArtifact
+
+if TYPE_CHECKING:
+    from agent_env.config.runtime import Config
+
+logger = logging.getLogger(__name__)
+
+
+def _get_type(cls: type[Artifact]) -> Any:
+    return cls.model_fields["type"].default
+
+
+ARTIFACT_REGISTRY: dict[str, type[Artifact]] = {
+    _get_type(CliArtifact): CliArtifact,
+    _get_type(FileArtifact): FileArtifact,
+    _get_type(FileArtifactUniverse): FileArtifactUniverse,
+    _get_type(DockerImageArtifact): DockerImageArtifact,
+    _get_type(EnvironmentArtifact): EnvironmentArtifact,
+    _get_type(EnvironmentUniverseArtifact): EnvironmentUniverseArtifact,
+    _get_type(SkillArtifact): SkillArtifact,
+    _get_type(VMImageArtifact): VMImageArtifact,
+}
+
+
+
+
+def _build_registry(source: Config | None = None) -> dict[str, type[Artifact]]:
+    """The built-in artifact types, then ``agent_env.artifacts`` plugins, then ``[artifacts] impls``
+    in ``source``."""
+    registry = dict(ARTIFACT_REGISTRY)
+    from_plugins = _registration.merge(registry, _registration.ARTIFACTS, _validate_plugin, source=source)
+    _merge_config_toml_artifacts(registry, source=source, from_plugins=from_plugins)
+    # After config, which may have replaced a class's own spelling and stranded its extra names.
+    for name in from_plugins:
+        if reason := _extra_name_problem(name, registry[name], registry, from_plugins.conflicts):
+            from_plugins.reject(name, _report.INVALID_PLUGIN, reason)
+    # This document's aliases, not the ambient Config's, or the two can disagree.
+    _check_type_aliases(registry, _load_type_aliases(source), from_plugins=from_plugins)
+    return registry
+
+
+def _extra_name_problem(
+    name: str, cls: type[Artifact], registry: dict[str, type[Artifact]],
+    conflicts: Mapping[str, tuple[Any, ...]] | None = None,
+) -> str | None:
+    """Why a plugin's extra name (a legacy spelling) for ``cls`` would read nothing, if it would.
+
+    It only reads old documents: the class writes its own spelling, which must resolve to it,
+    and a stored document validates against the class's ``type`` field, which must accept it.
+    """
+    own = _get_type(cls)
+    if name == own:
+        return None
+    builtin = ARTIFACT_REGISTRY.get(own)
+    if builtin is not None and builtin is not cls:
+        return f"its class inherits the built-in type {own!r}; give it its own 'type' field default"
+    if conflicts and own in conflicts:
+        claimants = list(conflicts[own])
+        return f"its class writes type {own!r}, which is left out: {_registration.conflict_message(own, _registration.ARTIFACTS, claimants)}"
+    if registry.get(own) is not cls:
+        elsewhere = registry.get(own)
+        where = "nothing registers it" if elsewhere is None else f"it resolves to {elsewhere.__qualname__}"
+        return f"its class writes type {own!r}, but {where}; register that name to the class too"
+    try:
+        TypeAdapter(cls.model_fields["type"].annotation).validate_python(name)
+    except ValidationError:
+        return f"its 'type' field does not accept {name!r}, so no document stored under it can be read"
+    return None
+
+
+def _validate_plugin(name: str, loaded: Any) -> type[Artifact]:
+    # One class may register under several names; _extra_name_problem checks the extra ones.
+    cls = _registration.require_subclass(loaded, Artifact)
+    if not isinstance(_get_type(cls), str):
+        raise TypeError(f"{cls.__qualname__} does not define its own 'type' field default")
+    if problem := _registration.unimplemented(cls, Artifact):
+        raise TypeError(problem)
+    return cls
+
+
+def get_artifact_registry() -> dict[str, type[Artifact]]:
+    from agent_env.config import runtime
+
+    return runtime.get_config().artifact_registry()
+
+
+def get_type_aliases() -> dict[str, str]:
+    """Legacy artifact `type` spellings mapped to the canonical one, from config.
+
+    Empty unless `[artifacts] type_aliases` declares any, and the core ships none: a
+    deployment that renamed an artifact type keeps reading the documents it already
+    wrote under the old spelling, without ever rewriting them. An installation that
+    never renamed a type has nothing to declare.
+
+    Registering a subclass under the old spelling expresses the same intent and stays
+    supported; the two are alternatives rather than layers, so declaring both for one
+    type is rejected.
+    """
+    from agent_env.config import runtime
+
+    return runtime.get_config().artifact_type_aliases()
+
+
+def canonical_type(stored_type: str) -> str:
+    """The registry key `stored_type` resolves to — itself unless it is an alias."""
+    return get_type_aliases().get(stored_type, stored_type)
+
+
+def equivalent_types(artifact_type: str) -> list[str]:
+    """Every stored spelling that resolves to the same artifact as `artifact_type`.
+
+    A `type` filter is evaluated server-side against the value as stored, so it has to
+    match documents written under either spelling — canonicalising on read happens far
+    too late to help it. Returns `[artifact_type]` unchanged when nothing aliases to it,
+    so an unaliased type still compiles to a scalar equality rather than a one-element
+    `$in`. The order is unspecified — `canonical_type` gives the representative spelling.
+    """
+    aliases = get_type_aliases()
+    canonical = aliases.get(artifact_type, artifact_type)
+    return sorted({artifact_type, canonical} | {a for a, c in aliases.items() if c == canonical})
+
+
+def _load_type_aliases(source: Config | None = None) -> dict[str, str]:
+    from agent_env.config import runtime
+    from agent_env.config import ConfigError
+
+    # A nested walk, so a mis-shaped table raises the config layer's own message rather
+    # than a second hand-rolled one.
+    aliases = (source or runtime.get_config()).section("artifacts", "type_aliases")
+    for legacy, canonical in aliases.items():
+        if not isinstance(canonical, str):
+            raise ConfigError(
+                f"[artifacts] type_aliases {legacy!r} must map to a string, got "
+                f"{type(canonical).__name__}: {canonical!r}"
+            )
+        if canonical == legacy:
+            raise ConfigError(f"[artifacts] type_aliases {legacy!r} maps to itself")
+        if canonical in aliases:
+            raise ConfigError(
+                f"[artifacts] type_aliases {legacy!r} maps to {canonical!r}, which is itself "
+                f"an alias; chains are not resolved"
+            )
+    return dict(aliases)
+
+
+def _check_type_aliases(
+    registry: dict[str, type[Artifact]],
+    aliases: dict[str, str],
+    *,
+    from_plugins: _registration.Registrations | None = None,
+) -> None:
+    from agent_env.config import ConfigError
+
+    from_plugins = from_plugins if from_plugins is not None else _registration.Registrations.empty()
+    for legacy, canonical in aliases.items():
+        if canonical not in registry:
+            if from_plugins.refuse(canonical, f"[artifacts] type_aliases {legacy!r}"):
+                continue
+            if from_plugins.failed(canonical):
+                # Like a config-only provider table for a failed plugin: skipped, not fatal, so
+                # one broken plugin does not take every artifact read down with it.
+                logger.warning(
+                    "[artifacts] type_aliases %r maps to %r, whose plugin failed to load; skipped", legacy, canonical
+                )
+                continue
+            raise ConfigError(
+                f"[artifacts] type_aliases {legacy!r} maps to {canonical!r}, which no artifact "
+                f"registers; declare it under [artifacts].impls or correct the alias"
+            )
+        # Aliasing a type that is still registered is normal mid-rename, as long as both
+        # spellings mean the same class. Pointing it at a different class instead silently
+        # redirects every document that type owns.
+        if legacy in from_plugins.conflicts:
+            claimants = "; ".join(str(p) for p in from_plugins.conflicts[legacy])
+            raise ConfigError(
+                f"[artifacts] type_aliases {legacy!r} maps to {canonical!r}, but plugins {claimants} "
+                f"register {legacy!r}; uninstall them or drop the alias"
+            )
+        owner = registry.get(legacy)
+        if owner is not None and owner is not registry[canonical]:
+            if (plugin := from_plugins.plugin(legacy)) is not None:
+                raise ConfigError(
+                    f"[artifacts] type_aliases {legacy!r} maps to {canonical!r}, but plugin {plugin} "
+                    f"registers {legacy!r} to {owner.__name__}; uninstall the plugin or drop the alias"
+                )
+            raise ConfigError(
+                f"[artifacts] type_aliases {legacy!r} is registered to {owner.__name__} but "
+                f"aliased to {canonical!r} ({registry[canonical].__name__}); a type resolves "
+                f"either through its own registered class or through an alias, not both — "
+                f"drop it from impls, or drop the alias"
+            )
+
+
+def _merge_config_toml_artifacts(
+    registry: dict[str, type[Artifact]],
+    *,
+    source: Config | None = None,
+    from_plugins: _registration.Registrations | None = None,
+) -> None:
+    from agent_env.config import runtime
+    from agent_env.config import ConfigError, load_impl
+
+    section = (source or runtime.get_config()).section("artifacts")
+    impls = section.get("impls", [])
+    if not isinstance(impls, list):
+        raise ConfigError(
+            f"[artifacts] impls must be a list of 'module:Class' strings, got {type(impls).__name__}"
+        )
+    from_plugins = from_plugins if from_plugins is not None else _registration.Registrations.empty()
+    for impl in impls:
+        if not isinstance(impl, str):
+            raise ConfigError(
+                f"[artifacts] impl must be a 'module:Class' string, got {type(impl).__name__}: {impl!r}"
+            )
+        cls = load_impl(impl, Artifact)
+        artifact_type = _get_type(cls)
+        if not isinstance(artifact_type, str):
+            raise ConfigError(
+                f"[artifacts] impl {impl!r} does not define its own 'type' "
+                f"(inherits the base Artifact default); set a concrete 'type' field default"
+            )
+        if problem := _registration.unimplemented(cls, Artifact):
+            raise ConfigError(f"[artifacts] impl {impl!r}: {problem}")
+        if from_plugins.refuse(artifact_type, f"[artifacts] impl {impl!r}"):
+            continue
+        if not from_plugins.release(artifact_type, "artifacts", impl, cls) and artifact_type in registry:
+            raise ConfigError(
+                f"[artifacts] impl {impl!r} type {artifact_type!r} is already registered "
+                f"(conflicts with a built-in or another custom artifact)"
+            )
+        registry[artifact_type] = cls