hivekit 0.8.0__tar.gz → 0.8.2__tar.gz

{hivekit-0.8.0 → hivekit-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hivekit
-Version: 0.8.0
+Version: 0.8.2
 Summary: Toolkits for using hive agents, including CLI and SDK.
 License: 
                                          Apache License
@@ -210,6 +210,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML>=5.1
+Requires-Dist: packaging>=21.0
 Requires-Dist: ruamel-yaml>=0.18
 Requires-Dist: pydantic>=1.8.2
 Requires-Dist: gitpython>=3.1.58

{hivekit-0.8.0 → hivekit-0.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hivekit"
-version = "0.8.0"
+version = "0.8.2"
 description = "Toolkits for using hive agents, including CLI and SDK."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -12,6 +12,7 @@ license = { file = "LICENSE" }
 
 dependencies = [
     "PyYAML>=5.1",
+    "packaging>=21.0",
     "ruamel-yaml>=0.18",
     "pydantic>=1.8.2",
     "gitpython>=3.1.58",

{hivekit-0.8.0 → hivekit-0.8.2}/src/cli/config.py

@@ -11,6 +11,7 @@ import pydantic
 import yaml
 from kubernetes.utils import parse_quantity
 from pydantic import (
+    AnyHttpUrl,
     ConfigDict,
     Field,
     PrivateAttr,
@@ -19,7 +20,6 @@ from pydantic import (
     model_validator,
 )
 
-from cli.utils.config_paths import get_coordinator_overlay_path
 from cli.utils.logger import set_log_level
 from cli.utils.time import unique_suffix
 
@@ -256,11 +256,67 @@ class PromptConfig(BaseModel):
         default=None,
         description="A list of ideas which will be randomly sampled to inject into the Hive.",
     )
-    arxiv_ids: Optional[list[str]] = Field(
+    attachments: Optional[list[str]] = Field(
         default=None,
-        description="A list of arXiv IDs to provide as reference material to the Hive.",
+        description=(
+            "A list of local PDF files/directories or HTTP/HTTPS PDF URLs to provide as "
+            "reference material. Directories are searched recursively for files with a "
+            ".pdf extension (case-insensitive). Local relative paths resolve from the "
+            "directory where hive is run."
+        ),
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_arxiv_ids(cls, values):
+        """Convert legacy IDs into attachment URLs without mutating the input."""
+        if not isinstance(values, dict) or "arxiv_ids" not in values:
+            return values
+        values = dict(values)
+        # Preserve the legacy list's type coercion while folding it into attachments.
+        string_list = pydantic.TypeAdapter(Optional[list[str]], config=cls.model_config)
+        legacy = string_list.validate_python(values.pop("arxiv_ids"))
+        converted_urls = [f"https://arxiv.org/pdf/{arxiv_id}" for arxiv_id in legacy or []]
+        if converted_urls:
+            attachments = string_list.validate_python(
+                cls.validate_attachments_list(values.get("attachments"))
+            )
+            values["attachments"] = [*(attachments or []), *converted_urls]
+        warning = (
+            "prompt.arxiv_ids is deprecated and is converted to PDF URLs in "
+            "prompt.attachments. Use PDF URLs in prompt.attachments and remove "
+            "prompt.arxiv_ids to silence this warning."
+        )
+        if converted_urls:
+            warning += "\nConverted PDF URLs:\n" + "\n".join(f"  - {url}" for url in converted_urls)
+        logger.warning(warning)
+        return values
+
+    @field_validator("attachments", mode="before")
+    @classmethod
+    def validate_attachments_list(cls, value):
+        if isinstance(value, str):
+            raise ValueError(
+                "Must be a YAML list, not a plain string. Example:\n  attachments:\n    - paper.pdf"
+            )
+        return value
+
+    @field_validator("attachments")
+    @classmethod
+    def validate_attachment_syntax(cls, value: Optional[list[str]]) -> Optional[list[str]]:
+        """Check attachment syntax without accessing local files or the network."""
+        if not value:
+            return value
+        http_url = pydantic.TypeAdapter(AnyHttpUrl)
+        for source in value:
+            if not source.strip():
+                raise ValueError("Attachment paths and URLs must not be empty")
+            # Recognize URL prefixes without treating colons in local filenames as schemes.
+            if re.match(r"(?i)^(?:[a-z][a-z0-9+.-]*://|https?:)", source.lstrip()):
+                http_url.validate_python(source, strict=True)
+        # Keep configured paths and URLs unchanged, including URL query strings.
+        return value
+
 
 def _extract_path(entry: str, strip_exclude: bool = False) -> str:
     """Reduce a file-list entry to the path it references."""
@@ -630,10 +686,9 @@ class HiveConfig(BaseModel):
     coordinator_image_tag: Optional[str] = Field(
         default=None,
         description="The image tag to run the coordinator at, e.g. 'v0.6.0'. Optional — when "
-        "omitted, in a dev environment the tag recorded by `hivectl generate config` in "
-        "~/.hive/coordinator.yaml is used if present. If that file or tag is absent, or in a "
-        "production environment, the backend's default coordinator image is used. This field is "
-        "ignored in production environments.",
+        "omitted, the backend's default coordinator image is used. Set this in the experiment "
+        "config or with a command-line override. This field is ignored outside development "
+        "environments.",
     )
     runtime: RuntimeConfig = Field(
         default_factory=RuntimeConfig, description="Runtime configuration for the experiment."
@@ -862,71 +917,12 @@ def _reconcile_num_sandboxes_override(cfg: dict, overridden_keys: set[tuple[str,
     del runtime[loser]
 
 
-def _recorded_coordinator_image_tag(overlay_path: str) -> Optional[str]:
-    """Return the coordinator image tag recorded in the overlay file, if any.
-
-    A broken overlay must not stop an experiment the user asked for, so anything
-    unusable is warned about and ignored. An absent, empty or non-scalar tag
-    records nothing; a bool is not a scalar here, being an int subclass.
-    """
-    if not os.path.exists(overlay_path):
-        return None
-    try:
-        with open(overlay_path, "r") as file:
-            overlay = yaml.safe_load(file)
-    except (OSError, yaml.YAMLError) as e:
-        logger.warning("Ignoring %s, which could not be read: %s", overlay_path, e)
-        return None
-    tag = overlay.get("coordinator_image_tag") if isinstance(overlay, dict) else None
-    if tag is None or tag == "":
-        return None
-    if isinstance(tag, bool) or not isinstance(tag, (str, int, float)):
-        logger.warning(
-            "Ignoring coordinator_image_tag: %r in %s, which must be a string or number.",
-            tag,
-            overlay_path,
-        )
-        return None
-    return str(tag)
-
-
-def _resolve_coordinator_image_tag(config_data: dict, overridden: bool) -> None:
-    """Fall back to the coordinator image tag `hivectl generate config` recorded.
-
-    A tag the experiment asked for wins, even an empty one asking for the backend
-    default. Whichever tag is used is logged with where it came from, as is any
-    recorded tag it discards, so which coordinator image runs is never a surprise.
-    """
-    overlay_path = get_coordinator_overlay_path()
-    recorded = _recorded_coordinator_image_tag(overlay_path)
-    if "coordinator_image_tag" not in config_data:
-        if recorded is None:
-            return
-        config_data["coordinator_image_tag"] = recorded
-        logger.warning(
-            "Using coordinator_image_tag=%s recorded in %s by `hivectl generate config`; "
-            "set coordinator_image_tag in the experiment config to override it.",
-            recorded,
-            overlay_path,
-        )
-        return
-    asked_for = config_data["coordinator_image_tag"]
+def _log_coordinator_image_tag(config_data: dict, overridden: bool) -> None:
+    """Report the tag explicitly selected by the experiment config or CLI."""
+    asked_for = config_data.get("coordinator_image_tag")
     source = "a command-line override" if overridden else "the experiment config"
-    # str(): an unquoted digit-only tag loads as an int. None is not compared, or
-    # an explicit null would match the tag "None" rather than discard it.
-    if recorded is not None and (asked_for is None or str(asked_for) != recorded):
-        logger.warning(
-            "Using coordinator_image_tag=%s from %s, discarding coordinator_image_tag=%s "
-            "recorded in %s.",
-            asked_for,
-            source,
-            recorded,
-            overlay_path,
-        )
-    elif asked_for is not None and asked_for != "":
+    if asked_for is not None and asked_for != "":
         logger.warning("Using coordinator_image_tag=%s from %s.", asked_for, source)
-    # An empty tag with nothing to discard asks for the backend's default image,
-    # exactly as setting no tag at all does, so there is nothing to report.
 
 
 def load_config(
@@ -936,8 +932,8 @@ def load_config(
 ) -> HiveConfig:
     """Load configuration from a YAML file.
 
-    Pass ``coordinator=False`` when no coordinator will run, so the recorded
-    coordinator image tag is neither filled in nor reported as being used.
+    Pass ``coordinator=False`` when no coordinator will run, so an explicit
+    coordinator image tag is not reported as being used.
     """
     with open(file_path, "r") as file:
         raw_text = file.read()
@@ -948,7 +944,7 @@ def load_config(
         overridden_keys = apply_overrides(config_data, overrides)
 
     if coordinator and isinstance(config_data, dict):
-        _resolve_coordinator_image_tag(config_data, ("coordinator_image_tag",) in overridden_keys)
+        _log_coordinator_image_tag(config_data, ("coordinator_image_tag",) in overridden_keys)
 
     try:
         config = HiveConfig(**config_data)

{hivekit-0.8.0 → hivekit-0.8.2}/src/cli/experiment.py

@@ -124,8 +124,6 @@ def build_experiment_crd(config: HiveConfig) -> Dict[str, Any]:
             experiment["spec"]["prompt"]["context"] = config.prompt.context
         if config.prompt.ideas:
             experiment["spec"]["prompt"]["ideas"] = config.prompt.ideas
-        if config.prompt.arxiv_ids:
-            experiment["spec"]["prompt"]["arxivIds"] = config.prompt.arxiv_ids
         if config.prompt.enable_evolution:
             experiment["spec"]["prompt"]["enableEvolution"] = config.prompt.enable_evolution
 

{hivekit-0.8.0 → hivekit-0.8.2}/src/cli/main.py

@@ -11,6 +11,7 @@ import shlex
 import sys
 import tempfile
 import time
+import traceback
 import warnings
 import webbrowser
 
@@ -38,12 +39,14 @@ from cli.http_client import (
 )
 from cli.skills_install import TARGETS as SKILL_TARGETS
 from cli.skills_install import skills_install
+from cli.update_check import check_for_update, print_update_footer, warn_if_outdated
 from cli.utils import docker
 from cli.utils.archive import resolve_file_list
+from cli.utils.attachments import AttachmentError, prepare_attachments
 from cli.utils.config_paths import get_config_dir, get_config_path, load_organization_id
 from cli.utils.config_sync import sync_base_image
 from cli.utils.time import humanize_time
-from cli.utils.upload import streaming_upload
+from cli.utils.upload import streaming_upload, streaming_upload_entries
 from cli.utils.url_utils import (
     build_oidc_endpoints,
     derive_identity_base_url,
@@ -251,6 +254,18 @@ def _upload_source_if_any(
         return patch_id
 
 
+def _upload_attachments_if_any(
+    client, attachments: list[str] | None, *, dry_run: bool = False
+) -> str | None:
+    """Prepare and upload PDFs, keeping downloads only for the upload's lifetime."""
+    with prepare_attachments(attachments or []) as entries:
+        if not entries or dry_run:
+            return None
+        resource_id = streaming_upload_entries(client, entries)
+        logger.debug("Resource upload complete. resource_id=%s", resource_id)
+        return resource_id
+
+
 @contextlib.contextmanager
 def _resolve_source(config):
     """Yield a local directory path for repo.source, cloning if remote."""
@@ -291,14 +306,24 @@ def create_experiment(args, overrides) -> None:
         )
         sys.exit(1)
 
+    attachments = config.prompt.attachments if config.prompt is not None else []
+    try:
+        resource_id = _upload_attachments_if_any(client, attachments, dry_run=args.dry_run)
+    except AttachmentError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}", highlight=False)
+        sys.exit(1)
+
     experiment_crd = experiment.build_experiment_crd(config)
 
     patch_id = _upload_source_if_any(
         client, config, dry_run=args.dry_run, allow_missing=args.allow_missing_files
     )
-    if patch_id:
-        experiment_crd.setdefault("metadata", {}).setdefault("annotations", {})
-        experiment_crd["metadata"]["annotations"]["hiverge.ai/patch-key"] = patch_id
+    if patch_id or resource_id:
+        annotations = experiment_crd.setdefault("metadata", {}).setdefault("annotations", {})
+        if patch_id:
+            annotations["hiverge.ai/patch-key"] = patch_id
+        if resource_id:
+            annotations["hiverge.ai/resource-key"] = resource_id
 
     if args.dry_run:
         console.print(
@@ -1626,6 +1651,27 @@ def main():
 
     argcomplete.autocomplete(parser)
     args, overrides = parser.parse_known_args()
+
+    status = check_for_update()
+    if status is not None and status.outdated:
+        warn_if_outdated(status)
+
+    try:
+        _dispatch(parser, args, overrides)
+    except SystemExit as exc:
+        if status is not None and status.outdated and _is_failure_code(exc.code):
+            print_update_footer(status)
+        raise
+    except Exception:
+        if status is None or not status.outdated:
+            raise
+        traceback.print_exc()
+        print_update_footer(status)
+        raise SystemExit(1)
+
+
+def _dispatch(parser, args, overrides) -> None:
+    """Route parsed args to the selected command, or print help if none."""
     if hasattr(args, "func"):
         if args.func in (create_experiment, shell_command):
             args.func(args, overrides)
@@ -1634,3 +1680,13 @@ def main():
             args.func(args)
     else:
         parser.print_help()
+
+
+def _is_failure_code(code: object) -> bool:
+    """Whether a SystemExit code denotes a failure worth footing the notice on.
+
+    ``0``/``None`` are success; 130 is a Ctrl-C interrupt, not a hive failure.
+    Any other value (a nonzero int, or a message string ``sys.exit`` prints) is
+    a failure.
+    """
+    return code not in (0, None, 130)

{hivekit-0.8.0 → hivekit-0.8.2}/src/cli/skills/hive-setup/SKILL.md

@@ -307,7 +307,13 @@ This is the agents' primary steer. Write it as an onboarding document — imagin
 
 - **Describe the problem, not the solution.** Do NOT suggest optimization approaches, likely bottlenecks, or directions to explore — that biases the Hive and narrows its search.
 - **Never describe the current code.** This context is fixed while the target evolves every iteration, so anything about how the present implementation works is stale and misleading at once.
-- **Distill useful background from the repo's README or design docs** into this prose — agents get context only here, never as markdown files; `repo.additional_context` is for code files only.
+- **Distill useful background from the repo's README or design docs** into this prose — `repo.additional_context` is for code files only. PDF references can be attached separately (see below).
+
+### PDF reference material
+
+When the user supplies research papers, technical manuals, or other PDF references, add them under `prompt.attachments`. They provide reference material for agents and are not included in candidate code. Keep the task and metric in `prompt.context`, with a short note on which references are relevant.
+
+Use local PDF files, local directories, or PDF URLs. For arXiv papers, use the `/pdf/` URL, such as `https://arxiv.org/pdf/2605.10327`. See [PDF attachments](references/configuration.md#pdf-attachments) for an example, path handling, and limits.
 
 ### Key field notes
 
@@ -336,6 +342,8 @@ These drive cost and feasibility, so **when unsure about sandbox count, runtime,
 
 After writing `hive.yaml`, you **must** run `hive create exp -c hive.yaml --dry-run` to confirm the config is valid. Fix any errors before moving on.
 
+With `prompt.attachments`, the dry-run also checks local PDFs and downloads PDF URLs for validation. Relative attachment paths resolve from the directory where you run `hive`; use absolute paths if the launch directory may differ.
+
 Add `--allow-missing-files` only when a `target_code`/`additional_context` path is deliberately absent from the upload — a prebuilt image with `repo.files` narrowed, `source: null`, or a file `setup_script` generates. It's accepted by `hive create exp` and `hive shell` alike; when the whole source directory is uploaded, omit it so a mistyped path still errors.
 
 

{hivekit-0.8.0 → hivekit-0.8.2}/src/cli/skills/hive-setup/references/configuration.md

@@ -22,6 +22,7 @@ Source: https://docs.hiverge.ai/gettingstarted/cli/configuration
 | `apiversion` | string | `v1alpha1` | Schema version |
 | `experiment_name` | string | required | Valid DNS label (`[a-z0-9-]`, max 51 chars, no leading `-`); trailing `-` appends a random 7-char unique suffix, so a name ending in `-` may have at most 43 chars before the `-` |
 | `coordinator_config_name` | string | `default-coordinator-config` | |
+| `coordinator_image_tag` | string | `null` | Development environments only. Set explicitly here or via `coordinator_image_tag=<tag>` on the command line; omitted or empty uses the backend default. |
 
 ## `repo`
 | Field | Type | Default | Notes |
@@ -108,6 +109,23 @@ Optional — omit for defaults. Steers the agents' search.
 |---|---|---|---|
 | `context` | string | — | Experiment-specific guidance, multi-line |
 | `ideas` | list[string] | — | Distinct directions; one randomly sampled and injected each iteration |
+| `attachments` | list[string] | `null` | Local PDF files, local directories, or PDF URLs. See [PDF attachments](#pdf-attachments). |
+
+### PDF attachments
+
+PDFs provide reference material for agents and are not included in candidate code.
+
+```yaml
+prompt:
+  attachments:
+    - papers/reference.pdf
+    - background/
+    - https://arxiv.org/pdf/2605.10327
+```
+
+- Relative paths resolve from the directory where you run `hive`, not from the location of `hive.yaml` or `repo.source`. Directories are searched recursively for PDFs.
+- Each PDF can be up to **20 MiB**. URLs must return a PDF; use a paper's PDF download URL rather than its abstract or landing page.
+- The CLI validates attachments before creating the experiment. `hive create exp -c hive.yaml --dry-run` also checks attachments, including downloading PDF URLs.
 
 ## Evaluator output contract
 `evaluate.py` must print a JSON object on the **final line** of stdout, and must **exit 0 even when reporting a failure** — a non-zero exit code is a crashed evaluator, not a failed candidate. Report invalid candidates with `{"status": "failed", ...}` and exit cleanly.
@@ -181,6 +199,8 @@ prompt:
   ideas:
     - "Try batching database writes"
     - "Consider async I/O for network calls"
+  attachments:
+    - https://arxiv.org/pdf/2605.10327
 ```
 
 ## CLI cheat-sheet

hivekit-0.8.2/src/cli/update_check.py

@@ -0,0 +1,136 @@
+# Copyright (C) 2026 Hiverge
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Compare the running hivekit against the latest release on PyPI.
+
+The check runs once at CLI startup. It is best-effort and fail-closed: any
+network error, timeout, missing metadata, or unparseable version yields
+an unknown status and skips the checks.
+"""
+
+import logging
+import os
+import sys
+import tomllib
+from dataclasses import dataclass
+
+import requests
+from packaging.version import InvalidVersion, Version
+
+from cli.version import _direct_url, _editable_source_dir, _package_version
+
+logger = logging.getLogger("hivekit")
+
+_PYPI_URL = "https://pypi.org/pypi/hivekit/json"
+_TIMEOUT_SECONDS = 3.0
+
+# Any non-empty value skips the network round-trip (CI, air-gapped, tests).
+_SKIP_ENV = "HIVE_NO_UPDATE_CHECK"
+
+
+# Sits after the pinned install commands in both the warning and the footer.
+_SKILLS_LINE = "then optionally update the Hive Skills with `hive skills install`."
+
+
+def _upgrade_commands(latest: str) -> str:
+    """The two pinned install commands, one per indented line.
+
+    The version pin (``hivekit==<latest>``) is required: a bare ``--upgrade
+    hivekit`` is a no-op whenever the resolver already considers the environment
+    satisfied, so the exact target version must be named.
+    """
+    return (
+        f"  uv pip install --upgrade hivekit=={latest}\n  pip install --upgrade hivekit=={latest}"
+    )
+
+
+@dataclass(frozen=True)
+class UpdateStatus:
+    local: str
+    latest: str
+    outdated: bool
+
+
+def _local_version() -> str:
+    """Version to compare against PyPI.
+
+    An editable install's recorded metadata is frozen at ``pip install -e``
+    time, so it lags the working tree. For a dev build the true version is
+    whatever the checkout's ``pyproject.toml`` declares now, so prefer that;
+    fall back to the recorded metadata for wheel/VCS/PyPI installs and whenever
+    the file cannot be read or declares no static version.
+    """
+    source_dir = _editable_source_dir(_direct_url())
+    if source_dir is not None:
+        try:
+            with open(os.path.join(source_dir, "pyproject.toml"), "rb") as f:
+                version = tomllib.load(f)["project"]["version"]
+            logger.debug("Editable checkout: version %s from pyproject.toml", version)
+            return version
+        except (OSError, tomllib.TOMLDecodeError, KeyError, TypeError):
+            logger.debug("Editable checkout: pyproject.toml version unreadable", exc_info=True)
+    return _package_version()
+
+
+def _latest_version() -> str | None:
+    """Return the newest hivekit version on PyPI, or ``None`` if unavailable."""
+    try:
+        resp = requests.get(_PYPI_URL, timeout=_TIMEOUT_SECONDS)
+        resp.raise_for_status()
+        latest = resp.json()["info"]["version"]
+        logger.debug("PyPI reports latest hivekit version %s", latest)
+        return latest
+    except Exception:
+        logger.debug("PyPI version check failed", exc_info=True)
+        return None
+
+
+def check_for_update() -> UpdateStatus | None:
+    """Compare the installed version against PyPI's latest.
+
+    Returns ``None`` when no comparison can be made (check disabled, network
+    failure, or either version unparseable); otherwise an ``UpdateStatus``.
+    """
+    if os.getenv(_SKIP_ENV):
+        return None
+
+    local = _local_version()
+    logger.debug("Installed hivekit version %s", local)
+    latest = _latest_version()
+    if latest is None:
+        return None
+
+    try:
+        outdated = Version(local) < Version(latest)
+    except InvalidVersion:
+        logger.debug("Unparseable version (local=%r latest=%r)", local, latest)
+        return None
+
+    logger.debug("Version check: local=%s latest=%s outdated=%s", local, latest, outdated)
+    return UpdateStatus(local=local, latest=latest, outdated=outdated)
+
+
+def warn_if_outdated(status: UpdateStatus) -> None:
+    """Emit a startup WARNING when the running version is behind PyPI."""
+    logger.warning(
+        "hivekit %s is out of date; the latest release is %s. Update with:\n%s\n%s",
+        status.local,
+        status.latest,
+        _upgrade_commands(status.latest),
+        _SKILLS_LINE,
+    )
+
+
+def print_update_footer(status: UpdateStatus) -> None:
+    """Restate the staleness as the final lines after a failed command.
+
+    Written to stderr so it trails the traceback or error a failure already
+    emitted there.
+    """
+    print(
+        f"\nThe current version of hivekit is {status.local} the latest version "
+        f"is {status.latest}. Please update with:\n{_upgrade_commands(status.latest)}\n"
+        f"{_SKILLS_LINE}",
+        file=sys.stderr,
+    )

{hivekit-0.8.0 → hivekit-0.8.2}/src/cli/utils/archive.py

@@ -1,23 +1,37 @@
 import logging
 import os
 import tarfile
+from dataclasses import dataclass
 from pathlib import PurePath
 
 logger = logging.getLogger("hivekit")
 
 
+@dataclass(frozen=True)
+class ArchiveEntry:
+    """One physical file and the relative name it should have in an archive."""
+
+    source_path: str
+    archive_name: str
+
+
 def _is_glob(pattern: str) -> bool:
     return any(c in pattern for c in "*?[")
 
 
+def _validate_relative_path(rel_path: str) -> None:
+    """Ensure a path is a safe relative archive name."""
+    if os.path.isabs(rel_path) or ".." in rel_path.split(os.sep):
+        raise ValueError(f"Unsafe relative path: '{rel_path}'")
+
+
 def _validate_path(base_dir: str, rel_path: str) -> None:
     """Ensure rel_path resolves within base_dir and is a safe archive name."""
+    _validate_relative_path(rel_path)
     real_base = os.path.realpath(base_dir)
     real_full = os.path.realpath(os.path.join(base_dir, rel_path))
     if not real_full.startswith(real_base + os.sep) and real_full != real_base:
         raise ValueError(f"Path escapes base directory: '{rel_path}'")
-    if os.path.isabs(rel_path) or ".." in rel_path.split(os.sep):
-        raise ValueError(f"Unsafe relative path: '{rel_path}'")
 
 
 def _walk_non_hidden(base_dir: str):
@@ -125,6 +139,25 @@ def add_to_tar(tar: tarfile.TarFile, base_dir: str, files: list[str]) -> None:
             raise ValueError(f"Path is neither file nor directory: '{entry}'")
 
 
+def add_entries_to_tar(tar: tarfile.TarFile, entries: list[ArchiveEntry]) -> None:
+    """Add explicitly mapped regular files to an open tar archive."""
+    seen: set[str] = set()
+    for entry in entries:
+        _validate_relative_path(entry.archive_name)
+        if entry.archive_name in {"", "."}:
+            raise ValueError(f"Unsafe archive name: '{entry.archive_name}'")
+        if entry.archive_name in seen:
+            raise ValueError(f"Duplicate archive name: '{entry.archive_name}'")
+        seen.add(entry.archive_name)
+
+        source_path = os.path.expanduser(entry.source_path)
+        if os.path.islink(source_path):
+            raise ValueError(f"Symlinks are not supported: '{source_path}'")
+        if not os.path.isfile(source_path):
+            raise ValueError(f"Archive source is not a file: '{source_path}'")
+        tar.add(source_path, arcname=entry.archive_name, recursive=False)
+
+
 def _add_directory(tar: tarfile.TarFile, base_dir: str, rel_dir: str) -> None:
     """Recursively add a directory, rejecting symlinks at any level."""
     full_dir = os.path.join(base_dir, rel_dir)