agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/artifact/__init__.py

@@ -0,0 +1,48 @@
+"""Artifact module for AgentEnv."""
+
+from agent_env.artifact.artifact import Artifact
+from agent_env.artifact.ref import ArtifactRef
+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 AGENT_SKILLS_SPEC_VERSION, SkillArtifact
+from agent_env.artifact.artifacts.vm_image import VMImageArtifact
+from agent_env.artifact.registry import (
+    ARTIFACT_REGISTRY,
+    canonical_type,
+    equivalent_types,
+    get_artifact_registry,
+    get_type_aliases,
+)
+from agent_env.artifact.store import ArtifactStore, get_artifact_store, reset_artifact_store, set_artifact_store
+from agent_env.artifact.universe import Universe
+
+__all__ = [
+    "Artifact",
+    "ArtifactRef",
+    "CliArtifact",
+    "DockerImageArtifact",
+    "FileArtifact",
+    "FileArtifactUniverse",
+    "EnvironmentArtifact",
+    "EnvironmentUniverseArtifact",
+    # Deprecated aliases. Kept in __all__ so `from agent_env.artifact import *`
+    # still binds them; served by __getattr__ below rather than imported eagerly, so
+    # importing this package does not itself trip the deprecation counter.
+    "SkillArtifact",
+    "AGENT_SKILLS_SPEC_VERSION",
+    "Universe",
+    "VMImageArtifact",
+    "ARTIFACT_REGISTRY",
+    "canonical_type",
+    "equivalent_types",
+    "get_artifact_registry",
+    "get_type_aliases",
+    "ArtifactStore",
+    "get_artifact_store",
+    "reset_artifact_store",
+    "set_artifact_store",
+]

agent_env/artifact/artifact.py

@@ -0,0 +1,74 @@
+"""Artifact models for AgentEnv."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, Self
+
+from pydantic import BaseModel, Field, field_validator
+
+from agent_env.entity_refs import EntityRef
+
+if TYPE_CHECKING:
+    from agent_env.bundle.authoring import AuthoringContext
+    from agent_env.artifact.ref import ArtifactRef
+    from agent_env.artifact.store import ArtifactQuery
+
+
+class Artifact(BaseModel):
+    """Base class for all environment artifacts. Immutable - each modification creates a new version."""
+
+    id: str = Field(description="Unique artifact identifier")
+    version: int = Field(default=0, description="Artifact version (auto-calculated on put)")
+    type: str = Field(description="The type of Artifact")
+
+    toml_refs: ClassVar[tuple[EntityRef, ...]] = ()
+
+    @field_validator("type", mode="before")
+    @classmethod
+    def _canonical_type(cls, value):
+        """Accept a spelling `[artifacts] type_aliases` maps to this type's own."""
+        from agent_env.artifact.registry import canonical_type
+
+        return canonical_type(value) if isinstance(value, str) else value
+
+    def as_ref(self) -> "ArtifactRef":
+        from agent_env.artifact.ref import ArtifactRef
+
+        if self.version < 1:
+            raise ValueError(
+                f"Cannot create a ref for unpersisted artifact {self.id!r} "
+                "(version=0). Call put() first."
+            )
+        return ArtifactRef(id=self.id, version=self.version)
+
+    @classmethod
+    def get(cls, id: str, version: Optional[int] = None) -> Self:
+        """The artifact stored under ``id``, which must be a ``cls``: the store builds the class
+        its stored type names, so ``FileArtifact.get`` refuses an id that holds another type."""
+        from agent_env.artifact.store import get_artifact_store
+
+        artifact = get_artifact_store().get(id, version)
+        if not isinstance(artifact, cls):
+            raise TypeError(f"artifact {id!r} is a {artifact.type!r} artifact, not a {cls.__name__}")
+        return artifact
+
+    @classmethod
+    def put(cls, **kwargs: Any) -> Self:
+        from agent_env.artifact.store import get_artifact_store
+
+        instance = cls(**kwargs)
+        return get_artifact_store().put_document(instance)
+
+    @classmethod
+    def from_toml(cls, data: dict[str, Any], ctx: AuthoringContext) -> Self:
+        """Write the artifact authored as ``data`` (its toml, with the keys ``toml_refs`` declares
+        resolved to ids) under ``ctx.id`` and return it. The default suits a type that is only a
+        document; one whose ``put`` uploads files or images overrides this."""
+        fields = {key: value for key, value in data.items() if key not in ("id", "type", "version")}
+        return cls.put(id=ctx.id, **fields)
+
+    @classmethod
+    def query(cls) -> "ArtifactQuery":
+        from agent_env.artifact.store import ArtifactQuery, get_artifact_store
+
+        return ArtifactQuery(get_artifact_store())

