agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/deploy/__init__.py

@@ -0,0 +1,152 @@
+"""Deploy orchestration building blocks (port of upstream ``src/cli/operations/deploy``)."""
+
+from agentcore.cli.external_requirements import (
+    NODE_MIN_VERSION,
+    DependencyCheckResult,
+    SemVer,
+    VersionCheckResult,
+    check_dependency_versions,
+    check_node_version,
+    check_uv_version,
+    compare_sem_ver,
+    format_sem_ver,
+    format_version_error,
+    parse_sem_ver,
+    requires_uv,
+    sem_ver_gte,
+)
+from agentcore.operations.deploy.backfill_vpc_id import BackfillVpcIdResult, backfill_container_vpc_ids
+from agentcore.operations.deploy.dependency_sync import (
+    SYNC_CDK_DEPENDENCIES_STEP,
+    ensure_managed_dependencies,
+    failed_sync_result,
+    teardown_sync_failure_result,
+    to_dep_sync_attrs,
+)
+from agentcore.operations.deploy.ensure_target import ensure_default_deployment_target
+from agentcore.operations.deploy.managed_memory_notice import (
+    MANAGED_MEMORY_ADD_NOTICE,
+    MANAGED_MEMORY_DEPLOY_NOTICE,
+    has_managed_memory_harness,
+)
+from agentcore.operations.deploy.payment_connector_authorization import (
+    QuickCreateConnectorAuthorization,
+    format_quick_create_connector_authorization,
+    get_quick_create_connector_authorizations,
+)
+from agentcore.operations.deploy.post_deploy_observability import setup_transaction_search
+from agentcore.operations.deploy.post_deploy_online_evals import (
+    EnableOnlineEvalsResult,
+    OnlineEvalEnableResult,
+    enable_online_eval_configs,
+)
+from agentcore.operations.deploy.pre_deploy_identity import (
+    ApiKeyProviderSetupResult,
+    MissingCredential,
+    OAuth2ProviderSetupResult,
+    PaymentCredentialProviderResult,
+    PaymentCredentialProvidersResult,
+    PreDeployIdentityResult,
+    PreDeployOAuth2Result,
+    assert_env_file_exists,
+    cleanup_payment_credential_providers,
+    get_all_credentials,
+    get_missing_credentials,
+    has_identity_api_providers,
+    has_identity_o_auth_providers,
+    has_payment_credential_providers,
+    setup_api_key_providers,
+    setup_o_auth2_providers,
+    setup_payment_credential_providers,
+)
+from agentcore.operations.deploy.preflight import (
+    BootstrapCheckResult,
+    PreflightContext,
+    StackStatusCheckResult,
+    SynthResult,
+    bootstrap_environment,
+    build_cdk_project,
+    check_bootstrap_needed,
+    check_stack_deployability,
+    format_error,
+    synthesize_cdk,
+    validate_harness_specs,
+    validate_project,
+)
+from agentcore.operations.deploy.teardown import (
+    DeployedTarget,
+    DiscoverDeployedResult,
+    destroy_target,
+    discover_deployed_targets,
+    get_cdk_project_dir,
+    perform_stack_teardown,
+)
+
+__all__ = [
+    "MANAGED_MEMORY_ADD_NOTICE",
+    "MANAGED_MEMORY_DEPLOY_NOTICE",
+    "NODE_MIN_VERSION",
+    "SYNC_CDK_DEPENDENCIES_STEP",
+    "ApiKeyProviderSetupResult",
+    "BackfillVpcIdResult",
+    "BootstrapCheckResult",
+    "DependencyCheckResult",
+    "DeployedTarget",
+    "DiscoverDeployedResult",
+    "EnableOnlineEvalsResult",
+    "MissingCredential",
+    "OAuth2ProviderSetupResult",
+    "OnlineEvalEnableResult",
+    "PaymentCredentialProviderResult",
+    "PaymentCredentialProvidersResult",
+    "PreDeployIdentityResult",
+    "PreDeployOAuth2Result",
+    "PreflightContext",
+    "QuickCreateConnectorAuthorization",
+    "SemVer",
+    "StackStatusCheckResult",
+    "SynthResult",
+    "VersionCheckResult",
+    "assert_env_file_exists",
+    "backfill_container_vpc_ids",
+    "bootstrap_environment",
+    "build_cdk_project",
+    "check_bootstrap_needed",
+    "check_dependency_versions",
+    "check_node_version",
+    "check_stack_deployability",
+    "check_uv_version",
+    "cleanup_payment_credential_providers",
+    "compare_sem_ver",
+    "destroy_target",
+    "discover_deployed_targets",
+    "enable_online_eval_configs",
+    "ensure_default_deployment_target",
+    "ensure_managed_dependencies",
+    "failed_sync_result",
+    "format_error",
+    "format_quick_create_connector_authorization",
+    "format_sem_ver",
+    "format_version_error",
+    "get_all_credentials",
+    "get_cdk_project_dir",
+    "get_missing_credentials",
+    "get_quick_create_connector_authorizations",
+    "has_identity_api_providers",
+    "has_identity_o_auth_providers",
+    "has_managed_memory_harness",
+    "has_payment_credential_providers",
+    "parse_sem_ver",
+    "perform_stack_teardown",
+    "requires_uv",
+    "sem_ver_gte",
+    "setup_api_key_providers",
+    "setup_o_auth2_providers",
+    "setup_payment_credential_providers",
+    "setup_transaction_search",
+    "synthesize_cdk",
+    "teardown_sync_failure_result",
+    "to_dep_sync_attrs",
+    "validate_harness_specs",
+    "validate_project",
+]

