agentcore-cli 0.31.1__py3-none-any.whl

agentcore/schema/schemas/__init__.py

@@ -0,0 +1,40 @@
+"""Pydantic ports of the upstream Zod schemas (port of ``src/schema/schemas/index.ts``).
+
+Unlike upstream (which re-exports only a subset of primitives), every primitive is re-exported.
+"""
+
+from .agent_env import *
+from .agent_env import __all__ as _agent_env
+from .agentcore_project import *
+from .agentcore_project import __all__ as _agentcore_project
+from .auth import *
+from .auth import __all__ as _auth
+from .aws_targets import *
+from .aws_targets import __all__ as _aws_targets
+from .connections import *
+from .connections import __all__ as _connections
+from .deployed_state import *
+from .deployed_state import __all__ as _deployed_state
+from .mcp import *
+from .mcp import __all__ as _mcp
+from .mcp_defs import *
+from .mcp_defs import __all__ as _mcp_defs
+from .primitives import *
+from .primitives import __all__ as _primitives
+from .primitives.harness import *
+from .primitives.harness import __all__ as _harness
+from .zod_util import unique_by
+
+__all__ = [
+    *_agent_env,
+    *_agentcore_project,
+    *_auth,
+    *_aws_targets,
+    *_connections,
+    *_deployed_state,
+    *_mcp,
+    *_mcp_defs,
+    *_primitives,
+    *_harness,
+    "unique_by",
+]

agentcore/schema/schemas/agent_env.py

