agent-plugins 0.2.0__tar.gz → 0.2.2__tar.gz

agent_plugins-0.2.2/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: agent-plugins
+Version: 0.2.2
+Summary: Ship Agent Plugins with Python packages and inspect their installed files
+Author: Péter Ferenc Gyarmati
+Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: tomli>=1.0.3 ; python_full_version < '3.11'
+Requires-Python: >=3.10, <3.15
+Project-URL: Documentation, https://peter-gy.github.io/agent-plugins/
+Project-URL: Issues, https://github.com/peter-gy/agent-plugins/issues
+Project-URL: Source, https://github.com/peter-gy/agent-plugins
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg">
+    <img alt="agent-plugins" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg" width="430">
+  </picture>
+</p>
+
+<p align="center">
+  Ship Agent Plugins with Python packages.
+</p>
+
+<p align="center">
+  <a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
+  <a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
+  <a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
+  <a href="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/peter-gy/agent-plugins/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/pypi/l/agent-plugins"></a>
+</p>
+
+`agent-plugins` ships a Python library and its agent integrations in one package. An agent with Python execution can read its packaged instructions, then use the library in the same environment. Library code, skills, tool configuration, and resources share one release.
+
+The [Agent Plugins format](https://agent-plugins.org/) defines the directory: a manifest, [Agent Skills](https://agentskills.io/specification) for instructions and resources, [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) server configuration for tools, and client extensions. This library packages that directory and makes it discoverable through Python metadata. Agent clients choose which components to activate.
+
+## Package your plugin
+
+Keep `plugin.json` and `skills/` beside your code. For a project using the [uv build backend](https://docs.astral.sh/uv/concepts/build-backend/), configure `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["agent-plugins", "uv_build"]
+build-backend = "agent_plugins.build.uv_build"
+
+[tool.agent-plugins]
+root = "."
+```
+
+Build with the [uv package manager](https://docs.astral.sh/uv/):
+
+```console
+uv build
+```
+
+The [quickstart](https://peter-gy.github.io/agent-plugins/guide/getting-started) creates a complete project, builds it, and locates the installed plugin. Use the [Hatchling adapter](https://peter-gy.github.io/agent-plugins/guide/build-backends#hatchling) for Hatchling projects, or [attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) when another tool owns the build:
+
+```console
+agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
+```
+
+Attachment updates the wheel in place. Pass `--output-dir` to preserve the input.
+
+## Inspect an installed plugin
+
+Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
+
+```console
+pip install agent-plugins
+```
+
+```python
+import agent_plugins as ap
+
+plugin = ap.locate("agent-plugins")
+skill = plugin.skill("agent-plugins")
+
+print(skill.source)
+print(skill.file("SKILL.md"))
+```
+
+Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
+
+## Documentation
+
+- [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started): package, install, and locate a plugin.
+- [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle): wheels, source distributions, and editable installs.
+- [Integrate](https://peter-gy.github.io/agent-plugins/guide/inspect-installed): read skills, inspect files, and resolve MCP configuration.
+- [Python API](https://peter-gy.github.io/agent-plugins/reference/python-api) · [CLI](https://peter-gy.github.io/agent-plugins/reference/cli) · [Configuration](https://peter-gy.github.io/agent-plugins/reference/pyproject)
+
+<details>
+<summary>Packaging lifecycle</summary>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg">
+    <img alt="Core model: an authored Python project builds into one wheel that installs the library beside its version-matched Agent Plugin, which locate() returns as a plugin handle" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg" width="300">
+  </picture>
+</p>
+
+</details>
+
+## Development
+
+See [development_docs/](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) for setup, architecture, checks, and releases. Serve the documentation locally with `pnpm --dir docs dev`.
+
+## License
+
+[Apache-2.0](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).

agent_plugins-0.2.2/README.md

@@ -0,0 +1,103 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg">
+    <img alt="agent-plugins" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg" width="430">
+  </picture>
+</p>
+
+<p align="center">
+  Ship Agent Plugins with Python packages.
+</p>
+
+<p align="center">
+  <a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
+  <a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
+  <a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
+  <a href="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/peter-gy/agent-plugins/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/pypi/l/agent-plugins"></a>
+</p>
+
+`agent-plugins` ships a Python library and its agent integrations in one package. An agent with Python execution can read its packaged instructions, then use the library in the same environment. Library code, skills, tool configuration, and resources share one release.
+
+The [Agent Plugins format](https://agent-plugins.org/) defines the directory: a manifest, [Agent Skills](https://agentskills.io/specification) for instructions and resources, [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) server configuration for tools, and client extensions. This library packages that directory and makes it discoverable through Python metadata. Agent clients choose which components to activate.
+
+## Package your plugin
+
+Keep `plugin.json` and `skills/` beside your code. For a project using the [uv build backend](https://docs.astral.sh/uv/concepts/build-backend/), configure `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["agent-plugins", "uv_build"]
+build-backend = "agent_plugins.build.uv_build"
+
+[tool.agent-plugins]
+root = "."
+```
+
+Build with the [uv package manager](https://docs.astral.sh/uv/):
+
+```console
+uv build
+```
+
+The [quickstart](https://peter-gy.github.io/agent-plugins/guide/getting-started) creates a complete project, builds it, and locates the installed plugin. Use the [Hatchling adapter](https://peter-gy.github.io/agent-plugins/guide/build-backends#hatchling) for Hatchling projects, or [attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) when another tool owns the build:
+
+```console
+agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
+```
+
+Attachment updates the wheel in place. Pass `--output-dir` to preserve the input.
+
+## Inspect an installed plugin
+
+Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
+
+```console
+pip install agent-plugins
+```
+
+```python
+import agent_plugins as ap
+
+plugin = ap.locate("agent-plugins")
+skill = plugin.skill("agent-plugins")
+
+print(skill.source)
+print(skill.file("SKILL.md"))
+```
+
+Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
+
+## Documentation
+
+- [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started): package, install, and locate a plugin.
+- [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle): wheels, source distributions, and editable installs.
+- [Integrate](https://peter-gy.github.io/agent-plugins/guide/inspect-installed): read skills, inspect files, and resolve MCP configuration.
+- [Python API](https://peter-gy.github.io/agent-plugins/reference/python-api) · [CLI](https://peter-gy.github.io/agent-plugins/reference/cli) · [Configuration](https://peter-gy.github.io/agent-plugins/reference/pyproject)
+
+<details>
+<summary>Packaging lifecycle</summary>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg">
+    <img alt="Core model: an authored Python project builds into one wheel that installs the library beside its version-matched Agent Plugin, which locate() returns as a plugin handle" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg" width="300">
+  </picture>
+</p>
+
+</details>
+
+## Development
+
+See [development_docs/](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) for setup, architecture, checks, and releases. Serve the documentation locally with `pnpm --dir docs dev`.
+
+## License
+
+[Apache-2.0](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).

{agent_plugins-0.2.0 → agent_plugins-0.2.2}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "agent-plugins"
-version = "0.2.0"
+version = "0.2.2"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 requires-python = ">=3.10,<3.15"
-dependencies = ["tomli==2.3.1; python_version < '3.11'"]
+dependencies = ["tomli>=1.0.3; python_version < '3.11'"]
 classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -30,7 +30,7 @@ agent-plugins = "agent_plugins._cli:main"
 
 [build-system]
 requires = [
-    "tomli==2.3.1; python_version < '3.11'",
+    "tomli>=1.0.3; python_version < '3.11'",
     "uv_build==0.12.2",
 ]
 build-backend = "agent_plugins.build.uv_build"

{agent_plugins-0.2.0 → agent_plugins-0.2.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugins"
-version = "0.2.0"
+version = "0.2.2"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
@@ -10,7 +10,7 @@ authors = [
 ]
 requires-python = ">=3.10,<3.15"
 dependencies = [
-    "tomli==2.3.1; python_version < '3.11'",
+    "tomli>=1.0.3; python_version < '3.11'",
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
@@ -31,7 +31,7 @@ agent-plugins = "agent_plugins._cli:main"
 
 [build-system]
 requires = [
-    "tomli==2.3.1; python_version < '3.11'",
+    "tomli>=1.0.3; python_version < '3.11'",
     "uv_build==0.12.2",
 ]
 build-backend = "agent_plugins.build.uv_build"

{agent_plugins-0.2.0 → agent_plugins-0.2.2}/src/agent_plugins/_build/plan.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import sys
 from dataclasses import dataclass
-from pathlib import Path, PurePosixPath
+from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import cast
 
 if sys.version_info >= (3, 11):
@@ -38,7 +38,7 @@ def build_plan(project: str | Path = ".") -> BuildPlan:
     """Load project configuration and return its complete plugin file plan."""
     try:
         project_path = Path(project).resolve()
-    except (OSError, RuntimeError) as error:
+    except (OSError, RuntimeError, ValueError) as error:
         raise AgentPluginError(
             f"Project path cannot be resolved: {project}. Check the path and retry."
         ) from error
@@ -63,10 +63,11 @@ def build_plan(project: str | Path = ".") -> BuildPlan:
 
     staged = project_path / STAGED_ROOT
     configured = project_path / root_value
-    source_root = staged if (staged / "plugin.json").is_file() else configured
+    is_staged = (staged / "plugin.json").is_file()
+    source_root = staged if is_staged else configured
     try:
         root = source_root.resolve(strict=True)
-    except (OSError, RuntimeError) as error:
+    except (OSError, RuntimeError, ValueError) as error:
         raise AgentPluginError(
             f"Agent Plugin root cannot be resolved: {source_root}"
         ) from error
@@ -75,10 +76,13 @@ def build_plan(project: str | Path = ".") -> BuildPlan:
 
     files: dict[PurePosixPath, Path] = {}
     _add_file(files, root, root / "plugin.json", required=True)
-    _add_tree(files, root, root / "skills")
-    _add_file(files, root, root / "mcp.json", required=False)
-    for pattern in include:
-        _add_pattern(files, root, pattern)
+    if is_staged:
+        _add_tree(files, root, root)
+    else:
+        _add_tree(files, root, root / "skills")
+        _add_file(files, root, root / "mcp.json", required=False)
+        for pattern in include:
+            _add_pattern(files, root, pattern)
 
     mappings = tuple(
         FileMapping(source=source, target=target)
@@ -87,6 +91,58 @@ def build_plan(project: str | Path = ".") -> BuildPlan:
     return BuildPlan(project=project_path, root=root, files=mappings)
 
 
+def validate_plan(plan: BuildPlan) -> tuple[PurePosixPath, ...]:
+    """Check that a plan can produce a discoverable plugin payload."""
+    files: list[PurePosixPath] = []
+    seen: set[PurePosixPath] = set()
+    for mapping in plan.files:
+        target = mapping.target
+        value = target.as_posix()
+        if (
+            target.is_absolute()
+            or PureWindowsPath(value).drive
+            or not target.parts
+            or ".." in target.parts
+            or "\\" in value
+            or "\x00" in value
+        ):
+            raise AgentPluginError(
+                f"Plugin target must stay within the plugin root: {value!r}"
+            )
+        if target in seen:
+            raise AgentPluginError(f"Plugin plan contains a duplicate target: {value}")
+        collision = next(
+            (
+                existing
+                for existing in seen
+                if existing in target.parents or target in existing.parents
+            ),
+            None,
+        )
+        if collision is not None:
+            raise AgentPluginError(
+                "Plugin plan contains file-directory target collisions: "
+                f"{collision.as_posix()} and {value}"
+            )
+        seen.add(target)
+        try:
+            source = mapping.source.resolve(strict=True)
+        except (OSError, RuntimeError, ValueError) as error:
+            raise AgentPluginError(
+                f"Plugin file cannot be read: {mapping.source}. "
+                "Restore the file and retry."
+            ) from error
+        if not source.is_file():
+            raise AgentPluginError(
+                f"Plugin source is not a file: {source}. "
+                "Select a regular file and retry."
+            )
+        files.append(target)
+    if PurePosixPath("plugin.json") not in seen:
+        raise AgentPluginError("Plugin plan must include plugin.json")
+    return tuple(files)
+
+
 def _config(document: dict[str, object], pyproject: Path) -> dict[str, object]:
     tool = document.get("tool")
     if not isinstance(tool, dict):
@@ -133,6 +189,8 @@ def _add_tree(files: dict[PurePosixPath, Path], root: Path, directory: Path) ->
         return
     if not directory.is_dir():
         raise AgentPluginError(f"Expected a directory: {directory}")
+    if directory.is_symlink():
+        raise AgentPluginError(f"Directory symlinks cannot be packaged: {directory}")
     for candidate in directory.rglob("*"):
         if candidate.is_symlink() and candidate.is_dir():
             raise AgentPluginError(

{agent_plugins-0.2.0 → agent_plugins-0.2.2}/src/agent_plugins/_build/sdist.py

@@ -35,7 +35,7 @@ def _rewrite(source_path: Path, target_path: Path, plan: BuildPlan) -> None:
     with tarfile.open(source_path, "r:gz") as source:
         members = source.getmembers()
         root = _archive_root(members)
-        stage = f"{root}/{STAGED_ROOT}"
+        stage = PurePosixPath(root, STAGED_ROOT)
 
         with (
             target_path.open("wb") as raw_target,
@@ -47,7 +47,7 @@ def _rewrite(source_path: Path, target_path: Path, plan: BuildPlan) -> None:
             ) as target,
         ):
             for member in members:
-                if member.name == stage or member.name.startswith(f"{stage}/"):
+                if PurePosixPath(member.name).is_relative_to(stage):
                     continue
                 file_object = source.extractfile(member) if member.isfile() else None
                 try:

agent_plugins-0.2.2/src/agent_plugins/_build/wheel.py

@@ -0,0 +1,239 @@
+"""Attach Agent Plugin payloads to wheel artifacts."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import tempfile
+import zipfile
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from .._errors import AgentPluginError
+from .plan import BuildPlan, build_plan, validate_plan
+from .wheel_archive import rewrite_wheel
+
+
+@dataclass(frozen=True, slots=True)
+class WheelAttachment:
+    """Describe an Agent Plugin attached to a wheel."""
+
+    source: Path
+    output: Path
+    dist_info: PurePosixPath
+    plugin_root: PurePosixPath
+    files: tuple[PurePosixPath, ...]
+    replaced_existing_plugin: bool
+    removed_signatures: tuple[PurePosixPath, ...]
+
+
+def attach_wheel(
+    wheel: str | Path,
+    *,
+    project: str | Path | None = None,
+    plan: BuildPlan | None = None,
+    output_dir: str | Path | None = None,
+) -> WheelAttachment:
+    """Attach a planned Agent Plugin to one existing wheel."""
+    if project is not None and plan is not None:
+        raise AgentPluginError(
+            "Pass either project or plan to attach_wheel(), not both"
+        )
+
+    source, source_mode = _resolve_wheel(wheel)
+    output = _resolve_output(source, output_dir)
+    selected_plan = plan if plan is not None else build_plan(project or Path.cwd())
+    files = validate_plan(selected_plan)
+
+    temporary = _temporary_wheel(output)
+    try:
+        try:
+            layout = rewrite_wheel(
+                source,
+                temporary,
+                plan=selected_plan,
+                editable_root=None,
+            )
+            temporary.chmod(source_mode)
+            _publish(temporary, output, in_place=output == source)
+        except AgentPluginError:
+            raise
+        except zipfile.BadZipFile as error:
+            raise AgentPluginError(
+                f"Wheel is corrupt: {source}. Rebuild the wheel and retry."
+            ) from error
+        except zipfile.LargeZipFile as error:
+            raise AgentPluginError(
+                f"Wheel exceeds the supported ZIP limits: {source}. "
+                "Rebuild the wheel with ZIP64 support and retry."
+            ) from error
+        except NotImplementedError as error:
+            raise AgentPluginError(
+                f"Wheel uses unsupported ZIP compression: {source}. "
+                "Rebuild the wheel with a supported compression method and retry."
+            ) from error
+        except OSError as error:
+            raise AgentPluginError(
+                f"Cannot write attached wheel: {output}. "
+                "Check file access and available space, then retry."
+            ) from error
+    finally:
+        with suppress(OSError):
+            temporary.unlink(missing_ok=True)
+
+    return WheelAttachment(
+        source=source,
+        output=output,
+        dist_info=layout.dist_info,
+        plugin_root=layout.plugin_root,
+        files=files,
+        replaced_existing_plugin=layout.replaced_existing_plugin,
+        removed_signatures=layout.removed_signatures,
+    )
+
+
+def _attach_editable_wheel(wheel: Path, plan: BuildPlan) -> None:
+    """Attach an authored-root marker to an editable wheel."""
+    source, source_mode = _resolve_wheel(wheel)
+    validate_plan(plan)
+    temporary = _temporary_wheel(source)
+    try:
+        try:
+            rewrite_wheel(source, temporary, plan=plan, editable_root=plan.root)
+            temporary.chmod(source_mode)
+            temporary.replace(source)
+        except AgentPluginError:
+            raise
+        except zipfile.BadZipFile as error:
+            raise AgentPluginError(
+                f"Wheel is corrupt: {source}. Rebuild the wheel and retry."
+            ) from error
+        except (zipfile.LargeZipFile, NotImplementedError) as error:
+            raise AgentPluginError(
+                f"Wheel uses an unsupported ZIP format: {source}. "
+                "Rebuild the wheel and retry."
+            ) from error
+        except OSError as error:
+            raise AgentPluginError(
+                f"Cannot write editable wheel: {source}. "
+                "Check file access and available space, then retry."
+            ) from error
+    finally:
+        with suppress(OSError):
+            temporary.unlink(missing_ok=True)
+
+
+def _resolve_wheel(wheel: str | Path) -> tuple[Path, int]:
+    candidate = Path(wheel).expanduser()
+    if candidate.suffix != ".whl":
+        raise AgentPluginError(
+            f"Wheel path must end in .whl: {candidate}. Select a built wheel and retry."
+        )
+    try:
+        path = candidate.resolve(strict=True)
+        metadata = path.stat()
+    except (OSError, RuntimeError, ValueError) as error:
+        raise AgentPluginError(
+            f"Wheel cannot be read: {candidate}. "
+            "Check the path and file access, then retry."
+        ) from error
+    if not path.is_file():
+        raise AgentPluginError(
+            f"Wheel path is not a file: {path}. Select a built wheel and retry."
+        )
+    return path, stat.S_IMODE(metadata.st_mode)
+
+
+def _resolve_output(source: Path, output_dir: str | Path | None) -> Path:
+    if output_dir is None:
+        return source
+    candidate = Path(output_dir).expanduser()
+    try:
+        directory = candidate.resolve(strict=True)
+    except (OSError, RuntimeError, ValueError) as error:
+        raise AgentPluginError(
+            f"Output directory cannot be used: {candidate}. "
+            "Create the directory and check its access, then retry."
+        ) from error
+    if not directory.is_dir():
+        raise AgentPluginError(
+            f"Output directory is not a directory: {directory}. "
+            "Select an existing directory and retry."
+        )
+    output = directory / source.name
+    if output.exists() or output.is_symlink():
+        raise AgentPluginError(
+            f"Output wheel already exists: {output}. "
+            "Remove it or select another output directory."
+        )
+    return output
+
+
+def _temporary_wheel(output: Path) -> Path:
+    try:
+        with tempfile.NamedTemporaryFile(
+            dir=output.parent,
+            prefix=f".{output.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary:
+            return Path(temporary.name)
+    except OSError as error:
+        raise AgentPluginError(
+            f"Cannot create a temporary wheel in {output.parent}. "
+            "Check directory access and available space, then retry."
+        ) from error
+
+
+def _publish(temporary: Path, output: Path, *, in_place: bool) -> None:
+    if in_place:
+        temporary.replace(output)
+        return
+    try:
+        os.link(temporary, output)
+    except FileExistsError as error:
+        raise AgentPluginError(
+            f"Output wheel already exists: {output}. "
+            "Remove it or select another output directory."
+        ) from error
+    except OSError:
+        _publish_reserved(temporary, output)
+
+
+def _publish_reserved(temporary: Path, output: Path) -> None:
+    descriptor: int | None = None
+    try:
+        mode = stat.S_IMODE(temporary.stat().st_mode)
+        descriptor = os.open(output, os.O_CREAT | os.O_EXCL | os.O_WRONLY, mode)
+        if os.name != "nt":
+            os.fchmod(descriptor, mode)
+        with (
+            temporary.open("rb") as source,
+            os.fdopen(descriptor, "wb", closefd=False) as target,
+        ):
+            shutil.copyfileobj(source, target, length=1024 * 1024)
+            target.flush()
+            os.fsync(descriptor)
+        if not os.path.samestat(os.fstat(descriptor), output.lstat()):
+            raise AgentPluginError(
+                f"Output wheel changed during publication: {output}. "
+                "Inspect the destination and retry."
+            )
+    except FileExistsError as error:
+        raise AgentPluginError(
+            f"Output wheel already exists: {output}. "
+            "Remove it or select another output directory."
+        ) from error
+    except AgentPluginError:
+        raise
+    except OSError as error:
+        raise AgentPluginError(
+            f"Cannot publish attached wheel: {output}. "
+            "Remove an incomplete destination, check file access, and retry."
+        ) from error
+    finally:
+        if descriptor is not None:
+            with suppress(OSError):
+                os.close(descriptor)