agentcore/operations/deploy/backfill_vpc_id.py

@@ -0,0 +1,90 @@
+"""Backfill ``networkConfig.vpcId`` for older Container+VPC configs (port of ``backfill-vpc-id.ts``).
+
+CDK synth re-reads agentcore.json / harness.json from disk, so the resolved VPC id is written there.
+On a preview (``persist=False``) the returned ``restore()`` reverts the files; a failure mid-run
+rolls back any partial preview writes before re-raising.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentcore.aws import agentcore_control
+from agentcore.schema.constants import is_container_build
+
+
+@dataclass
+class BackfillVpcIdResult:
+    backfilled: list[str] = field(default_factory=list)
+    restore: Callable[[], None] = lambda: None
+
+
+def _needs_vpc_id(spec: Any) -> bool:
+    nc = getattr(spec, "network_config", None)
+    return (
+        is_container_build(spec)
+        and getattr(spec, "network_mode", None) == "VPC"
+        and nc is not None
+        and len(nc.subnets) > 0
+        and not nc.vpc_id
+    )
+
+
+def backfill_container_vpc_ids(
+    config_io: Any, project_spec: Any, region: str, persist: bool = True
+) -> BackfillVpcIdResult:
+    backfilled: list[str] = []
+    originals: dict[str, str] = {}
+
+    def snapshot(path: str) -> None:
+        if persist or path in originals:
+            return
+        with open(path, encoding="utf-8") as fh:
+            originals[path] = fh.read()
+
+    def restore() -> None:
+        failures = []
+        for path, content in originals.items():
+            try:
+                with open(path, "w", encoding="utf-8") as fh:
+                    fh.write(content)
+            except OSError as exc:
+                failures.append(f"{path}: {exc}")
+        if failures:
+            raise RuntimeError(f"Failed to restore {len(failures)} config file(s) after preview: {'; '.join(failures)}")
+
+    try:
+        runtimes_changed = False
+        for runtime in project_spec.runtimes or []:
+            if _needs_vpc_id(runtime):
+                runtime.network_config.vpc_id = agentcore_control.resolve_vpc_id_from_subnets(
+                    list(runtime.network_config.subnets), region
+                )
+                runtimes_changed = True
+                backfilled.append(runtime.name)
+        if runtimes_changed:
+            snapshot(config_io.get_agent_config_path())
+            config_io.write_project_spec(project_spec)
+
+        for entry in project_spec.harnesses or []:
+            harness = config_io.read_harness_spec(entry.name)
+            if _needs_vpc_id(harness):
+                harness.network_config.vpc_id = agentcore_control.resolve_vpc_id_from_subnets(
+                    list(harness.network_config.subnets), region
+                )
+                snapshot(config_io.get_harness_config_path(entry.name))
+                config_io.write_harness_spec(entry.name, harness)
+                backfilled.append(entry.name)
+    except Exception:
+        try:
+            restore()
+        except Exception:  # noqa: BLE001 - preserve the original error
+            pass
+        raise
+
+    return BackfillVpcIdResult(backfilled=backfilled, restore=restore)
+
+
+__all__ = ["BackfillVpcIdResult", "backfill_container_vpc_ids"]

agentcore/operations/deploy/change_detection.py

@@ -0,0 +1,84 @@
+"""Deploy-skip detection for harness-only projects (port of ``change-detection.ts``)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.operations.deploy.ensure_target import ensure_default_deployment_target
+
+
+def _js_json(value: Any) -> str:
+    # Must equal JSON.stringify(value) byte for byte so hashes match ones written by the npm CLI.
+    return to_json_string(to_jsonable(value), None)
+
+
+def _read(path: str) -> str | None:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
+def compute_project_deploy_hash(config_io: Any) -> str:
+    """SHA-256 (first 16 hex chars) over agentcore.json, harness files and aws-targets.json."""
+    digest = hashlib.sha256()
+    project_spec = config_io.read_project_spec()
+    digest.update(_js_json(project_spec).encode("utf-8"))
+
+    project_root = os.path.dirname(config_io.get_config_root())
+    for harness in project_spec.harnesses or []:
+        harness_dir = os.path.join(project_root, harness.path)
+        harness_json = _read(os.path.join(harness_dir, "harness.json"))
+        if harness_json is not None:
+            digest.update(harness_json.encode("utf-8"))
+            try:
+                dockerfile = json.loads(harness_json).get("dockerfile")
+            except (ValueError, AttributeError):
+                dockerfile = None
+            if isinstance(dockerfile, str) and dockerfile:
+                content = _read(os.path.join(harness_dir, dockerfile))
+                if content is not None:
+                    digest.update(content.encode("utf-8"))
+        prompt = _read(os.path.join(harness_dir, "system-prompt.md"))
+        if prompt is not None:
+            digest.update(prompt.encode("utf-8"))
+
+    digest.update(_js_json(config_io.read_aws_deployment_targets()).encode("utf-8"))
+    return digest.hexdigest()[:16]
+
+
+def can_skip_deploy(config_io: Any) -> bool:
+    """True when a harness-only project is unchanged since its last deploy (to every target)."""
+    try:
+        project_spec = config_io.read_project_spec()
+        if project_spec.runtimes:
+            return False
+        current = compute_project_deploy_hash(config_io)
+        state = config_io.read_deployed_state()
+        if not state.targets:
+            return False
+        for target in state.targets.values():
+            stored = target.resources.deploy_hash if target.resources else None
+            if stored != current:
+                return False
+        return True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def is_deploy_skippable() -> bool:
+    try:
+        config_io = ConfigIO()
+        ensure_default_deployment_target(config_io)
+        return can_skip_deploy(config_io)
+    except Exception:  # noqa: BLE001
+        return False
+
+
+__all__ = ["can_skip_deploy", "compute_project_deploy_hash", "is_deploy_skippable"]

