agentcore-cli 0.31.1__py3-none-any.whl

agentcore/lib/packaging/node.py

@@ -0,0 +1,153 @@
+"""Node/TypeScript CodeZip packager (port of ``packaging/node.ts``).
+
+Upstream calls the esbuild JS API in-process; here the esbuild CLI is run with the equivalent
+flags. It is taken from the project's ``node_modules/.bin``, else ``PATH``, else ``npx``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from typing import Any
+
+from agentcore.lib.constants import get_artifact_zip_name
+from agentcore.lib.errors.types import PackagingError
+from agentcore.lib.packaging.helpers import (
+    create_zip_from_dir,
+    enforce_zip_size_limit,
+    ensure_dir_clean,
+    is_node_runtime,
+    resolve_node_project_paths,
+)
+from agentcore.lib.packaging.types import ArtifactResult, PackageOptions, spec_field
+from agentcore.lib.utils.subprocess import run_subprocess_capture
+
+_NODE_RUNTIME_REGEX = re.compile(r"NODE_(\d+)")
+
+ESBUILD_VERSION_RANGE = "^0.28.0"
+
+# Packages that are require()d dynamically and so can't be bundled; copied into _deps/.
+DYNAMIC_REQUIRE_PACKAGES = (
+    "@fastify/sse",
+    "@fastify/websocket",
+    "duplexify",
+    "end-of-stream",
+    "fastify-plugin",
+    "inherits",
+    "once",
+    "readable-stream",
+    "safe-buffer",
+    "stream-shift",
+    "string_decoder",
+    "util-deprecate",
+    "wrappy",
+    "ws",
+)
+
+DEPS_DIR = "_deps"
+
+# Defines importMetaUrl for CJS output and makes require() fall back to _deps/<pkg>.
+CJS_BANNER = (
+    'const importMetaUrl = require("url").pathToFileURL(__filename).href;'
+    '(function(){var M=require("module"),p=require("path"),f=require("fs"),d=p.join(__dirname,"_deps"),o=M._resolveFilename;'
+    "M._resolveFilename=function(r,P,i,O){try{return o.call(this,r,P,i,O)}catch(e){"
+    'var dp=p.join(d,r);if(f.existsSync(dp)){var pk=p.join(dp,"package.json");'
+    'if(f.existsSync(pk)){var m=JSON.parse(f.readFileSync(pk,"utf8")).main||"index.js";return p.resolve(dp,m)}'
+    'return p.resolve(dp,"index.js")}throw e}};})();'
+)
+
+
+def extract_node_version(runtime: str) -> str:
+    """``NODE_20`` -> ``20``."""
+    match = _NODE_RUNTIME_REGEX.search(runtime)
+    if not match:
+        raise PackagingError(f"Unsupported Node runtime value: {runtime}")
+    if not match.group(1):
+        raise PackagingError(f"Invalid Node runtime value: {runtime}")
+    return match.group(1)
+
+
+def _copy_dynamic_deps(src_dir: str, staging_dir: str) -> None:
+    src_node_modules = os.path.join(src_dir, "node_modules")
+    if not os.path.exists(src_node_modules):
+        return
+    for pkg in DYNAMIC_REQUIRE_PACKAGES:
+        pkg_path = os.path.join(src_node_modules, pkg)
+        if os.path.exists(pkg_path):
+            shutil.copytree(pkg_path, os.path.join(staging_dir, DEPS_DIR, pkg), dirs_exist_ok=True, symlinks=True)
+
+
+def _esbuild_command(src_dir: str) -> tuple[str, list[str]]:
+    local = os.path.join(src_dir, "node_modules", ".bin", "esbuild")
+    for candidate in (local, local + ".cmd"):
+        if os.path.exists(candidate):
+            return candidate, []
+    on_path = shutil.which("esbuild")
+    if on_path:
+        return on_path, []
+    return "npx", ["--yes", f"esbuild@{ESBUILD_VERSION_RANGE}"]
+
+
+def run_esbuild(entry_file: str, outfile: str, node_target: str, src_dir: str) -> None:
+    command, prefix = _esbuild_command(src_dir)
+    args = [
+        *prefix,
+        entry_file,
+        "--bundle",
+        "--platform=node",
+        "--format=cjs",
+        "--minify",
+        f"--target={node_target}",
+        f"--outfile={outfile}",
+        f"--banner:js={CJS_BANNER}",
+        "--define:import.meta.url=importMetaUrl",
+        "--log-level=warning",
+    ]
+    result = run_subprocess_capture(command, args, cwd=src_dir)
+    if result.code != 0:
+        output = f"{result.stdout}\n{result.stderr}".strip()
+        raise PackagingError(f"esbuild failed to bundle {entry_file}:\n{output}")
+
+
+def _package(runtime_version: str, agent_name: str, options: PackageOptions) -> ArtifactResult:
+    paths = resolve_node_project_paths(options, agent_name)
+    ensure_dir_clean(paths.staging_dir)
+
+    entry_file = os.path.join(paths.src_dir, "main.ts")
+    run_esbuild(
+        entry_file,
+        os.path.join(paths.staging_dir, "main.js"),
+        f"node{extract_node_version(runtime_version)}",
+        paths.src_dir,
+    )
+
+    with open(os.path.join(paths.staging_dir, "package.json"), "w", encoding="utf-8") as fh:
+        fh.write('{"type":"commonjs"}')
+    _copy_dynamic_deps(paths.src_dir, paths.staging_dir)
+
+    artifact_path = options.output_path or os.path.join(paths.artifacts_dir, get_artifact_zip_name(agent_name))
+    create_zip_from_dir(paths.staging_dir, artifact_path)
+    size_bytes = enforce_zip_size_limit(artifact_path)
+    return ArtifactResult(artifact_path=artifact_path, size_bytes=size_bytes, staging_path=paths.staging_dir)
+
+
+class NodeCodeZipPackager:
+    def pack(self, spec: Any, options: PackageOptions | None = None) -> ArtifactResult:
+        options = options or PackageOptions()
+        if spec_field(spec, "build") != "CodeZip":
+            raise PackagingError("Node packager only supports CodeZip build type.")
+        runtime_version = spec_field(spec, "runtimeVersion")
+        if not runtime_version or not is_node_runtime(runtime_version):
+            raise PackagingError(f"Node packager only supports Node runtimes. Received: {runtime_version}")
+        return _package(runtime_version, options.agent_name or spec_field(spec, "name"), options)
+
+    def pack_code_zip(self, config: Any, options: PackageOptions | None = None) -> ArtifactResult:
+        options = options or PackageOptions()
+        runtime_version = spec_field(config, "runtimeVersion") or "NODE_20"
+        if not is_node_runtime(runtime_version):
+            raise PackagingError(f"Node packager only supports Node runtimes. Received: {runtime_version}")
+        return _package(runtime_version, options.agent_name or spec_field(config, "name") or "asset", options)
+
+
+NodeCodeZipPackagerSync = NodeCodeZipPackager

agentcore/lib/packaging/python.py

@@ -0,0 +1,135 @@
+"""Python CodeZip packager (port of ``packaging/python.ts``).
+
+Dependencies are installed with ``uv pip install --target`` for aarch64 manylinux, trying each
+platform candidate until one has wheels for every dependency.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from agentcore.lib.constants import UV_INSTALL_HINT, get_artifact_zip_name
+from agentcore.lib.errors.types import PackagingError
+from agentcore.lib.packaging.helpers import (
+    convert_windows_scripts_to_linux,
+    copy_source_tree,
+    create_zip_from_dir,
+    enforce_zip_size_limit,
+    ensure_binary_available,
+    ensure_dir_clean,
+    is_python_runtime,
+    resolve_project_paths,
+)
+from agentcore.lib.packaging.types import ArtifactResult, PackageOptions, spec_field
+from agentcore.lib.packaging.uv import detect_unavailable_platform
+from agentcore.lib.utils.subprocess import run_subprocess_capture
+
+_PYTHON_RUNTIME_REGEX = re.compile(r"PYTHON_(\d+)_?(\d+)?")
+
+# AgentCore Runtime uses AL2023 (GLIBC 2.34), so any manylinux <= 2_34 works.
+PLATFORM_CANDIDATES = ("aarch64-manylinux2014", "aarch64-manylinux_2_28", "aarch64-manylinux_2_34")
+
+
+def default_python_version() -> str:
+    try:
+        from agentcore.schema import DEFAULT_PYTHON_VERSION  # type: ignore[attr-defined]
+
+        return str(getattr(DEFAULT_PYTHON_VERSION, "value", DEFAULT_PYTHON_VERSION))
+    except Exception:  # schema package absent or not importable
+        return "PYTHON_3_14"
+
+
+def extract_python_version(runtime: str) -> str:
+    """``PYTHON_3_12`` -> ``3.12`` (for ``uv --python-version``)."""
+    match = _PYTHON_RUNTIME_REGEX.search(runtime)
+    if not match:
+        raise PackagingError(f"Unsupported Python runtime value: {runtime}")
+    major, minor = match.group(1), match.group(2)
+    if not major or not minor:
+        raise PackagingError(f"Invalid Python runtime value: {runtime}")
+    return f"{int(major)}.{int(minor)}"
+
+
+def _install_with_retries(
+    project_root: str,
+    src_dir: str,
+    staging_dir: str,
+    runtime_version: str,
+    python_platforms: Sequence[str],
+    pyproject_path: str,
+) -> str:
+    python_version = extract_python_version(runtime_version)
+    for platform in python_platforms:
+        if not platform:
+            raise PackagingError("No platform candidate available for dependency installation.")
+        ensure_dir_clean(staging_dir)
+        result = run_subprocess_capture(
+            "uv",
+            [
+                "pip",
+                "install",
+                "-r",
+                pyproject_path,
+                "--target",
+                staging_dir,
+                "--python-version",
+                python_version,
+                "--python-platform",
+                platform,
+                "--only-binary",
+                ":all:",
+            ],
+            cwd=project_root,
+        )
+        if result.code == 0:
+            copy_source_tree(src_dir, staging_dir)
+            convert_windows_scripts_to_linux(staging_dir)
+            return staging_dir
+        if detect_unavailable_platform(result):
+            continue
+        combined = f"{result.stdout}\n{result.stderr}".strip()
+        raise PackagingError(combined or f"uv install failed on platform {platform} with exit code {result.code}")
+    raise PackagingError("uv install failed for all platform candidates.")
+
+
+def _package(runtime_version: str, agent_name: str, options: PackageOptions) -> ArtifactResult:
+    paths = resolve_project_paths(options, agent_name)
+    platforms = [options.python_platform] if options.python_platform else list(PLATFORM_CANDIDATES)
+
+    ensure_binary_available("uv", UV_INSTALL_HINT)
+    ensure_dir_clean(paths.staging_dir)
+
+    final_staging = _install_with_retries(
+        paths.project_root, paths.src_dir, paths.staging_dir, runtime_version, platforms, paths.pyproject_path
+    )
+    artifact_path = options.output_path or os.path.join(paths.artifacts_dir, get_artifact_zip_name(agent_name))
+    create_zip_from_dir(final_staging, artifact_path)
+    size_bytes = enforce_zip_size_limit(artifact_path)
+    return ArtifactResult(artifact_path=artifact_path, size_bytes=size_bytes, staging_path=final_staging)
+
+
+class PythonCodeZipPackager:
+    """Packager for CLI usage (``pack``) and CDK-style bundling (``pack_code_zip``)."""
+
+    def pack(self, spec: Any, options: PackageOptions | None = None) -> ArtifactResult:
+        options = options or PackageOptions()
+        if spec_field(spec, "build") != "CodeZip":
+            raise PackagingError("Python packager only supports CodeZip build type.")
+        runtime_version = spec_field(spec, "runtimeVersion")
+        if not runtime_version or not is_python_runtime(runtime_version):
+            raise PackagingError(f"Python packager only supports Python runtimes. Received: {runtime_version}")
+        return _package(runtime_version, options.agent_name or spec_field(spec, "name"), options)
+
+    def pack_code_zip(self, config: Any, options: PackageOptions | None = None) -> ArtifactResult:
+        options = options or PackageOptions()
+        runtime_version = spec_field(config, "runtimeVersion") or default_python_version()
+        if not is_python_runtime(runtime_version):
+            raise PackagingError(f"Python packager only supports Python runtimes. Received: {runtime_version}")
+        return _package(runtime_version, options.agent_name or spec_field(config, "name") or "asset", options)
+
+
+# Upstream's separate sync packager is the same class here.
+PythonCodeZipPackagerSync = PythonCodeZipPackager