@@ -0,0 +1,545 @@
+"""Agent runtimes, i.e. AgentEnvSpec (port of ``schemas/agent-env.ts``)."""
+
+from __future__ import annotations
+
+from typing import Annotated, Final, Literal, get_args
+
+from pydantic import AfterValidator, Field, model_validator
+
+from .._zod import Issue, StrictModel, ZBool, ZodModel, array_checks, js_regex, raise_issues, zint, zstr
+from ..constants import (
+    MAX_CONTAINER_BUILD_SECURITY_GROUPS,
+    SECURITY_GROUP_ID_PATTERN,
+    SUBNET_ID_PATTERN,
+    VPC_ID_PATTERN,
+    NetworkMode,
+    ProtocolMode,
+    RuntimeVersion,
+    is_container_build,
+)
+from .auth import AuthorizerConfig, RuntimeAuthorizerType
+from .connections import Connection
+from .primitives.capacity_provider import CapacityProviderConfiguration, CapacityProviderVolumeName
+from .primitives.tags import Tags
+
+# ============================================================================
+# Name Schemas
+# ============================================================================
+
+# https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html
+AgentName = zstr(
+    min=1,
+    max=48,
+    min_msg="Name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
+)
+
+EnvVarName = zstr(
+    min=1,
+    max=255,
+    pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+    pattern_msg="Must start with a letter or underscore, contain only letters, digits, and underscores",
+)
+
+# https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html
+GatewayName = zstr(
+    min=1,
+    max=100,
+    pattern=r"^[0-9a-zA-Z](?:[0-9a-zA-Z-]*[0-9a-zA-Z])?$",
+    pattern_msg="Gateway name must be alphanumeric with optional hyphens (max 100 chars)",
+)
+
+# ============================================================================
+# Common Types
+# ============================================================================
+
+# Access level for resource sharing.
+Access = Literal["read", "readwrite"]
+ACCESS_LEVELS: Final[tuple[Access, ...]] = get_args(Access)
+
+AgentType = Literal["AgentCoreRuntime"]
+
+BuildType = Literal["CodeZip", "Container"]
+BUILD_TYPES: Final[tuple[BuildType, ...]] = get_args(BuildType)
+
+# Python (main.py, main.py:handler) or TypeScript (main.ts, main.js, index.ts) entrypoint.
+Entrypoint = zstr(
+    min=1,
+    pattern=r"^[a-zA-Z0-9_][a-zA-Z0-9_/.-]*\.(py|ts|js)(:[a-zA-Z_][a-zA-Z0-9_]*)?$",
+    pattern_msg=(
+        'Must be a Python (.py) or TypeScript (.ts/.js) file path with optional handler (e.g., "main.py:handler" '
+        'or "index.ts")'
+    ),
+)
+
+DirectoryPathStr = zstr(min=1)
+
+# Char-safe set only: the buildspec interpolates this unquoted as `docker build -f $DOCKERFILE_PATH`.
+_DOCKERFILE_PATH_ALLOWED_CHARS = js_regex(r"^[A-Za-z0-9._/-]+$")
+
+
+def is_valid_dockerfile_path(p: str) -> bool:
+    """Safe relative Dockerfile path within the build context.
+
+    Allowed chars only, no leading slash, and no empty ('' from leading/trailing/double slash) or
+    '..' segments. Shared by the schema and the runtime ``getDockerfilePath`` guard.
+    """
+    if not _DOCKERFILE_PATH_ALLOWED_CHARS.search(p):
+        return False
+    if p.startswith("/"):
+        return False
+    return not any(segment in ("", "..") for segment in p.split("/"))
+
+
+DockerfilePath = zstr(
+    min=1,
+    max=255,
+    refines=(
+        (
+            is_valid_dockerfile_path,
+            (
+                "Must be a relative path within the build context: a filename or forward-slash subpath using only "
+                'letters, digits, dot, dash, underscore, and slash; no leading slash, no ".." traversal, and no empty '
+                "segments (no trailing or double slash)"
+            ),
+        ),
+    ),
+)
+
+# Build-arg names reserved by the CodeBuild build environment (best-effort denylist).
+RESERVED_BUILD_ARG_KEYS: Final[tuple[str, ...]] = (
+    # Buildspec control vars (mirrored in @aws/agentcore-cdk's ContainerBuildProject / build handler).
+    "ECR_REGISTRY",
+    "IMAGE_URI",
+    "DOCKERFILE_PATH",
+    "BUILD_ARG_FLAGS",
+    # Overriding these would break the buildspec's own commands or redirect the docker client.
+    "PATH",
+    "HOME",
+    "IFS",
+    "LD_PRELOAD",
+    "LD_LIBRARY_PATH",
+    "DOCKER_HOST",
+    "DOCKER_CONFIG",
+    "DOCKER_TLS_VERIFY",
+    "DOCKER_CERT_PATH",
+)
+
+
+def is_reserved_build_arg_key(key: str) -> bool:
+    return key in RESERVED_BUILD_ARG_KEYS or key.startswith(("CODEBUILD_", "AWS_"))
+
+
+# Each value becomes a CodeBuild PLAINTEXT env override; control chars/overlong values break StartBuild.
+BuildArgValue = zstr(
+    max=4096,
+    max_msg="Build arg values must be at most 4096 characters",
+    refines=(
+        (
+            lambda v: not any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in v),
+            "Build arg values must not contain control characters (including newlines)",
+        ),
+    ),
+)
+
+
+class EnvVar(ZodModel):
+    name: EnvVarName
+    value: str
+
+
+class Instrumentation(ZodModel):
+    """Runtime observability. ``enableOtel`` wraps the entrypoint with opentelemetry-instrument."""
+
+    enable_otel: ZBool = True
+
+
+class NetworkConfig(ZodModel):
+    """VPC-mode network configuration (required when networkMode is VPC)."""
+
+    subnets: Annotated[
+        list[zstr(pattern=SUBNET_ID_PATTERN, pattern_msg="Must be a subnet id (subnet-...)")],
+        array_checks(min=1, max=16),
+    ]
+    security_groups: Annotated[
+        list[zstr(pattern=SECURITY_GROUP_ID_PATTERN, pattern_msg="Must be a security group id (sg-...)")],
+        array_checks(min=1, max=16),
+    ]
+    # Required for Container builds in VPC mode (CodeBuild cannot infer the VPC from subnets).
+    vpc_id: zstr(pattern=VPC_ID_PATTERN, pattern_msg="Must be a VPC id (vpc-...)") | None = None
+
+
+# Allowed request headers: any valid HTTP header name that is not structurally reserved
+# (x-amz-*, x-amzn-* except X-Amzn-Bedrock-AgentCore-Runtime-Custom-*). Max 20.
+HEADER_ALLOWLIST_PREFIX: Final = "X-Amzn-Bedrock-AgentCore-Runtime-Custom-"
+HEADER_NAME_PATTERN: Final = js_regex(r"^[A-Za-z0-9\-_]+$")
+MAX_HEADER_ALLOWLIST_SIZE: Final = 20
+
+
+def check_allowlist_header(val: str) -> str | None:
+    """Return None if ``val`` is a valid allowlist header name, else the violated rule's message."""
+    if not HEADER_NAME_PATTERN.search(val):
+        return f'Header name "{val}" must contain only alphanumeric characters, hyphens, and underscores.'
+    lower = val.lower()
+    if lower.startswith("x-amz-"):
+        return f'Header "{val}" is not allowed. Headers starting with "x-amz-" are reserved for AWS request signing.'
+    if lower.startswith("x-amzn-") and not lower.startswith("x-amzn-bedrock-agentcore-runtime-custom-"):
+        return (
+            f'Header "{val}" is not allowed. Headers starting with "x-amzn-" are reserved, except for '
+            '"X-Amzn-Bedrock-AgentCore-Runtime-Custom-*".'
+        )
+    return None
+
+
+def _check_header(val: str) -> str:
+    error = check_allowlist_header(val)
+    if error:
+        raise_issues([((), error)], val)
+    return val
+
+
+RequestHeaderAllowlist = Annotated[
+    list[Annotated[str, AfterValidator(_check_header)]],
+    array_checks(max=MAX_HEADER_ALLOWLIST_SIZE, max_msg=f"Maximum {MAX_HEADER_ALLOWLIST_SIZE} headers allowed"),
+]
+
+
+def _mount_path(example: str) -> object:
+    return zstr(
+        min=6,
+        max=200,
+        pattern=r"^\/mnt\/[a-zA-Z0-9._-]+\/?$",
+        pattern_msg=f"Must be a path under /mnt with exactly one subdirectory (e.g. {example})",
+    )
+
+
+SessionStorageMountPath = _mount_path("/mnt/data")
+
+
+class SessionStorage(ZodModel):
+    """Session-scoped filesystem persistence; files under mountPath survive stop/resume."""
+
+    mount_path: SessionStorageMountPath
+
+
+EFS_ACCESS_POINT_ARN_PATTERN: Final = js_regex(
+    r"^arn:aws[-a-z]*:elasticfilesystem:[a-z][a-z0-9-]*:[0-9]{12}:access-point\/fsap-[0-9a-f]{8,40}$"
+)
+
+S3_FILES_ACCESS_POINT_ARN_PATTERN: Final = js_regex(
+    r"^arn:aws[-a-z]*:s3files:[a-z][a-z0-9-]*:[0-9]{12}:file-system\/fs-[0-9a-f]{17,40}\/access-point\/fsap-[0-9a-f]{17,40}$"
+)
+
+
+class EfsAccessPointConfig(ZodModel):
+    """EFS access point mount (requires VPC network mode)."""
+
+    access_point_arn: zstr(
+        pattern=EFS_ACCESS_POINT_ARN_PATTERN,
+        pattern_msg=(
+            "Must be an EFS access point ARN "
+            "(arn:aws[-a-z]*:elasticfilesystem:{region}:{account}:access-point/fsap-{id})"
+        ),
+    )
+    mount_path: _mount_path("/mnt/tools")
+
+
+class S3FilesAccessPointConfig(ZodModel):
+    """S3 Files access point mount (requires VPC network mode)."""
+
+    access_point_arn: zstr(
+        pattern=S3_FILES_ACCESS_POINT_ARN_PATTERN,
+        pattern_msg=(
+            "Must be an S3 Files access point ARN "
+            "(arn:aws[-a-z]*:s3files:{region}:{account}:file-system/fs-{id}/access-point/fsap-{id})"
+        ),
+    )
+    mount_path: _mount_path("/mnt/datasets")
+
+
+class CapacityProviderVolumeConfig(ZodModel):
+    """Mount of a named volume defined on the attached capacity provider."""
+
+    volume_name: CapacityProviderVolumeName
+    mount_path: _mount_path("/mnt/models")
+
+
+MAX_EFS_MOUNTS: Final = 2
+MAX_S3_MOUNTS: Final = 2
+
+
+class SessionStorageFilesystem(StrictModel):
+    session_storage: SessionStorage
+
+
+class EfsAccessPointFilesystem(StrictModel):
+    efs_access_point: EfsAccessPointConfig
+
+
+class S3FilesAccessPointFilesystem(StrictModel):
+    s3_files_access_point: S3FilesAccessPointConfig
+
+
+class CapacityProviderVolumeFilesystem(StrictModel):
+    capacity_provider_volume: CapacityProviderVolumeConfig
+
+
+# Exactly one key per entry. Service limits per runtime: max 5 total, max 1 sessionStorage, max
+# MAX_EFS_MOUNTS efsAccessPoint, max MAX_S3_MOUNTS s3FilesAccessPoint.
+FilesystemConfiguration = Annotated[
+    SessionStorageFilesystem
+    | EfsAccessPointFilesystem
+    | S3FilesAccessPointFilesystem
+    | CapacityProviderVolumeFilesystem,
+    Field(union_mode="left_to_right"),
+]
+
+
+def filesystem_mount_path(fc: FilesystemConfiguration) -> str:
+    if isinstance(fc, SessionStorageFilesystem):
+        return fc.session_storage.mount_path
+    if isinstance(fc, EfsAccessPointFilesystem):
+        return fc.efs_access_point.mount_path
+    if isinstance(fc, S3FilesAccessPointFilesystem):
+        return fc.s3_files_access_point.mount_path
+    return fc.capacity_provider_volume.mount_path
+
+
+def _strip_trailing_slash(p: str) -> str:
+    return p.removesuffix("/")
+
+
+LIFECYCLE_TIMEOUT_MIN: Final = 60
+LIFECYCLE_TIMEOUT_MAX: Final = 28800
+
+
+class LifecycleConfiguration(ZodModel):
+    """Idle timeout (API default 900s) and max lifetime (API default 28800s) of runtime sessions."""
+
+    idle_runtime_session_timeout: zint(ge=LIFECYCLE_TIMEOUT_MIN, le=LIFECYCLE_TIMEOUT_MAX) | None = None
+    max_lifetime: zint(ge=LIFECYCLE_TIMEOUT_MIN, le=LIFECYCLE_TIMEOUT_MAX) | None = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> LifecycleConfiguration:
+        if (
+            self.idle_runtime_session_timeout is not None
+            and self.max_lifetime is not None
+            and self.idle_runtime_session_timeout > self.max_lifetime
+        ):
+            raise_issues([(("idleRuntimeSessionTimeout",), "idleRuntimeSessionTimeout must be <= maxLifetime")], self)
+        return self
+
+
+# ============================================================================
+# Runtime Endpoint
+# ============================================================================
+
+RuntimeEndpointName = zstr(
+    min=1,
+    max=48,
+    min_msg="Endpoint name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
+)
+
+
+class RuntimeEndpoint(ZodModel):
+    # Version number this endpoint points to (>= 1).
+    version: zint(ge=1)
+    description: zstr(max=200) | None = None
+
+
+_CONTAINER_ONLY_FIELDS: Final = (
+    ("dockerfile", "dockerfile"),
+    ("build_context_path", "buildContextPath"),
+    ("custom_docker_build_args", "customDockerBuildArgs"),
+)
+
+
+class AgentEnvSpec(ZodModel):
+    """An AgentCore Runtime (top-level resource in agentcore.json ``runtimes``)."""
+
+    name: AgentName
+    description: zstr(max=200) | None = None
+    build: BuildType
+    entrypoint: Entrypoint
+    code_location: DirectoryPathStr
+    # Container builds: Dockerfile relative to the build context. Default: 'Dockerfile'.
+    dockerfile: DockerfilePath | None = None
+    # Container builds: docker build context (instead of codeLocation); not containment-checked.
+    build_context_path: DirectoryPathStr | None = None
+    # Container builds: `--build-arg` flags (keys are env-var names).
+    custom_docker_build_args: dict[EnvVarName, BuildArgValue] | None = None
+    runtime_version: RuntimeVersion | None = None
+    env_vars: list[EnvVar] | None = None
+    network_mode: NetworkMode | None = None
+    network_config: NetworkConfig | None = None
+    instrumentation: Instrumentation | None = None
+    protocol: ProtocolMode | None = None
+    request_header_allowlist: RequestHeaderAllowlist | None = None
+    # ARN of an existing IAM execution role to use instead of creating a new one.
+    execution_role_arn: str | None = None
+    # Managed-policy ARNs or `.json` policy-document paths (relative to codeLocation).
+    additional_policies: list[zstr(min=1)] | None = None
+    authorizer_type: RuntimeAuthorizerType | None = None
+    authorizer_configuration: AuthorizerConfig | None = None
+    tags: Tags | None = None
+    lifecycle_configuration: LifecycleConfiguration | None = None
+    filesystem_configurations: list[FilesystemConfiguration] | None = None
+    # Named endpoints (version aliases); keys are endpoint names.
+    endpoints: dict[RuntimeEndpointName, RuntimeEndpoint] | None = None
+    connections: list[Connection] | None = None
+    # Attach to a capacity provider; mutually exclusive with VPC networking.
+    capacity_provider_configuration: CapacityProviderConfiguration | None = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> AgentEnvSpec:
+        issues: list[Issue] = []
+        if self.network_mode == "VPC" and self.network_config is None:
+            issues.append((("networkConfig",), "networkConfig is required when networkMode is VPC"))
+        if self.network_mode != "VPC" and self.network_config is not None:
+            issues.append((("networkConfig",), "networkConfig is only allowed when networkMode is VPC"))
+        # A capacity provider supplies its own network topology: networkMode is not settable at all.
+        if self.capacity_provider_configuration is not None and (
+            self.network_mode is not None or self.network_config is not None
+        ):
+            issues.append(
+                (
+                    ("capacityProviderConfiguration",),
+                    (
+                        "capacityProviderConfiguration cannot be combined with a networkMode or VPC networking — a "
+                        "capacity provider supplies its own network topology, so leave networkMode/networkConfig unset"
+                    ),
+                )
+            )
+        # vpcId is intentionally NOT required here (old configs predate it; deploy backfills it).
+        if (
+            self.network_mode == "VPC"
+            and is_container_build(self)
+            and self.network_config is not None
+            and len(self.network_config.security_groups) > MAX_CONTAINER_BUILD_SECURITY_GROUPS
+        ):
+            issues.append(
+                (
+                    ("networkConfig", "securityGroups"),
+                    (
+                        f"Container builds in VPC mode allow at most {MAX_CONTAINER_BUILD_SECURITY_GROUPS} security "
+                        "groups (CodeBuild limit)"
+                    ),
+                )
+            )
+        jwt = self.authorizer_configuration.custom_jwt_authorizer if self.authorizer_configuration else None
+        if self.authorizer_type == "CUSTOM_JWT" and jwt is None:
+            issues.append(
+                (
+                    ("authorizerConfiguration",),
+                    "authorizerConfiguration with customJwtAuthorizer is required when authorizerType is CUSTOM_JWT",
+                )
+            )
+        if self.authorizer_type != "CUSTOM_JWT" and self.authorizer_configuration is not None:
+            issues.append(
+                (
+                    ("authorizerConfiguration",),
+                    "authorizerConfiguration is only allowed when authorizerType is CUSTOM_JWT",
+                )
+            )
+        for attr, key in _CONTAINER_ONLY_FIELDS:
+            if self.build != "Container" and getattr(self, attr):
+                issues.append(((key,), f"{key} is only allowed for Container builds"))
+        for key in self.custom_docker_build_args or {}:
+            if is_reserved_build_arg_key(key):
+                issues.append(
+                    (
+                        ("customDockerBuildArgs", key),
+                        (
+                            f'customDockerBuildArgs key "{key}" is reserved by the build environment (must not be '
+                            f"{', '.join(RESERVED_BUILD_ARG_KEYS)}, or start with CODEBUILD_ or AWS_)"
+                        ),
+                    )
+                )
+        fcs = self.filesystem_configurations or []
+        if fcs:
+            issues.extend(self._filesystem_issues(fcs))
+        raise_issues(issues, self)
+        return self
+
+    def _filesystem_issues(self, fcs: list[FilesystemConfiguration]) -> list[Issue]:
+        path = ("filesystemConfigurations",)
+        issues: list[Issue] = []
+        efs = sum(isinstance(fc, EfsAccessPointFilesystem) for fc in fcs)
+        s3 = sum(isinstance(fc, S3FilesAccessPointFilesystem) for fc in fcs)
+        ss = sum(isinstance(fc, SessionStorageFilesystem) for fc in fcs)
+        cp_vol = sum(isinstance(fc, CapacityProviderVolumeFilesystem) for fc in fcs)
+        if cp_vol > 0 and self.capacity_provider_configuration is None:
+            issues.append(
+                (
+                    path,
+                    (
+                        "capacityProviderVolume filesystem mounts require the runtime to be attached to a capacity "
+                        "provider (set capacityProviderConfiguration)"
+                    ),
+                )
+            )
+        if len(fcs) > 5:
+            issues.append((path, "Maximum 5 filesystem configurations allowed"))
+        if efs > MAX_EFS_MOUNTS:
+            issues.append((path, f"Maximum {MAX_EFS_MOUNTS} efsAccessPoint configurations allowed"))
+        if s3 > MAX_S3_MOUNTS:
+            issues.append((path, f"Maximum {MAX_S3_MOUNTS} s3FilesAccessPoint configurations allowed"))
+        if ss > 1:
+            issues.append((path, "Maximum 1 sessionStorage configuration allowed"))
+        if (efs > 0 or s3 > 0) and self.network_mode != "VPC":
+            issues.append((path, "efsAccessPoint and s3FilesAccessPoint filesystem mounts require networkMode: VPC"))
+        mount_paths = [_strip_trailing_slash(filesystem_mount_path(fc)) for fc in fcs]
+        if len(set(mount_paths)) != len(mount_paths):
+            issues.append((path, "Filesystem mount paths must be unique"))
+        return issues
+
+
+__all__ = [
+    "ACCESS_LEVELS",
+    "BUILD_TYPES",
+    "EFS_ACCESS_POINT_ARN_PATTERN",
+    "HEADER_ALLOWLIST_PREFIX",
+    "HEADER_NAME_PATTERN",
+    "LIFECYCLE_TIMEOUT_MAX",
+    "LIFECYCLE_TIMEOUT_MIN",
+    "MAX_EFS_MOUNTS",
+    "MAX_HEADER_ALLOWLIST_SIZE",
+    "MAX_S3_MOUNTS",
+    "RESERVED_BUILD_ARG_KEYS",
+    "S3_FILES_ACCESS_POINT_ARN_PATTERN",
+    "Access",
+    "AgentEnvSpec",
+    "AgentName",
+    "AgentType",
+    "BuildArgValue",
+    "BuildType",
+    "CapacityProviderVolumeConfig",
+    "CapacityProviderVolumeFilesystem",
+    "DirectoryPathStr",
+    "DockerfilePath",
+    "EfsAccessPointConfig",
+    "EfsAccessPointFilesystem",
+    "Entrypoint",
+    "EnvVar",
+    "EnvVarName",
+    "FilesystemConfiguration",
+    "GatewayName",
+    "Instrumentation",
+    "LifecycleConfiguration",
+    "NetworkConfig",
+    "RequestHeaderAllowlist",
+    "RuntimeEndpoint",
+    "RuntimeEndpointName",
+    "S3FilesAccessPointConfig",
+    "S3FilesAccessPointFilesystem",
+    "SessionStorage",
+    "SessionStorageFilesystem",
+    "SessionStorageMountPath",
+    "check_allowlist_header",
+    "filesystem_mount_path",
+    "is_reserved_build_arg_key",
+    "is_valid_dockerfile_path",
+]