agentcore/operations/deploy/constants.py

@@ -0,0 +1,58 @@
+"""Constants from upstream ``src/cli/constants.ts`` that only deploy needs.
+
+``cli/constants.py`` belongs to another area; deploy-only values live here instead.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+from agentcore import __version__ as PACKAGE_VERSION
+
+DISTRO_MODE: Final = "PROD_DISTRO"
+
+DISTRO_CONFIG: Final = {
+    "PROD_DISTRO": {
+        "packageName": "@aws/agentcore",
+        "registryUrl": "https://registry.npmjs.org",
+        "installCommand": "npm install -g @aws/agentcore@latest",
+    },
+    "PRIVATE_DEV_DISTRO": {
+        "packageName": "@aws/agentcore",
+        "registryUrl": "https://npm.pkg.github.com",
+        "installCommand": "npm install -g @aws/agentcore@latest --registry=https://npm.pkg.github.com",
+    },
+}
+
+
+@dataclass(frozen=True)
+class DistroConfig:
+    package_name: str
+    registry_url: str
+    install_command: str
+    dist_tag: str
+
+
+def get_npm_dist_tag() -> str:
+    return "preview" if "-" in PACKAGE_VERSION else "latest"
+
+
+def get_distro_config() -> DistroConfig:
+    base = DISTRO_CONFIG[DISTRO_MODE]
+    tag = get_npm_dist_tag()
+    return DistroConfig(
+        package_name=base["packageName"],
+        registry_url=base["registryUrl"],
+        install_command=base["installCommand"].replace("@latest", f"@{tag}"),
+        dist_tag=tag,
+    )
+
+
+# tui/constants.ts BOOTSTRAP (used by the interactive deploy prompt).
+BOOTSTRAP_TITLE: Final = "CDK bootstrapping required"
+BOOTSTRAP_EXPLAINER: Final = (
+    "The AgentCore CLI uses AWS CDK and CloudFormation to manage AWS resources.\n"
+    "CDK bootstrapping is a one-time setup that creates resources CDK needs to deploy stacks.\n"
+    "This will create a CDKToolkit stack in your AWS account."
+)

agentcore/operations/deploy/dependency_sync.py

@@ -0,0 +1,105 @@
+"""Managed CDK dependency pinning for deploy (port of ``dependency-sync.ts``)."""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+from importlib.resources import as_file
+from typing import Any
+
+from agentcore.lib.dependency_management import sync as _sync
+from agentcore.lib.dependency_management.types import DependencySyncOutcome, DependencySyncResult
+from agentcore.lib.schemas.io.global_config import read_global_config_sync
+from agentcore.operations.deploy.constants import get_distro_config
+from agentcore.templates.template_root import get_template_path
+
+# Step label shared by the CLI and interactive deploy flows.
+SYNC_CDK_DEPENDENCIES_STEP = "Sync CDK dependencies"
+
+
+def _no_op_sync_result(outcome: DependencySyncOutcome, warnings: list[str] | None = None) -> DependencySyncResult:
+    return DependencySyncResult(
+        outcome=outcome,
+        opted_out=False,
+        check_only=False,
+        migrated_from_caret=False,
+        reinstalled=False,
+        skew_warning=False,
+        changes=[],
+        restored=[],
+        skipped=[],
+        warnings=list(warnings or []),
+        notice=None,
+    )
+
+
+def failed_sync_result() -> DependencySyncResult:
+    """Attached to the failure result when the sync itself throws (nothing took effect)."""
+    return _no_op_sync_result("failed")
+
+
+def teardown_sync_failure_result(err: BaseException) -> DependencySyncResult:
+    """Warning-only result for a DependencySyncError on a teardown deploy (teardown is never blocked)."""
+    return _no_op_sync_result("failure-suppressed", [f"Dependency sync failed (continuing with teardown): {err}"])
+
+
+def to_dep_sync_attrs(sync: DependencySyncResult) -> dict[str, Any]:
+    """dep_sync_* telemetry attrs (telemetry itself is not ported; kept for parity)."""
+    return {
+        "dep_sync_outcome": sync.outcome,
+        "dep_sync_changed_count": len(sync.changes) + len(sync.restored),
+        "dep_sync_migrated": sync.migrated_from_caret,
+        "dep_sync_opted_out": sync.opted_out,
+        "dep_sync_skew_warning": sync.skew_warning,
+        "dep_sync_reinstalled": sync.reinstalled,
+    }
+
+
+def _camel(name: str) -> str:
+    head, *rest = name.rstrip("_").split("_")
+    return head + "".join(p[:1].upper() + p[1:] for p in rest)
+
+
+def dependency_sync_result_to_json(sync: DependencySyncResult) -> dict[str, Any]:
+    """The camelCase JSON upstream prints for ``dependencySyncResult`` (``from_`` -> ``from``)."""
+
+    def convert(value: Any) -> Any:
+        if dataclasses.is_dataclass(value) and not isinstance(value, type):
+            return {_camel(f.name): convert(getattr(value, f.name)) for f in dataclasses.fields(value)}
+        if isinstance(value, list):
+            return [convert(v) for v in value]
+        return value
+
+    return convert(sync)
+
+
+def ensure_managed_dependencies(
+    cdk_project: Any, *, check_only: bool = False, treat_skew_as_warning: bool = False
+) -> DependencySyncResult:
+    """Pin ``agentcore/cdk/package.json`` to the CLI's vended versions (skipped with AGENTCORE_SKIP_INSTALL).
+
+    Raises ``CliVersionTooOldError`` on newer-than-CLI skew (unless ``treat_skew_as_warning`` or opted out)
+    and ``DependencySyncError`` on rewrite/install failure.
+    """
+    if os.environ.get("AGENTCORE_SKIP_INSTALL"):
+        return _no_op_sync_result("skipped")
+    disabled = read_global_config_sync().get("disableDependencyManagement") is True
+    with as_file(get_template_path("cdk", "package.json")) as vended:
+        return _sync.sync_managed_dependencies(
+            vended_package_json_path=str(vended),
+            project_dir=str(cdk_project.project_dir),
+            disabled=disabled,
+            mode="check" if check_only else "apply",
+            treat_skew_as_warning=treat_skew_as_warning,
+            install_command=get_distro_config().install_command,
+        )
+
+
+__all__ = [
+    "SYNC_CDK_DEPENDENCIES_STEP",
+    "dependency_sync_result_to_json",
+    "ensure_managed_dependencies",
+    "failed_sync_result",
+    "teardown_sync_failure_result",
+    "to_dep_sync_attrs",
+]

agentcore/operations/deploy/ensure_target.py

@@ -0,0 +1,30 @@
+"""Auto-populate aws-targets.json for non-interactive deploys (port of ``ensure-target.ts``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentcore.aws import aws_context
+from agentcore.lib.errors.types import ConfigNotFoundError
+
+
+def ensure_default_deployment_target(config_io: Any) -> bool:
+    """Write a ``default`` target from the detected AWS context when none exist.
+
+    A missing ``aws-targets.json`` counts as empty; any other read error is surfaced. Returns True
+    when a target was written.
+    """
+    try:
+        targets = config_io.read_aws_deployment_targets()
+    except ConfigNotFoundError:
+        targets = []
+    if targets:
+        return False
+    ctx = aws_context.detect_aws_context()
+    if not ctx.account_id:
+        return False
+    config_io.write_aws_deployment_targets([{"name": "default", "account": ctx.account_id, "region": ctx.region}])
+    return True
+
+
+__all__ = ["ensure_default_deployment_target"]

agentcore/operations/deploy/gateway_status.py

@@ -0,0 +1,44 @@
+"""Gateway target sync statuses after deploy (port of ``gateway-status.ts``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentcore.aws.agentcore_control import create_control_client
+
+STATUS_DISPLAY = {
+    "READY": "✓ synced",
+    "SYNCHRONIZING": "⟳ syncing...",
+    "SYNCHRONIZE_UNSUCCESSFUL": "⚠ sync failed",
+    "CREATING": "⟳ creating...",
+    "UPDATING": "⟳ updating...",
+    "UPDATE_UNSUCCESSFUL": "⚠ update failed",
+    "FAILED": "✗ failed",
+    "DELETING": "⟳ deleting...",
+}
+
+
+@dataclass(frozen=True)
+class TargetSyncStatus:
+    name: str
+    status: str
+
+
+def format_target_status(status: str) -> str:
+    return STATUS_DISPLAY.get(status, status)
+
+
+def get_gateway_target_statuses(gateway_id: str, region: str) -> list[TargetSyncStatus]:
+    """Statuses of every target in a gateway; ``[]`` on any error (non-blocking)."""
+    try:
+        client = create_control_client(region)
+        response = client.list_gateway_targets(gatewayIdentifier=gateway_id, maxResults=100)
+        return [
+            TargetSyncStatus(name=t.get("name") or "unknown", status=t.get("status") or "UNKNOWN")
+            for t in response.get("items") or []
+        ]
+    except Exception:  # noqa: BLE001
+        return []
+
+
+__all__ = ["STATUS_DISPLAY", "TargetSyncStatus", "format_target_status", "get_gateway_target_statuses"]

agentcore/operations/deploy/managed_memory_notice.py

@@ -0,0 +1,36 @@
+"""Managed-memory heads-up shown before the slow CFN apply (port of ``managed-memory-notice.ts``)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+MANAGED_MEMORY_DEPLOY_NOTICE = (
+    "Managed memory: this harness provisions a dedicated AgentCore Memory resource on deploy "
+    "(you requested --memory-mode managed).\n\n"
+    "Memory provisioning can take 3-5 minutes. We know this is slow, and we will be reducing this "
+    "provisioning time. To skip it, redeploy with --memory-mode disabled."
+)
+
+MANAGED_MEMORY_ADD_NOTICE = (
+    "Managed memory: this harness will provision a dedicated AgentCore Memory resource on deploy "
+    "(you requested --memory-mode managed).\n\n"
+    "Memory provisioning can take 3-5 minutes. We know this is slow, and we will be reducing this "
+    "provisioning time. To skip it, recreate the harness with --memory-mode disabled."
+)
+
+
+def has_managed_memory_harness(config_io: Any, harnesses: Sequence[Any] | None) -> bool:
+    """True when any harness.json explicitly uses ``memory.mode == 'managed'`` (unreadable specs don't count)."""
+    for harness in harnesses or []:
+        try:
+            spec = config_io.read_harness_spec(harness.name)
+        except Exception:  # noqa: BLE001
+            continue
+        memory = getattr(spec, "memory", None)
+        if memory is not None and getattr(memory, "mode", None) == "managed":
+            return True
+    return False
+
+
+__all__ = ["MANAGED_MEMORY_ADD_NOTICE", "MANAGED_MEMORY_DEPLOY_NOTICE", "has_managed_memory_harness"]