agentcore/lib/packaging/types.py

@@ -0,0 +1,69 @@
+"""Packaging option/result types (port of ``packaging/types/packaging.ts``)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Protocol
+
+
+@dataclass(slots=True)
+class PackageOptions:
+    # Override for project root; defaults to cwd / discovered root.
+    project_root: str | None = None
+    # Override for source directory; defaults to the project root.
+    src_dir: str | None = None
+    # Override for pyproject.toml (Python) path.
+    pyproject_path: str | None = None
+    # Override for the artifact base directory; defaults to <projectRoot>/agentcore.
+    artifact_dir: str | None = None
+    # Python platform tag override; default tries PLATFORM_CANDIDATES.
+    python_platform: str | None = None
+    # Agent name for artifact naming and staging isolation.
+    agent_name: str | None = None
+    # Write the zip here if given.
+    output_path: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactResult:
+    artifact_path: str
+    size_bytes: int
+    staging_path: str
+
+
+@dataclass(slots=True)
+class CodeBundleConfig:
+    """Minimal bundle config; ``AgentEnvSpec`` models satisfy the same shape."""
+
+    name: str
+    code_location: str
+    entrypoint: str
+    runtime_version: str | None = None
+
+
+class RuntimePackager(Protocol):
+    def pack(self, spec: Any, options: PackageOptions | None = None) -> ArtifactResult: ...
+
+
+class CodeZipPackager(Protocol):
+    def pack_code_zip(self, config: Any, options: PackageOptions | None = None) -> ArtifactResult: ...
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+def spec_field(spec: Any, name: str, default: Any = None) -> Any:
+    """Read a spec field by its camelCase JSON name from a dict or a model (snake_case or alias attr)."""
+    if isinstance(spec, Mapping):
+        value = spec.get(name, spec.get(_snake(name)))
+        return default if value is None else value
+    for attr in (_snake(name), name):
+        value = getattr(spec, attr, None)
+        if value is not None:
+            # Enum-valued fields (e.g. build type) compare by value.
+            return value.value if isinstance(value, Enum) else value
+    return default

agentcore/lib/packaging/uv.py

@@ -0,0 +1,45 @@
+"""Detect "no wheel for this platform" failures from ``uv pip install`` (port of ``uv.ts``)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from agentcore.lib.utils.subprocess import SubprocessResult
+
+_PLATFORM_HINT_REGEX = re.compile(r"platforms:\s*([^\n]+)", re.IGNORECASE)
+_MANYLINUX_TOKEN = re.compile(r"(manylinux[^\s,]+)", re.IGNORECASE)
+_NO_WHEELS_REGEX = re.compile(
+    r"(has no wheels with a matching (?:platform|Python ABI) tag|no compatible (?:wheels|tags) found|has no usable wheels)",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PlatformIssue:
+    message: str
+    platforms: list[str] | None = field(default=None)
+
+
+def detect_unavailable_platform(result: SubprocessResult) -> PlatformIssue | None:
+    combined = f"{result.stdout}\n{result.stderr}"
+    hint = _PLATFORM_HINT_REGEX.search(combined)
+    if hint and hint.group(1):
+        hints = [m for m in _MANYLINUX_TOKEN.findall(hint.group(1)) if m]
+        if hints:
+            return PlatformIssue(message=_extract_relevant_block(combined, _PLATFORM_HINT_REGEX), platforms=hints)
+
+    if _NO_WHEELS_REGEX.search(combined):
+        return PlatformIssue(message=_extract_relevant_block(combined, _NO_WHEELS_REGEX))
+
+    return None
+
+
+def _extract_relevant_block(text: str, pattern: re.Pattern[str], context: int = 3) -> str:
+    lines = re.split(r"\r?\n", text)
+    index = next((i for i, line in enumerate(lines) if pattern.search(line)), -1)
+    if index == -1:
+        return text.strip()
+    start = max(0, index - context)
+    end = min(len(lines), index + context + 1)
+    return "\n".join(line.strip() for line in lines[start:end]).strip()

agentcore/lib/result.py

@@ -0,0 +1,104 @@
+"""Rust-style ``Result`` for fallible operations (port of ``src/lib/result.ts``).
+
+Upstream uses a discriminated union whose success branch spreads its data onto the result
+object. Here ``Ok`` wraps the data in ``value`` and ``Err`` wraps the exception in ``error``;
+both expose ``success`` so ``if result.success:`` narrows as it does upstream.
+``serialize_result`` reproduces the flat JSON shape the TypeScript CLI prints.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Generic, Literal, TypeAlias, TypeVar, overload
+
+from agentcore.lib.errors.types import BaseError
+
+T = TypeVar("T")
+E = TypeVar("E", bound=BaseException)
+
+_MISSING: Any = object()
+
+
+@dataclass(frozen=True, slots=True)
+class Ok(Generic[T]):
+    value: T = None  # type: ignore[assignment]
+
+    @property
+    def success(self) -> Literal[True]:
+        return True
+
+
+@dataclass(frozen=True, slots=True)
+class Err(Generic[E]):
+    error: E
+    # Extra fields carried alongside a failure (upstream's `{ success: false, error, ...rest }`).
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def success(self) -> Literal[False]:
+        return False
+
+
+Result: TypeAlias = Ok[T] | Err[E]
+
+
+def ok(value: T = None) -> Ok[T]:  # type: ignore[assignment]
+    return Ok(value)
+
+
+def err(error: E, **extra: Any) -> Err[E]:
+    return Err(error, extra)
+
+
+failure_result = err
+
+
+@overload
+def unwrap_result(result: Ok[T] | Err[Any]) -> T: ...
+@overload
+def unwrap_result(result: Ok[T] | Err[Any], default: T) -> T: ...
+def unwrap_result(result: Ok[T] | Err[Any], default: Any = _MISSING) -> Any:
+    """Return the success value, else ``default`` if given, else raise the contained error."""
+    if isinstance(result, Ok):
+        return result.value
+    if default is not _MISSING:
+        return default
+    raise result.error
+
+
+def _data_dict(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return dict(value)
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump(mode="json", by_alias=True)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+    return {"value": value}
+
+
+def serialize_result(result: Ok[Any] | Err[Any] | Mapping[str, Any]) -> dict[str, Any]:
+    """Convert a result to its JSON-serialisable form.
+
+    Failures replace ``error`` with its message and, for typed ``BaseError``s, add
+    ``errorName`` and ``errorSource``. Plain dict results (``{"success": ..., "error": exc}``)
+    are accepted too.
+    """
+    if isinstance(result, Ok):
+        return {"success": True, **_data_dict(result.value)}
+    if isinstance(result, Err):
+        error, rest = result.error, {"success": False, **result.extra}
+    else:
+        if result.get("success"):
+            return dict(result)
+        rest = {k: v for k, v in result.items() if k != "error"}
+        error = result.get("error")
+    serialized: dict[str, Any] = {**rest, "error": str(error) if error is not None else None}
+    if isinstance(error, BaseError):
+        serialized["errorName"] = error.name
+        serialized["errorSource"] = error.error_source
+    return serialized

agentcore/lib/schemas/__init__.py

@@ -0,0 +1 @@
+"""Schema I/O (config files on disk)."""

agentcore/lib/schemas/io/__init__.py

@@ -0,0 +1,27 @@
+from agentcore.lib.schemas.io.config_io import ConfigIO, create_config_io, get_schema_url_for_version
+from agentcore.lib.schemas.io.path_resolver import (
+    PathConfig,
+    PathResolver,
+    default_path_config,
+    find_config_root,
+    find_project_root,
+    get_session_project_root,
+    get_working_directory,
+    require_config_root,
+    set_session_project_root,
+)
+
+__all__ = [
+    "ConfigIO",
+    "PathConfig",
+    "PathResolver",
+    "create_config_io",
+    "default_path_config",
+    "find_config_root",
+    "find_project_root",
+    "get_schema_url_for_version",
+    "get_session_project_root",
+    "get_working_directory",
+    "require_config_root",
+    "set_session_project_root",
+]