hivekit 0.8.1__tar.gz → 0.8.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hivekit
-Version: 0.8.1
+Version: 0.8.2
 Summary: Toolkits for using hive agents, including CLI and SDK.
 License: 
                                          Apache License

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hivekit"
-version = "0.8.1"
+version = "0.8.2"
 description = "Toolkits for using hive agents, including CLI and SDK."
 readme = "README.md"
 requires-python = ">=3.12"

{hivekit-0.8.1 → 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.1 → 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.1 → hivekit-0.8.2}/src/cli/main.py

@@ -42,10 +42,11 @@ 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,
@@ -253,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."""
@@ -293,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(

{hivekit-0.8.1 → 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.1 → 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.1 → 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)

hivekit-0.8.2/src/cli/utils/attachments.py

@@ -0,0 +1,225 @@
+# Copyright (C) 2026 Hiverge
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Prepare local and remote PDF attachments for upload."""
+
+import contextlib
+import os
+import re
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path, PurePosixPath
+from urllib.parse import unquote, urlparse
+
+import requests
+from rich import filesize
+from rich.markup import escape
+from rich.progress import FileSizeColumn, Progress, SpinnerColumn, TextColumn, TransferSpeedColumn
+
+from cli.utils.archive import ArchiveEntry
+
+MAX_PDF_ATTACHMENT_BYTES = 20 * 1024 * 1024
+MAX_PDF_ATTACHMENT_MIB = MAX_PDF_ATTACHMENT_BYTES // (1024 * 1024)
+RESOURCES_DIR = ".hive/resources"
+
+_DOWNLOAD_CHUNK_SIZE = 64 * 1024
+_PDF_HEADER_SCAN_BYTES = 1024
+_REQUEST_TIMEOUT = (10, 120)
+
+
+class AttachmentError(ValueError):
+    """A configured attachment could not be prepared for upload."""
+
+
+def _validate_pdf(path: Path, configured_source: str) -> None:
+    """Check the PDF header and size, rejecting symlinks and unreadable files."""
+    if path.is_symlink():
+        raise AttachmentError(
+            f"attachment {configured_source!r} is a symlink; symlinks are not supported"
+        )
+    try:
+        size = path.stat().st_size
+    except OSError as error:
+        raise AttachmentError(
+            f"attachment {configured_source!r} could not be read: {error}"
+        ) from error
+    if size > MAX_PDF_ATTACHMENT_BYTES:
+        raise AttachmentError(
+            f"attachment {configured_source!r} exceeds the {MAX_PDF_ATTACHMENT_MIB} MiB PDF limit"
+        )
+    try:
+        with path.open("rb") as file:
+            header = file.read(_PDF_HEADER_SCAN_BYTES)
+    except OSError as error:
+        raise AttachmentError(
+            f"attachment {configured_source!r} could not be read: {error}"
+        ) from error
+    if b"%PDF-" not in header:
+        raise AttachmentError(f"attachment {configured_source!r} is not a PDF")
+
+
+def _safe_stem(value: str) -> str:
+    """Return a non-empty filename stem without path components or control characters."""
+    name = PurePosixPath(value.replace("\\", "/")).name
+    name = re.sub(r"[\x00-\x1f\x7f]", "", name).strip()
+    if name.lower().endswith(".pdf"):
+        name = name[:-4]
+    name = name.strip().strip(".")
+    return name[:200] or "attachment"
+
+
+def _allocate_filename(source_name: str, used_names: set[str]) -> str:
+    """Choose an unused PDF basename and add it to used_names."""
+    stem = _safe_stem(source_name)
+    candidate = f"{stem}.pdf"
+    duplicate = 0
+    while candidate in used_names:
+        duplicate += 1
+        candidate = f"{stem} ({duplicate}).pdf"
+    used_names.add(candidate)
+    return candidate
+
+
+def _download_pdf(url: str, destination: Path) -> None:
+    """Download a PDF with filename, byte-count, and transfer-speed feedback."""
+    filename = f"{_safe_stem(unquote(urlparse(url).path))}.pdf"
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[bold blue]Downloading"),
+            TextColumn("{task.description}", markup=False),
+            FileSizeColumn(),
+            TransferSpeedColumn(),
+            transient=True,
+        ) as progress:
+            if not progress.console.is_interactive:
+                progress.console.print(f"Downloading {filename}", markup=False, highlight=False)
+            task = progress.add_task(filename, total=None)
+            with requests.get(
+                url,
+                stream=True,
+                allow_redirects=True,
+                timeout=_REQUEST_TIMEOUT,
+            ) as response:
+                response.raise_for_status()
+                content_length = response.headers.get("content-length")
+                if content_length is not None:
+                    try:
+                        declared_size = int(content_length)
+                    except ValueError:
+                        declared_size = None
+                    if declared_size is not None and declared_size > MAX_PDF_ATTACHMENT_BYTES:
+                        raise AttachmentError(
+                            f"attachment {url!r} exceeds the {MAX_PDF_ATTACHMENT_MIB} MiB PDF limit"
+                        )
+
+                downloaded = 0
+                with destination.open("wb") as file:
+                    for chunk in response.iter_content(chunk_size=_DOWNLOAD_CHUNK_SIZE):
+                        if not chunk:
+                            continue
+                        downloaded += len(chunk)
+                        if downloaded > MAX_PDF_ATTACHMENT_BYTES:
+                            raise AttachmentError(
+                                f"attachment {url!r} exceeds the {MAX_PDF_ATTACHMENT_MIB} MiB PDF limit"
+                            )
+                        file.write(chunk)
+                        progress.update(task, completed=downloaded)
+    except AttachmentError:
+        raise
+    except (OSError, requests.RequestException) as error:
+        raise AttachmentError(f"attachment {url!r} could not be downloaded: {error}") from error
+
+    progress.console.print(
+        f"[bold green]✓[/bold green] Downloaded {escape(filename)} "
+        f"({filesize.decimal(downloaded)})",
+        highlight=False,
+    )
+
+
+def _local_pdfs(configured_path: str) -> list[Path]:
+    """Resolve a local file or recursively select directory PDFs in path order."""
+    expanded = os.path.expandvars(os.path.expanduser(configured_path))
+    path = Path(os.path.abspath(expanded))
+    if path.is_file():
+        return [path]
+    if path.is_dir():
+        pdfs = sorted(
+            (
+                candidate
+                for candidate in path.rglob("*")
+                if candidate.is_file() and candidate.suffix.lower() == ".pdf"
+            ),
+            key=lambda candidate: candidate.relative_to(path).as_posix(),
+        )
+        if pdfs:
+            return pdfs
+        raise AttachmentError(f"attachment directory {configured_path!r} contains no PDF files")
+    raise AttachmentError(f"attachment path {configured_path!r} does not exist")
+
+
+@contextlib.contextmanager
+def prepare_attachments(configured_sources: list[str]) -> Iterator[list[ArchiveEntry]]:
+    """Yield validated PDF archive entries and clean up temporary downloads.
+
+    Sources have already passed syntax validation in PromptConfig.
+    Local files are read in place and left unchanged. All source failures are
+    reported together before yielding entries to the uploader.
+    """
+    if not configured_sources:
+        yield []
+        return
+
+    with tempfile.TemporaryDirectory(prefix="hive-attachments-") as temp_dir:
+        temp_path = Path(temp_dir)
+        entries: list[ArchiveEntry] = []
+        used_names: set[str] = set()
+        failures: list[str] = []
+
+        for source_index, configured_source in enumerate(configured_sources):
+            try:
+                if configured_source.lower().startswith(("http://", "https://")):
+                    downloaded_path = temp_path / f"download-{source_index}.pdf"
+                    _download_pdf(configured_source, downloaded_path)
+                    source_paths = [downloaded_path]
+                    source_names = [unquote(urlparse(configured_source).path)]
+                    validation_sources = [configured_source]
+                else:
+                    source_paths = _local_pdfs(configured_source)
+                    source_names = [path.name for path in source_paths]
+                    expanded = Path(
+                        os.path.abspath(os.path.expandvars(os.path.expanduser(configured_source)))
+                    )
+                    if expanded.is_dir():
+                        validation_sources = [
+                            f"{configured_source.rstrip('/')}/{path.relative_to(expanded).as_posix()}"
+                            for path in source_paths
+                        ]
+                    else:
+                        validation_sources = [configured_source]
+            except AttachmentError as error:
+                failures.append(str(error))
+                continue
+
+            for source_path, source_name, validation_source in zip(
+                source_paths, source_names, validation_sources, strict=True
+            ):
+                try:
+                    _validate_pdf(source_path, validation_source)
+                except AttachmentError as error:
+                    failures.append(str(error))
+                    continue
+                filename = _allocate_filename(source_name, used_names)
+                entries.append(
+                    ArchiveEntry(
+                        source_path=str(source_path),
+                        archive_name=f"{RESOURCES_DIR}/{filename}",
+                    )
+                )
+
+        if failures:
+            details = "\n".join(f"  - {failure}" for failure in failures)
+            raise AttachmentError(f"The following attachments could not be prepared:\n{details}")
+
+        yield entries

{hivekit-0.8.1 → hivekit-0.8.2}/src/cli/utils/config_paths.py

@@ -29,14 +29,6 @@ def get_config_path() -> str:
     return os.path.join(get_config_dir(), "config.yaml")
 
 
-def get_coordinator_overlay_path() -> str:
-    """
-    Return the path of the file ``hivectl generate config`` records the
-    coordinator image tag in, which experiment configs fall back to.
-    """
-    return os.path.join(get_config_dir(), "coordinator.yaml")
-
-
 def load_organization_id() -> str:
     """Load the organization ID from ~/.hive/config.yaml."""
     config_path = get_config_path()