agent_env/artifact/artifacts/cli.py

@@ -0,0 +1,83 @@
+"""CliArtifact — packages a CLI tool (entrypoint + supporting files) as a versioned artifact.
+
+A CliArtifact references one FileArtifactUniverse bundling every file in the CLI
+directory tree, colocated under a single S3 prefix (`artifacts/cli/<key_segment(id)>/<version>/`).
+The `entrypoint` field is a relative path within that prefix that consumers
+(e.g. an agent gateway) chmod +x and symlink onto PATH.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, Optional
+
+from pydantic import Field
+
+from agent_env.artifact.artifact import Artifact
+from agent_env.config import get_config
+from agent_env.store.ids import derive_id, key_segment
+
+if TYPE_CHECKING:
+    from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+
+
+class CliArtifact(Artifact):
+    type: Literal["cli"] = "cli"
+
+    cli_files_id: str = Field(description="ID of the FileArtifactUniverse bundling every file in the CLI tree")
+    cli_object_url: str = Field(alias="cli_s3_url", description="Object-store prefix where the CLI bundle lives")
+    entrypoint: str = Field(description="Relative path within the bundle to the executable file (e.g. 'bin/slack')")
+    command_name: str = Field(description="Command name installed on PATH (e.g. 'slack' -> /usr/local/bin/slack)")
+
+    env_id: Optional[str] = Field(default=None, description="Source env id this CLI was generated from, if any")
+    env_version: Optional[int] = Field(default=None, description="Source env version this CLI was generated from, if any")
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        command_name: str,
+        entrypoint: str,
+        cli_dir: Path,
+        env_id: Optional[str] = None,
+        env_version: Optional[int] = None,
+    ) -> "CliArtifact":
+        from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+        from agent_env.artifact.store import get_artifact_store
+
+        if not cli_dir.is_dir():
+            raise ValueError(f"cli_dir {cli_dir} is not a directory")
+        entrypoint_path = cli_dir / entrypoint
+        if not entrypoint_path.is_file():
+            raise ValueError(f"entrypoint {entrypoint!r} not found at {entrypoint_path}")
+
+        files: dict[str, Path] = {}
+        for p in sorted(cli_dir.rglob("*")):
+            if p.is_file():
+                files[p.relative_to(cli_dir).as_posix()] = p
+        if not files:
+            raise ValueError(f"cli_dir {cli_dir} contains no files")
+
+        store = get_artifact_store()
+        version = store.next_version(id)
+        key = f"{get_config().get_artifact_key_prefix()}artifacts/cli/{key_segment(id)}/{version}/"
+        cli_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=cli_s3_url)
+
+        instance = cls(
+            id=id,
+            version=version,
+            cli_files_id=universe.id,
+            cli_s3_url=cli_s3_url,
+            entrypoint=entrypoint,
+            command_name=command_name,
+            env_id=env_id,
+            env_version=env_version,
+        )
+        return store.put_document(instance)
+
+    def get_cli_files(self) -> "FileArtifactUniverse":
+        from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+        return FileArtifactUniverse.get(self.cli_files_id)

agent_env/artifact/artifacts/docker_image.py

@@ -0,0 +1,457 @@
+"""Docker image artifact for storing Docker images in S3."""
+
+from __future__ import annotations
+
+import asyncio
+import gzip
+import logging
+import os
+import posixpath
+import re
+import shlex
+import subprocess
+import tarfile
+import tempfile
+import uuid
+from dataclasses import dataclass
+from importlib.metadata import version as pkg_version
+from pathlib import Path
+from typing import Callable, ClassVar, Literal
+from urllib.parse import urlparse
+
+from pydantic import Field
+
+from agent_env.artifact.artifact import Artifact
+from agent_env.store.ids import fs_safe, image_repository, is_local_id
+
+logger = logging.getLogger(__name__)
+
+ProgressCallback = Callable[[str, str, int], None]
+
+_SAFE_GIT_NAME = re.compile(r"^[a-zA-Z0-9._-]+$")
+
+
+def _validate_git_name(value: str, label: str) -> str:
+    if not _SAFE_GIT_NAME.match(value):
+        raise ValueError(f"Invalid {label}: {value!r}")
+    return value
+
+
+
+def _git_clone_commands(owner: str, repo: str, ref: str | None, token: str | None) -> list[str]:
+    """Shell commands that clone ``owner/repo`` at ``ref`` into /tmp/repo. A token rides a
+    throwaway GIT_ASKPASS helper so it never appears on a command line, and the helper is
+    removed whether or not the clone succeeds; without a token the clone is anonymous and
+    fails fast on a private repository instead of prompting."""
+    ref_flag = f"--branch {ref}" if ref else ""
+    clone_url = f"https://github.com/{owner}/{repo}.git"
+    if not token:
+        return [f"GIT_TERMINAL_PROMPT=0 git clone --depth 1 {ref_flag} {clone_url} /tmp/repo"]
+    askpass_script = (
+        '#!/bin/sh\n'
+        'case "$1" in\n'
+        '*sername*) echo x-access-token;;\n'
+        f'*) echo "{token}";;\n'
+        'esac\n'
+    )
+    return [
+        f"cat > /tmp/git-askpass.sh << 'ASKEOF'\n{askpass_script}ASKEOF",
+        "chmod +x /tmp/git-askpass.sh",
+        f"trap 'rm -f /tmp/git-askpass.sh' EXIT; GIT_ASKPASS=/tmp/git-askpass.sh git clone --depth 1 {ref_flag} {clone_url} /tmp/repo",
+    ]
+
+class DockerImageArtifact(Artifact):
+    """A Docker image artifact stored as tar.gz in S3."""
+
+    DOCKER_SAVE_TIMEOUT_SECONDS: ClassVar[int] = 900
+
+    type: Literal["docker_image"] = "docker_image"
+    description: str = Field(description="Description of the Docker image")
+    image_name: str = Field(description="Docker image name/tag")
+    tar_gz_object_url: str = Field(alias="tar_gz_s3_url", description="Object-store locator of the tar.gz file")
+    build_context_object_url: str | None = Field(default=None, alias="build_context_s3_url", description="Object-store locator of the build context tar.gz")
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        description: str,
+        image_name: str,
+        build_context_path: str | None = None,
+        dockerfile_path: str | None = None,
+    ) -> "DockerImageArtifact":
+        from agent_env.artifact.store import get_artifact_store
+        from agent_env.config import get_config
+
+        store = get_artifact_store()
+        version = store.next_version(id)
+
+        config = get_config()
+        image_store = config.get_image_store_for(id)
+        repository = image_repository(id)
+        image_ref = image_store.image_ref(repository, f"v{version}")
+        image_store.ensure_repository(repository)
+        _push_local_image(image_name, image_ref, image_store)
+
+        with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+
+        try:
+            save_proc = subprocess.Popen(
+                ["docker", "save", image_ref],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            with gzip.open(tmp_path, "wb") as gz_file:
+                while chunk := save_proc.stdout.read(8192):
+                    gz_file.write(chunk)
+            try:
+                save_proc.wait(timeout=cls.DOCKER_SAVE_TIMEOUT_SECONDS)
+            except subprocess.TimeoutExpired:
+                save_proc.kill()
+                raise RuntimeError(f"docker save {image_ref} timed out after {cls.DOCKER_SAVE_TIMEOUT_SECONDS} seconds")
+            if save_proc.returncode != 0:
+                stderr = save_proc.stderr.read().decode() if save_proc.stderr else ""
+                raise RuntimeError(f"docker save {image_ref} failed: {stderr}")
+
+            tar_gz_s3_url = store.put_object_file(
+                artifact_type="docker_image",
+                id=id,
+                version=version,
+                object_name=f"{fs_safe(id)}-v{version}.tar.gz",
+                file_path=str(tmp_path),
+                content_type="application/gzip",
+            )
+        finally:
+            if tmp_path.exists():
+                tmp_path.unlink()
+
+        build_context_s3_url = None
+        if build_context_path:
+            context_dir = Path(build_context_path)
+            paths_to_include = _get_dockerfile_copy_sources(context_dir, dockerfile_path)
+            with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as ctx_tmp:
+                ctx_tmp_path = Path(ctx_tmp.name)
+            try:
+                with tarfile.open(ctx_tmp_path, "w:gz") as tar:
+                    for rel_path in paths_to_include:
+                        full_path = context_dir / rel_path
+                        if full_path.exists():
+                            tar.add(str(full_path), arcname=rel_path)
+                build_context_s3_url = store.put_object_file(
+                    artifact_type="docker_image",
+                    id=id,
+                    version=version,
+                    object_name="build-context.tar.gz",
+                    file_path=str(ctx_tmp_path),
+                    content_type="application/gzip",
+                )
+            finally:
+                if ctx_tmp_path.exists():
+                    ctx_tmp_path.unlink()
+
+        return cls.put_tar(
+            id,
+            description=description,
+            image_name=image_ref,
+            tar_gz_s3_url=tar_gz_s3_url,
+            build_context_s3_url=build_context_s3_url,
+        )
+
+    @classmethod
+    def put_tar(
+        cls,
+        id: str,
+        *,
+        description: str,
+        image_name: str,
+        tar_gz_s3_url: str,
+        build_context_s3_url: str | None = None,
+    ) -> "DockerImageArtifact":
+        from agent_env.artifact.store import get_artifact_store
+        from agent_env.config import get_config
+
+        for url in (tar_gz_s3_url, build_context_s3_url):
+            if url:
+                get_config().check_object_url(id, url)
+        store = get_artifact_store()
+        version = store.next_version(id)
+        instance = cls(
+            id=id,
+            version=version,
+            description=description,
+            image_name=image_name,
+            tar_gz_s3_url=tar_gz_s3_url,
+            build_context_s3_url=build_context_s3_url,
+        )
+        return store.put_document(instance)
+
+    def load(self) -> bytes:
+        from agent_env.artifact.store import get_artifact_store
+        return get_artifact_store().get_object(self.tar_gz_object_url)
+
+    @classmethod
+    async def put_from_github(
+        cls,
+        id: str,
+        dockerfile_github_url: str,
+        docker_context_github_url: str | None = None,
+        on_progress: ProgressCallback | None = None,
+        github_token: str | None = None,
+    ) -> GitHubBuildResult:
+        """Build a Docker image from a GitHub repo on a temporary VM.
+
+        Clones the repo (with ``github_token`` when the repository is private), runs docker
+        build, saves the image, uploads to S3, and creates a DockerImageArtifact. Returns a GitHubBuildResult with
+        the artifact and git metadata.
+
+        Note: Branch names containing slashes (e.g. feature/fix-bug) are not
+        supported in GitHub URLs due to path ambiguity. Use branches/tags
+        without slashes, or the default branch.
+        """
+        from agent_env.providers import get_sandbox_provider
+        from agent_env.config import get_config
+
+        refuse_local_github_build(id)
+        log = on_progress or (lambda step, msg, pct: None)
+
+        log("validate", "Parsing GitHub URLs...", 5)
+        df_parts = cls._parse_github_url(dockerfile_github_url)
+        if df_parts.path is None:
+            raise ValueError(f"Dockerfile URL must include a path to the Dockerfile: {dockerfile_github_url}")
+
+        if docker_context_github_url:
+            ctx_parts = cls._parse_github_url(docker_context_github_url)
+            if (ctx_parts.owner, ctx_parts.repo) != (df_parts.owner, df_parts.repo):
+                raise ValueError("Dockerfile and context URLs must reference the same repository")
+            if ctx_parts.ref and df_parts.ref and ctx_parts.ref != df_parts.ref:
+                raise ValueError("Dockerfile and context URLs must reference the same ref")
+            context_repo_path = ctx_parts.path or ""
+        else:
+            context_repo_path = posixpath.dirname(df_parts.path)
+
+        owner, repo, ref = df_parts.owner, df_parts.repo, df_parts.ref
+        dockerfile_repo_path = df_parts.path
+        config = get_config()
+        suffix = uuid.uuid4().hex[:8]
+        image_tag = f"{id}-{suffix}"
+
+        from agent_env.artifact.store import get_artifact_store
+        store = get_artifact_store()
+        version = store.next_version(id)
+        image_store = config.get_image_store()
+        repository = image_repository(id)
+        image_ref = image_store.image_ref(repository, f"v{version}")
+        await asyncio.to_thread(image_store.ensure_repository, repository)
+        auth = await asyncio.to_thread(image_store.auth, image_ref)
+
+        log("create_vm", "Creating VM...", 10)
+        logger.info(f"put_from_github: cloning {owner}/{repo} ref={ref} dockerfile={dockerfile_repo_path} context={context_repo_path}")
+        sandbox = await get_sandbox_provider().create_vm(
+            disk_size_gb=20, timeout=1800, exposed_ports=[],
+            attribution={"project_id": "agent-env-image-builder"},
+        )
+        try:
+            log("install_git", "Installing git...", 20)
+            await sandbox.exec_script("apt-get update -qq && apt-get install -y -qq git >/dev/null 2>&1")
+
+            log("clone", f"Cloning {owner}/{repo}...", 30)
+            _validate_git_name(owner, "owner")
+            _validate_git_name(repo, "repo")
+            if ref:
+                _validate_git_name(ref, "ref")
+            for command in _git_clone_commands(owner, repo, ref, github_token):
+                await sandbox.exec_script(command)
+
+            commit_hash = (await sandbox.exec_script("git -C /tmp/repo rev-parse HEAD")).strip()
+
+            log("build", "Building Docker image...", 50)
+            dockerfile_abs = shlex.quote(f"/tmp/repo/{dockerfile_repo_path}")
+            context_abs = shlex.quote(f"/tmp/repo/{context_repo_path}" if context_repo_path else "/tmp/repo")
+            await sandbox.exec_script(f"test -f {dockerfile_abs}")
+            await sandbox.exec_script(f"docker build --platform linux/amd64 -f {dockerfile_abs} -t {shlex.quote(image_tag)} {context_abs}")
+
+            log("push", "Pushing image...", 60)
+            login_cmd = ""
+            if auth is not None:
+                login_cmd = (
+                    f"echo {shlex.quote(auth.password)} | docker login "
+                    f"--username {shlex.quote(auth.username)} --password-stdin {shlex.quote(auth.registry)} && "
+                )
+            await sandbox.exec_script(
+                f"docker tag {shlex.quote(image_tag)} {shlex.quote(image_ref)} && "
+                f"{login_cmd}"
+                f"docker push {shlex.quote(image_ref)}"
+            )
+
+            log("save", "Saving Docker image...", 65)
+            await sandbox.exec_script(f"docker save {shlex.quote(image_ref)} | gzip > /tmp/image.tar.gz")
+
+            log("upload", "Uploading to object store...", 75)
+            object_store = config.get_object_store()
+
+            def _signed_put(key: str) -> tuple[str, str]:
+                url = object_store.object_url(f"{config.get_artifact_key_prefix()}{key}")
+                put = object_store.signed_put_url(url)
+                if put is None:
+                    raise RuntimeError(
+                        f"{type(object_store).__name__} can't presign uploads; GitHub image builds need a signable object store."
+                    )
+                return url, put
+
+            tar_gz_s3_url, image_put_url = await asyncio.to_thread(_signed_put, f"github-builds/{id}/{image_tag}.tar.gz")
+            await sandbox.exec_script(f'curl -fsSL -X PUT --upload-file /tmp/image.tar.gz "{image_put_url}"')
+
+            log("upload_context", "Uploading build context...", 80)
+            dockerfile_content = await sandbox.exec_script(f"cat {dockerfile_abs}")
+            df_rel = posixpath.relpath(dockerfile_repo_path, context_repo_path) if context_repo_path else dockerfile_repo_path
+            copy_sources = _parse_copy_sources(dockerfile_content, df_rel)
+            tar_paths = " ".join(shlex.quote(p) for p in copy_sources)
+            await sandbox.exec_script(f"tar czf /tmp/build-context.tar.gz -C {context_abs} {tar_paths}")
+            build_context_s3_url, context_put_url = await asyncio.to_thread(
+                _signed_put, f"github-builds/{id}/{image_tag}-context.tar.gz"
+            )
+            await sandbox.exec_script(f'curl -fsSL -X PUT --upload-file /tmp/build-context.tar.gz "{context_put_url}"')
+        finally:
+            log("cleanup", "Terminating build VM...", 85)
+            await sandbox.terminate()
+
+        log("store", "Storing artifact...", 90)
+        artifact = cls.put_tar(
+            id=id,
+            description=f"Built from GitHub: {dockerfile_github_url}",
+            image_name=image_ref,
+            tar_gz_s3_url=tar_gz_s3_url,
+            build_context_s3_url=build_context_s3_url,
+        )
+        logger.info(f"put_from_github: created artifact id={artifact.id} version={artifact.version}")
+
+        result = GitHubBuildResult(
+            artifact=artifact,
+            github_owner=owner,
+            github_repo=repo,
+            github_ref=ref,
+            github_commit=commit_hash,
+            dockerfile_github_url=dockerfile_github_url,
+            docker_context_github_url=docker_context_github_url,
+        )
+        log("done", f"Created artifact {id}", 100)
+        return result
+
+    @dataclass
+    class _GitHubURLParts:
+        owner: str
+        repo: str
+        ref: str | None
+        path: str | None
+
+    @staticmethod
+    def _parse_github_url(url: str) -> DockerImageArtifact._GitHubURLParts:
+        """Parse a GitHub browser URL into components.
+
+        Accepts:
+            https://github.com/{owner}/{repo}
+            https://github.com/{owner}/{repo}/tree/{ref}
+            https://github.com/{owner}/{repo}/tree/{ref}/{path}
+            https://github.com/{owner}/{repo}/blob/{ref}/{path}
+        """
+        parsed = urlparse(url)
+        if parsed.hostname != "github.com":
+            raise ValueError(f"Expected github.com URL, got: {parsed.hostname}")
+        segments = [s for s in parsed.path.strip("/").split("/") if s]
+        if len(segments) < 2:
+            raise ValueError(f"GitHub URL must include owner and repo: {url}")
+        owner, repo = segments[0], segments[1]
+        if len(segments) == 2:
+            return DockerImageArtifact._GitHubURLParts(owner=owner, repo=repo, ref=None, path=None)
+        if segments[2] not in ("tree", "blob"):
+            raise ValueError(f"Expected /tree/ or /blob/ in GitHub URL, got /{segments[2]}/: {url}")
+        if len(segments) < 4:
+            raise ValueError(f"GitHub URL must include a ref after /tree/: {url}")
+        ref = segments[3]
+        path = "/".join(segments[4:]) if len(segments) > 4 else None
+        return DockerImageArtifact._GitHubURLParts(owner=owner, repo=repo, ref=ref, path=path)
+
+
+def refuse_local_github_build(entity_id: str) -> None:
+    """A GitHub build publishes to the configured registry, so it takes a registry id; an ``@local``
+    image is built from its own Dockerfile."""
+    if is_local_id(entity_id):
+        raise ValueError(
+            f"{entity_id!r} is an @local id, but a GitHub build publishes to the configured registry; give it a registry id"
+        )
+
+
+@dataclass
+class GitHubBuildResult:
+    artifact: DockerImageArtifact
+    github_owner: str
+    github_repo: str
+    github_ref: str | None
+    github_commit: str
+    dockerfile_github_url: str
+    docker_context_github_url: str | None
+
+
+def _push_local_image(local_tag: str, image_ref: str, image_store) -> None:
+    auth = image_store.auth(image_ref)
+    if auth is not None:
+        login = subprocess.run(
+            ["docker", "login", "--username", auth.username, "--password-stdin", auth.registry],
+            input=auth.password, text=True, capture_output=True,
+        )
+        if login.returncode != 0:
+            raise RuntimeError(f"docker login failed: {login.stderr}")
+
+    for cmd, label in [
+        (["docker", "tag", local_tag, image_ref], "tag"),
+        (["docker", "push", image_ref], "push"),
+    ]:
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"docker {label} failed: {result.stderr}")
+    logger.info(f"Pushed {local_tag} -> {image_ref}")
+
+
+def _parse_copy_sources(dockerfile_text: str, dockerfile_rel_path: str | None = None) -> list[str]:
+    """Parse COPY/ADD source paths from Dockerfile text. Returns top-level directories to include in context tar."""
+    paths: list[str] = []
+    if dockerfile_rel_path:
+        paths.append(dockerfile_rel_path)
+
+    for line in dockerfile_text.splitlines():
+        stripped = line.strip()
+        if not stripped.upper().startswith("COPY ") and not stripped.upper().startswith("ADD "):
+            continue
+        parts = stripped.split()
+        args = [p for p in parts[1:] if not p.startswith("--")]
+        if len(args) < 2:
+            continue
+        for src in args[:-1]:
+            if src.startswith("/") or "://" in src:
+                continue
+            src_clean = src.rstrip("/")
+            top_dir = src_clean.split("/")[0]
+            if top_dir and top_dir != "." and top_dir not in paths:
+                paths.append(top_dir)
+
+    return paths if paths else ["."]
+
+
+def _get_dockerfile_copy_sources(context_dir: Path, dockerfile_path: str | None) -> list[str]:
+    """Parse COPY source paths from a local Dockerfile and return relative paths to include in the build context tar."""
+    if not dockerfile_path:
+        return ["."]
+
+    df = Path(dockerfile_path)
+    if not df.is_absolute() and not df.exists():
+        df = context_dir / df
+
+    try:
+        df_rel = str(df.relative_to(context_dir))
+    except ValueError:
+        df_rel = None
+
+    paths = _parse_copy_sources(df.read_text(), df_rel)
+    return [p for p in paths if (context_dir / p).exists()] or ["."]