agentcore-cli 0.31.1__py3-none-any.whl

agentcore/lib/errors/validation.py

@@ -0,0 +1,121 @@
+"""Human-readable formatting of schema validation issues (port of ``src/lib/errors/zod.ts``).
+
+Upstream formats Zod issues; here the input is Pydantic's ``ValidationError.errors()`` (or
+issue dicts of the same shape: ``type``, ``loc``, ``msg``, optional ``input`` / ``ctx``). The
+output format (``  - path: message`` per line, bracket path notation) matches upstream.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+# Pydantic error type -> the JSON type name Zod would report as "expected".
+_TYPE_NAMES = {
+    "string_type": "string",
+    "int_type": "number",
+    "int_parsing": "number",
+    "int_from_float": "int",
+    "float_type": "number",
+    "float_parsing": "number",
+    "bool_type": "boolean",
+    "bool_parsing": "boolean",
+    "dict_type": "object",
+    "model_type": "object",
+    "model_attributes_type": "object",
+    "list_type": "array",
+    "tuple_type": "array",
+}
+
+_QUOTED = re.compile(r"'((?:[^'\\]|\\.)*)'")
+
+
+def format_path(path: Sequence[Any]) -> str:
+    """Format a location tuple in bracket notation: ``agents[0].name``."""
+    if not path:
+        return "root"
+    out = []
+    for i, segment in enumerate(path):
+        if isinstance(segment, int) and not isinstance(segment, bool):
+            out.append(f"[{segment}]")
+        else:
+            out.append(str(segment) if i == 0 else f".{segment}")
+    return "".join(out)
+
+
+def _expected_options(issue: Mapping[str, Any]) -> list[str] | None:
+    ctx = issue.get("ctx") or {}
+    expected = ctx.get("expected")
+    if isinstance(expected, (list, tuple)):
+        return [str(o) for o in expected]
+    if isinstance(expected, str):
+        found = _QUOTED.findall(expected)
+        if found:
+            return found
+    return None
+
+
+def _format_issue(issue: Mapping[str, Any]) -> str:
+    path = format_path(tuple(issue.get("loc") or ()))
+    kind = issue.get("type", "")
+
+    if kind in _TYPE_NAMES:
+        return f'{path}: expected "{_TYPE_NAMES[kind]}"'
+
+    if kind in ("literal_error", "enum"):
+        options = _expected_options(issue)
+        if options:
+            expected = " | ".join(f'"{o}"' for o in options)
+            if "input" in issue:
+                return f"{path}: got {_json(issue['input'])}, expected {expected}"
+            return f"{path}: expected {expected}"
+
+    if kind in ("union_tag_invalid", "union_tag_not_found"):
+        discriminator = str((issue.get("ctx") or {}).get("discriminator", "")).strip("'")
+        if discriminator:
+            return f'{path}: invalid "{discriminator}" value'
+
+    message = issue.get("msg") or kind or "invalid value"
+    return f"{path}: {message}"
+
+
+def _json(value: Any) -> str:
+    try:
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    except (TypeError, ValueError):
+        return json.dumps(str(value))
+
+
+def format_validation_errors(issues: Iterable[Mapping[str, Any]]) -> str:
+    """Format all issues into a newline-separated ``  - path: message`` list.
+
+    Pydantic reports each forbidden extra key separately; they are grouped per parent object
+    into Zod's single ``unknown keys (remove): "a", "b"`` line.
+    """
+    lines: list[str] = []
+    unknown_by_parent: dict[tuple[Any, ...], list[str]] = {}
+    unknown_line_index: dict[tuple[Any, ...], int] = {}
+
+    for issue in issues:
+        if issue.get("type") == "extra_forbidden" and issue.get("loc"):
+            loc = tuple(issue["loc"])
+            parent, key = loc[:-1], str(loc[-1])
+            if parent not in unknown_by_parent:
+                unknown_by_parent[parent] = []
+                unknown_line_index[parent] = len(lines)
+                lines.append("")
+            unknown_by_parent[parent].append(key)
+            continue
+        lines.append(f"  - {_format_issue(issue)}")
+
+    for parent, keys in unknown_by_parent.items():
+        joined = ", ".join(f'"{k}"' for k in keys)
+        lines[unknown_line_index[parent]] = f"  - {format_path(parent)}: unknown keys (remove): {joined}"
+
+    return "\n".join(lines)
+
+
+# Upstream name, kept for literal ports of call sites.
+format_zod_errors = format_validation_errors

agentcore/lib/packaging/__init__.py

@@ -0,0 +1,81 @@
+"""Deployment artifact packaging (port of ``src/lib/packaging``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentcore.lib.errors.types import PackagingError
+from agentcore.lib.packaging.build_context import ResolvedBuildContext, resolve_build_context
+from agentcore.lib.packaging.build_context_dockerignore import ensure_build_context_dockerignore
+from agentcore.lib.packaging.container import ContainerPackager
+from agentcore.lib.packaging.helpers import is_node_runtime, is_python_runtime, resolve_code_location
+from agentcore.lib.packaging.node import NodeCodeZipPackager
+from agentcore.lib.packaging.python import PythonCodeZipPackager, default_python_version
+from agentcore.lib.packaging.types import (
+    ArtifactResult,
+    CodeBundleConfig,
+    CodeZipPackager,
+    PackageOptions,
+    RuntimePackager,
+    spec_field,
+)
+
+
+def validate_agent_exists(project: Any, agent_name: str) -> None:
+    """Raise ``PackagingError`` unless ``project.runtimes`` contains ``agent_name``."""
+    runtimes = spec_field(project, "runtimes", []) or []
+    if not any(spec_field(a, "name") == agent_name for a in runtimes):
+        available = ", ".join(str(spec_field(a, "name")) for a in runtimes)
+        raise PackagingError(f"Agent '{agent_name}' not found. Available agents: {available}")
+
+
+def get_runtime_packager(runtime_version: str) -> RuntimePackager:
+    if is_python_runtime(runtime_version):
+        return PythonCodeZipPackager()
+    if is_node_runtime(runtime_version):
+        return NodeCodeZipPackager()
+    raise PackagingError(f"Unsupported runtime version: {runtime_version}")
+
+
+def get_code_zip_packager(runtime_version: str) -> CodeZipPackager:
+    if is_python_runtime(runtime_version):
+        return PythonCodeZipPackager()
+    if is_node_runtime(runtime_version):
+        return NodeCodeZipPackager()
+    raise PackagingError(f"Unsupported runtime version: {runtime_version}")
+
+
+def get_container_packager() -> RuntimePackager:
+    return ContainerPackager()
+
+
+def pack_runtime(spec: Any, options: PackageOptions | None = None) -> ArtifactResult:
+    """Package a runtime, choosing the packager from build type and runtime version."""
+    if spec_field(spec, "build") == "Container":
+        return get_container_packager().pack(spec, options)
+    return get_runtime_packager(spec_field(spec, "runtimeVersion")).pack(spec, options)
+
+
+def pack_code_zip_sync(config: Any, options: PackageOptions | None = None) -> ArtifactResult:
+    """Package a CodeZip bundle (defaults to Python when no runtime version is set)."""
+    runtime_version = spec_field(config, "runtimeVersion") or default_python_version()
+    return get_code_zip_packager(runtime_version).pack_code_zip(config, options)
+
+
+__all__ = [
+    "ArtifactResult",
+    "CodeBundleConfig",
+    "CodeZipPackager",
+    "PackageOptions",
+    "ResolvedBuildContext",
+    "RuntimePackager",
+    "ensure_build_context_dockerignore",
+    "get_code_zip_packager",
+    "get_container_packager",
+    "get_runtime_packager",
+    "pack_code_zip_sync",
+    "pack_runtime",
+    "resolve_build_context",
+    "resolve_code_location",
+    "validate_agent_exists",
+]

agentcore/lib/packaging/build_args.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from agentcore.lib.schemas.io.global_config import read_global_config_sync
+
+
+def get_uv_build_args() -> list[str]:
+    """``--build-arg`` flags for UV index URLs configured in ``~/.agentcore/config.json``."""
+    config = read_global_config_sync()
+    args: list[str] = []
+    if config.get("uvDefaultIndex"):
+        args += ["--build-arg", f"UV_DEFAULT_INDEX={config['uvDefaultIndex']}"]
+    if config.get("uvIndex"):
+        args += ["--build-arg", f"UV_INDEX={config['uvIndex']}"]
+    return args
+
+
+def get_custom_build_args(custom_docker_build_args: Mapping[str, str] | None = None) -> list[str]:
+    """``--build-arg KEY=VALUE`` flags for an agent's ``customDockerBuildArgs``."""
+    return [
+        part for key, value in (custom_docker_build_args or {}).items() for part in ("--build-arg", f"{key}={value}")
+    ]

agentcore/lib/packaging/build_context.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib.constants import get_dockerfile_path
+from agentcore.lib.packaging.helpers import resolve_code_location
+from agentcore.lib.packaging.types import spec_field
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedBuildContext:
+    # Absolute Docker build context (buildContextPath when set, else codeLocation).
+    build_context: str
+    # Absolute Dockerfile path, resolved against the build context.
+    dockerfile_path: str
+
+
+def resolve_build_context(spec: Any, base_dir: str) -> ResolvedBuildContext:
+    """Single resolver for a Container agent's build context + Dockerfile, shared by package/deploy/dev."""
+    location = spec_field(spec, "buildContextPath") or spec_field(spec, "codeLocation")
+    build_context = resolve_code_location(location, base_dir)
+    return ResolvedBuildContext(
+        build_context=build_context,
+        dockerfile_path=get_dockerfile_path(build_context, spec_field(spec, "dockerfile")),
+    )

agentcore/lib/packaging/build_context_dockerignore.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import os
+
+# Written at a Container agent's build-context root when buildContextPath is set and none exists.
+BUILD_CONTEXT_DOCKERIGNORE_TEMPLATE = """# Generated by agentcore because this agent sets buildContextPath — the whole of this directory is the
+# Docker build context, so secrets/junk here would otherwise be baked into the image and uploaded to
+# CodeBuild. Patterns are listed both bare and '**/'-prefixed so nested copies (e.g.
+# app/agent-one/node_modules, app/agent-one/.env) are excluded too, not just the top level — Docker
+# matches .dockerignore patterns root-relative. Both 'agentcore dev'/'package' and 'agentcore deploy'
+# honor this file. Edit freely; to intentionally include a file listed here (e.g. a non-secret
+# .env.production), add a '!'-prefixed line for it below.
+.env
+.env.*
+**/.env
+**/.env.*
+.git
+**/.git
+.venv
+**/.venv
+node_modules
+**/node_modules
+__pycache__
+**/__pycache__
+.pytest_cache
+**/.pytest_cache
+.DS_Store
+**/.DS_Store
+agentcore/
+"""
+
+
+def ensure_build_context_dockerignore(resolved_build_context: str) -> str | None:
+    """Create ``.dockerignore`` at the build-context root unless the dir is missing or one exists.
+
+    Returns the created path, else ``None``. A user's existing file is never overwritten.
+    """
+    if not os.path.exists(resolved_build_context):
+        return None
+    path = os.path.join(resolved_build_context, ".dockerignore")
+    if os.path.exists(path):
+        return None
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(BUILD_CONTEXT_DOCKERIGNORE_TEMPLATE)
+    return path

agentcore/lib/packaging/container.py

@@ -0,0 +1,95 @@
+"""Container packager (port of ``packaging/container.ts``): local image build + 1GB size check."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import Any
+
+from agentcore.lib.constants import CONTAINER_RUNTIMES, DOCKERFILE_NAME, ONE_GB
+from agentcore.lib.errors.types import PackagingError
+from agentcore.lib.packaging.build_args import get_custom_build_args, get_uv_build_args
+from agentcore.lib.packaging.build_context import resolve_build_context
+from agentcore.lib.packaging.build_context_dockerignore import ensure_build_context_dockerignore
+from agentcore.lib.packaging.helpers import resolve_code_location
+from agentcore.lib.packaging.types import ArtifactResult, PackageOptions, spec_field
+
+
+def _run(args: list[str]) -> subprocess.CompletedProcess[bytes] | None:
+    try:
+        return subprocess.run(args, stdin=subprocess.DEVNULL, capture_output=True)
+    except OSError:
+        return None
+
+
+def detect_container_runtime() -> str | None:
+    """First runtime in CONTAINER_RUNTIMES order that ``which`` finds and that answers ``--version``."""
+    for runtime in CONTAINER_RUNTIMES:
+        found = _run(["which", runtime])
+        if found is not None and found.returncode == 0:
+            version = _run([runtime, "--version"])
+            if version is not None and version.returncode == 0:
+                return runtime
+    return None
+
+
+class ContainerPackager:
+    def pack(self, spec: Any, options: PackageOptions | None = None) -> ArtifactResult:
+        options = options or PackageOptions()
+        if spec_field(spec, "build") != "Container":
+            raise PackagingError("ContainerPackager only supports Container build type.")
+
+        agent_name = options.agent_name or spec_field(spec, "name")
+        config_base_dir = options.artifact_dir or options.project_root or os.getcwd()
+        code_location = resolve_code_location(spec_field(spec, "codeLocation"), config_base_dir)
+        resolved = resolve_build_context(spec, config_base_dir)
+
+        if not os.path.exists(resolved.dockerfile_path):
+            raise PackagingError(
+                f"{spec_field(spec, 'dockerfile') or DOCKERFILE_NAME} not found at {resolved.dockerfile_path}. "
+                "Container agents require a Dockerfile."
+            )
+
+        # Dockerfile validated: when buildContextPath widens the context, keep secrets/junk out.
+        if spec_field(spec, "buildContextPath"):
+            ensure_build_context_dockerignore(resolved.build_context)
+
+        runtime = detect_container_runtime()
+        if not runtime:
+            # No local runtime: skip local build validation (deploy uses CodeBuild).
+            return ArtifactResult(artifact_path="", size_bytes=0, staging_path=code_location)
+
+        # Image tags must be lowercase; agent names may not be.
+        image_name = f"agentcore-package-{agent_name}".lower()
+        build = _run(
+            [
+                runtime,
+                "build",
+                "-t",
+                image_name,
+                "-f",
+                resolved.dockerfile_path,
+                *get_uv_build_args(),
+                *get_custom_build_args(spec_field(spec, "customDockerBuildArgs")),
+                resolved.build_context,
+            ]
+        )
+        if build is None or build.returncode != 0:
+            stderr = build.stderr.decode("utf-8", errors="replace") if build is not None else ""
+            raise PackagingError(f"Container build failed:\n{stderr}")
+
+        inspect = _run([runtime, "image", "inspect", image_name, "--format", "{{.Size}}"])
+        try:
+            size_bytes = int((inspect.stdout.decode().strip() if inspect else "") or "0")
+        except ValueError:
+            size_bytes = 0
+        if size_bytes > ONE_GB:
+            size_mb = f"{size_bytes / (1024 * 1024):.2f}"
+            raise PackagingError(
+                f"Container image exceeds 1GB limit ({size_mb}MB). "
+                "Optimize your Dockerfile: use multi-stage builds, minimize dependencies, add .dockerignore."
+            )
+
+        return ArtifactResult(
+            artifact_path=f"{runtime}://{image_name}", size_bytes=size_bytes, staging_path=code_location
+        )

agentcore/lib/packaging/helpers.py

@@ -0,0 +1,289 @@
+"""Shared packaging helpers (port of ``packaging/helpers.ts``)."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import zipfile
+from dataclasses import dataclass
+
+from agentcore.lib.constants import CONFIG_DIR
+from agentcore.lib.errors.types import ArtifactSizeError, MissingDependencyError, MissingProjectFileError
+from agentcore.lib.packaging.types import PackageOptions
+from agentcore.lib.utils.platform import is_windows
+from agentcore.lib.utils.subprocess import check_subprocess, run_subprocess
+
+MAX_ZIP_SIZE_BYTES = 250 * 1024 * 1024
+
+_EXCLUDED_ENTRIES = frozenset({".git", ".venv", "__pycache__", ".pytest_cache", ".DS_Store", "node_modules"})
+
+
+def is_python_runtime(runtime_version: str) -> bool:
+    return runtime_version.startswith("PYTHON_")
+
+
+def is_node_runtime(runtime_version: str) -> bool:
+    return runtime_version.startswith("NODE_")
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedPaths:
+    project_root: str
+    src_dir: str
+    # For Node projects this points at package.json.
+    pyproject_path: str
+    artifact_dir: str
+    build_dir: str
+    staging_dir: str
+    artifacts_dir: str
+
+
+def _is_env_secret_entry(name: str) -> bool:
+    """``.env`` / ``.env.local`` / ``.env.*``: per-environment secrets, excluded at every depth."""
+    return name in (".env", ".env.local") or name.startswith(".env.")
+
+
+def _should_exclude_entry(name: str, source: str, root_dir: str) -> bool:
+    """Copy-stage filter. The project's ``agentcore/`` dir is skipped only at the source root, so
+    an in-tree dependency shipping its own ``agentcore/`` package is still packaged."""
+    if name in _EXCLUDED_ENTRIES:
+        return True
+    if name == CONFIG_DIR and os.path.abspath(source) == os.path.abspath(root_dir):
+        return True
+    return _is_env_secret_entry(name)
+
+
+def _is_zip_excluded_entry(name: str) -> bool:
+    """Zip-stage filter. A top-level ``agentcore/`` in staging is a real package, so it's kept."""
+    return name in _EXCLUDED_ENTRIES or _is_env_secret_entry(name)
+
+
+def resolve_code_location(code_location: str, config_base_dir: str) -> str:
+    """Resolve a ``codeLocation`` relative to the repository root (parent of ``agentcore/``)."""
+    if os.path.isabs(code_location):
+        return code_location
+    return os.path.abspath(os.path.join(os.path.dirname(config_base_dir), code_location))
+
+
+def _find_up(file_name: str, start_dir: str) -> str | None:
+    current = os.path.abspath(start_dir)
+    while True:
+        candidate = os.path.join(current, file_name)
+        if os.path.exists(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def _derive_paths(project_root: str, manifest: str, options: PackageOptions, agent_name: str | None) -> ResolvedPaths:
+    src_dir = os.path.abspath(os.path.join(project_root, options.src_dir or "."))
+    artifact_dir = os.path.abspath(options.artifact_dir or os.path.join(project_root, CONFIG_DIR))
+    # Staging layout: <artifactDir>/<name>/staging
+    build_dir = os.path.join(artifact_dir, agent_name or "default")
+    return ResolvedPaths(
+        project_root=project_root,
+        src_dir=src_dir,
+        pyproject_path=manifest,
+        artifact_dir=artifact_dir,
+        build_dir=build_dir,
+        staging_dir=os.path.join(build_dir, "staging"),
+        artifacts_dir=artifact_dir,
+    )
+
+
+def resolve_project_paths(options: PackageOptions | None = None, agent_name: str | None = None) -> ResolvedPaths:
+    """Paths for a Python project, locating ``pyproject.toml`` (explicit or nearest ancestor)."""
+    options = options or PackageOptions()
+    start_dir = os.path.abspath(options.project_root) if options.project_root else os.getcwd()
+    candidate = (
+        os.path.abspath(options.pyproject_path) if options.pyproject_path else _find_up("pyproject.toml", start_dir)
+    )
+    if not candidate or not os.path.exists(candidate):
+        raise MissingProjectFileError(options.pyproject_path or os.path.join(start_dir, "pyproject.toml"))
+    project_root = os.path.abspath(options.project_root) if options.project_root else os.path.dirname(candidate)
+    return _derive_paths(project_root, candidate, options, agent_name)
+
+
+def resolve_node_project_paths(options: PackageOptions | None = None, agent_name: str | None = None) -> ResolvedPaths:
+    """Paths for a Node/TypeScript project, locating the nearest ``package.json``."""
+    options = options or PackageOptions()
+    start_dir = os.path.abspath(options.project_root) if options.project_root else os.getcwd()
+    candidate = _find_up("package.json", start_dir)
+    if not candidate or not os.path.exists(candidate):
+        raise MissingProjectFileError(os.path.join(start_dir, "package.json"))
+    project_root = os.path.abspath(options.project_root) if options.project_root else os.path.dirname(candidate)
+    return _derive_paths(project_root, candidate, options, agent_name)
+
+
+def ensure_dir_clean(directory: str) -> None:
+    shutil.rmtree(directory, ignore_errors=True)
+    os.makedirs(directory, exist_ok=True)
+
+
+def _copy_entry(source: str, destination: str, root_dir: str) -> None:
+    if os.path.isdir(source):
+        os.makedirs(destination, exist_ok=True)
+        for entry in os.listdir(source):
+            if _should_exclude_entry(entry, source, root_dir):
+                continue
+            _copy_entry(os.path.join(source, entry), os.path.join(destination, entry), root_dir)
+        return
+    # Content only (like a stream copy), following symlinks.
+    shutil.copyfile(source, destination)
+
+
+def copy_source_tree(src_dir: str, destination: str) -> None:
+    if not os.path.exists(src_dir):
+        raise MissingProjectFileError(src_dir)
+    _copy_entry(src_dir, destination, src_dir)
+
+
+def ensure_binary_available(binary: str, install_hint: str | None = None) -> None:
+    checks = [
+        lambda: check_subprocess("where" if is_windows else "which", [binary]),
+        lambda: check_subprocess(binary, ["--version"]),
+        lambda: check_subprocess(binary, ["-v"]),
+    ]
+    if any(check() for check in checks):
+        return
+    raise MissingDependencyError(binary, install_hint)
+
+
+def run_command(command: str, args: list[str], cwd: str | None = None) -> None:
+    run_subprocess(command, args, cwd=cwd)
+
+
+def _collect_files(directory: str, base_path: str = "") -> list[tuple[str, str]]:
+    """(absolute path, zip path) pairs. Like upstream, symlinks are neither files nor dirs here."""
+    result: list[tuple[str, str]] = []
+    with os.scandir(directory) as it:
+        entries = sorted(it, key=lambda e: e.name)
+    for entry in entries:
+        if _is_zip_excluded_entry(entry.name):
+            continue
+        zip_path = f"{base_path}/{entry.name}" if base_path else entry.name
+        if entry.is_dir(follow_symlinks=False):
+            result.extend(_collect_files(entry.path, zip_path))
+        elif entry.is_file(follow_symlinks=False):
+            result.append((entry.path, zip_path))
+    return result
+
+
+def create_zip_from_dir(source_dir: str, output_zip: str) -> None:
+    """Zip regular files under ``source_dir`` (deflate level 6), preserving file modes."""
+    if os.path.exists(output_zip):
+        os.remove(output_zip)
+    os.makedirs(os.path.dirname(output_zip) or ".", exist_ok=True)
+    files = _collect_files(source_dir)
+    with zipfile.ZipFile(output_zip, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=6) as zf:
+        for full_path, zip_path in files:
+            info = zipfile.ZipInfo.from_file(full_path, zip_path, strict_timestamps=False)
+            info.compress_type = zipfile.ZIP_DEFLATED
+            with open(full_path, "rb") as fh:
+                zf.writestr(info, fh.read(), compress_type=zipfile.ZIP_DEFLATED, compresslevel=6)
+
+
+def enforce_zip_size_limit(zip_path: str) -> int:
+    size = os.stat(zip_path).st_size
+    if size > MAX_ZIP_SIZE_BYTES:
+        raise ArtifactSizeError(MAX_ZIP_SIZE_BYTES, size)
+    return size
+
+
+# --- Console script fix-ups ---------------------------------------------------------------------
+
+_PORTABLE_SHEBANG = "#!/usr/bin/env python3"
+
+# Console scripts whose Windows .exe launchers are replaced by Linux scripts when cross-packaging.
+_KNOWN_CONSOLE_SCRIPTS: dict[str, tuple[str, str]] = {
+    "opentelemetry-instrument": ("opentelemetry.instrumentation.auto_instrumentation", "run"),
+    "opentelemetry-bootstrap": ("opentelemetry.instrumentation.bootstrap", "run"),
+}
+
+_HARDCODED_SHEBANG = re.compile(r"^#!/(?:Users|home|opt|var|tmp)/.*python")
+
+
+def _generate_linux_console_script(module_path: str, func_name: str) -> str:
+    return (
+        "#!/usr/bin/env python3\n"
+        "# -*- coding: utf-8 -*-\n"
+        "import re\n"
+        "import sys\n"
+        f"from {module_path} import {func_name}\n"
+        "if __name__ == '__main__':\n"
+        "    sys.argv[0] = re.sub(r'(-script\\.pyw|\\.exe)?$', '', sys.argv[0])\n"
+        f"    sys.exit({func_name}())\n"
+    )
+
+
+def _write_executable(path: str, content: str) -> None:
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(content)
+    os.chmod(path, 0o755)
+
+
+def _rewrite_unix_shebangs(staging_dir: str) -> None:
+    """Replace hardcoded interpreter paths in ``bin/`` scripts with ``#!/usr/bin/env python3``."""
+    bin_dir = os.path.join(staging_dir, "bin")
+    if not os.path.exists(bin_dir):
+        return
+    for entry in os.listdir(bin_dir):
+        script_path = os.path.join(bin_dir, entry)
+        if not os.path.isfile(script_path):
+            continue
+        with open(script_path, "rb") as fh:
+            content = fh.read().decode("utf-8", errors="replace")
+        first_line = content.split("\n", 1)[0]
+        if first_line and _HARDCODED_SHEBANG.search(first_line):
+            # Rewrites in place; like upstream, the existing file mode is kept.
+            with open(script_path, "w", encoding="utf-8", newline="") as fh:
+                fh.write(content.replace(first_line, _PORTABLE_SHEBANG, 1))
+
+
+def convert_windows_scripts_to_linux(staging_dir: str) -> None:
+    """Make console scripts runnable on Linux: rewrite .exe launchers (Windows) or shebangs (Unix)."""
+    if not is_windows:
+        _rewrite_unix_shebangs(staging_dir)
+        return
+    bin_dir = os.path.join(staging_dir, "bin")
+    if not os.path.exists(bin_dir):
+        return
+    for entry in os.listdir(bin_dir):
+        if not entry.endswith(".exe"):
+            continue
+        script_name = entry[:-4]
+        entry_point = _KNOWN_CONSOLE_SCRIPTS.get(script_name)
+        if entry_point:
+            os.unlink(os.path.join(bin_dir, entry))
+            _write_executable(os.path.join(bin_dir, script_name), _generate_linux_console_script(*entry_point))
+
+
+# Upstream keeps *Sync twins for CDK bundling; Python is synchronous throughout.
+resolve_project_paths_sync = resolve_project_paths
+resolve_node_project_paths_sync = resolve_node_project_paths
+ensure_dir_clean_sync = ensure_dir_clean
+copy_source_tree_sync = copy_source_tree
+ensure_binary_available_sync = ensure_binary_available
+create_zip_from_dir_sync = create_zip_from_dir
+enforce_zip_size_limit_sync = enforce_zip_size_limit
+convert_windows_scripts_to_linux_sync = convert_windows_scripts_to_linux
+
+__all__ = [
+    "MAX_ZIP_SIZE_BYTES",
+    "ResolvedPaths",
+    "convert_windows_scripts_to_linux",
+    "copy_source_tree",
+    "create_zip_from_dir",
+    "enforce_zip_size_limit",
+    "ensure_binary_available",
+    "ensure_dir_clean",
+    "is_node_runtime",
+    "is_python_runtime",
+    "resolve_code_location",
+    "resolve_node_project_paths",
+    "resolve_project_paths",
+    "run_command",
+]