agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/deploy/actions.py

@@ -0,0 +1,840 @@
+"""Deploy orchestration (port of ``commands/deploy/actions.ts``)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from agentcore.aws.account import validate_aws_credentials
+from agentcore.aws.target_region import apply_target_region_to_env
+from agentcore.cdk.toolkit import (
+    CdkToolkitWrapper,
+    DeployMessage,
+    SwitchableIoHost,
+    create_switchable_io_host,
+    pattern_must_match,
+)
+from agentcore.cli.commands.deploy.types import DeployResult
+from agentcore.cli.errors import get_error_message, is_changeset_in_progress_error, is_stack_in_progress_error
+from agentcore.cloudformation import outputs as cfn_outputs
+from agentcore.lib.dependency_management.types import DependencySyncResult
+from agentcore.lib.errors.types import DependencySyncError, ResourceNotFoundError, ValidationError, to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.lib.utils.credentials import SecureCredentials
+from agentcore.logging.exec_logger import ExecLogger
+from agentcore.operations.deploy import (
+    backfill_vpc_id,
+    change_detection,
+    dependency_sync,
+    ensure_target,
+    gateway_status,
+    post_deploy_datasets,
+    post_deploy_knowledge_bases,
+    post_deploy_observability,
+    post_deploy_online_evals,
+    pre_deploy_identity,
+    preflight,
+    teardown,
+)
+from agentcore.operations.deploy import managed_memory_notice as memory_notice
+from agentcore.operations.deploy import payment_connector_authorization as pca
+from agentcore.operations.harness.orphan import find_orphan_harnesses
+from agentcore.operations.knowledge_base.hydrate_data_sources import hydrate_knowledge_base_data_sources
+
+StepStatus = Literal["start", "success", "error", "warn"]
+
+AGENT_NEXT_STEPS = ["agentcore invoke", "agentcore status"]
+MEMORY_ONLY_NEXT_STEPS = ["agentcore add agent", "agentcore status"]
+
+
+@dataclass
+class ValidatedDeployOptions:
+    target: str
+    auto_confirm: bool = False
+    verbose: bool = False
+    plan: bool = False
+    diff: bool = False
+    on_progress: Callable[[str, StepStatus], None] | None = None
+    on_resource_event: Callable[[str], None] | None = None
+    on_deploy_message: Callable[[DeployMessage], None] | None = None
+    # One-shot user-facing notice (e.g. managed-memory heads-up), always surfaced.
+    on_notice: Callable[[str], None] | None = None
+    # --- interactive-mode hooks (replace the Ink TUI's confirm/credential screens) ---
+    # Asked instead of failing when a teardown deploy runs without --yes.
+    confirm_teardown: Callable[[], bool] | None = None
+    # Asked instead of failing when bootstrap is needed without --yes; False skips bootstrapping.
+    confirm_bootstrap: Callable[[], bool] | None = None
+    # Credentials entered at the prompt (not persisted); override .env.local values.
+    runtime_credentials: SecureCredentials | None = None
+    # The prompt's "skip" choice: don't set up API key / OAuth providers.
+    skip_identity_setup: bool = False
+
+
+def to_stack_name(project_name: str, target_name: str) -> str:
+    """Matches ``toStackName`` in the vended ``bin/cdk.ts`` (underscores -> dashes)."""
+    return f"AgentCore-{project_name.replace('_', '-')}-{target_name.replace('_', '-')}"
+
+
+@dataclass(frozen=True)
+class HarnessVersionDrift:
+    name: str
+    to: int
+    from_: int | None = None
+
+
+def compute_harness_version_drift(
+    prev: Mapping[str, Any] | None, next_: Mapping[str, Mapping[str, Any]]
+) -> list[HarnessVersionDrift]:
+    """Harnesses whose (emitted) config version changed or appeared since the previous deploy."""
+
+    def version(record: Any) -> int | None:
+        if record is None:
+            return None
+        if isinstance(record, Mapping):
+            return record.get("harnessVersion")
+        return getattr(record, "harness_version", None)
+
+    notes = []
+    for name, record in next_.items():
+        to = version(record)
+        if to is None:
+            continue
+        frm = version((prev or {}).get(name))
+        if frm != to:
+            notes.append(HarnessVersionDrift(name=name, to=to, from_=frm))
+    return notes
+
+
+def select_target_stack(stack_names: list[str], project_name: str, target_name: str) -> Ok[str] | Err[ValidationError]:
+    """The synthesized stack for the deployed target (never blindly ``stack_names[0]``)."""
+    if not stack_names:
+        return Err(ValidationError("No stacks found to deploy"))
+    expected = to_stack_name(project_name, target_name)
+    if expected not in stack_names:
+        return Err(
+            ValidationError(
+                f"Synthesized stacks [{', '.join(stack_names)}] do not include the stack for target "
+                f'"{target_name}" (expected "{expected}").'
+            )
+        )
+    return Ok(expected)
+
+
+def run_diff(toolkit_wrapper: CdkToolkitWrapper, stack_name: str, io_host: SwitchableIoHost | None = None) -> None:
+    host = io_host or create_switchable_io_host()
+    has_content = False
+
+    def on_raw(code: str, _level: str, message: str, _data: Any = None) -> None:
+        nonlocal has_content
+        if not message:
+            return
+        # I4002: formatted diff per stack, I4001: overall diff summary
+        if code in ("CDK_TOOLKIT_I4002", "CDK_TOOLKIT_I4001"):
+            has_content = True
+            print(message)
+
+    host.set_on_raw_message(on_raw)
+    host.set_verbose(True)
+    if toolkit_wrapper.io_host is not host:
+        toolkit_wrapper.io_host = host
+    toolkit_wrapper.diff(pattern_must_match(stack_name))
+    if not has_content:
+        print("No stack differences detected.")
+    host.set_verbose(False)
+    host.set_on_raw_message(None)
+
+
+def run_deploy(toolkit_wrapper: CdkToolkitWrapper, stack_name: str) -> None:
+    toolkit_wrapper.deploy(pattern_must_match(stack_name))
+
+
+def _resources_json(state: Any, target_name: str) -> dict[str, Any]:
+    if state is None:
+        return {}
+    data = to_jsonable(state)
+    return ((data.get("targets") or {}).get(target_name) or {}).get("resources") or {}
+
+
+def handle_deploy(options: ValidatedDeployOptions) -> DeployResult:
+    toolkit_wrapper: CdkToolkitWrapper | None = None
+    restore_env: Callable[[], None] | None = None
+    # Preview modes revert the vpcId backfill on every exit path (success, early return, or raise).
+    preview_restore: Callable[[], None] | None = None
+    logger = ExecLogger(command="deploy")
+    current_step = ""
+    sync_result: DependencySyncResult | None = None
+
+    def start_step(name: str) -> None:
+        nonlocal current_step
+        current_step = name
+        logger.start_step(name)
+        if options.on_progress:
+            options.on_progress(name, "start")
+
+    def end_step(status: Literal["success", "error", "warn"], message: str | None = None) -> None:
+        logger.end_step(status, message)
+        if options.on_progress:
+            options.on_progress(current_step, status)
+
+    def fail(error: BaseException) -> DeployResult:
+        logger.finalize(False)
+        return DeployResult(
+            success=False, error=error, log_path=logger.get_relative_log_path(), dependency_sync_result=sync_result
+        )
+
+    try:
+        config_io = ConfigIO()
+
+        # Fresh projects have an empty aws-targets.json; non-interactive deploys auto-populate one.
+        start_step("Load deployment target")
+        ensure_target.ensure_default_deployment_target(config_io)
+        targets = config_io.resolve_aws_deployment_targets()
+        target = next((t for t in targets if t.name == options.target), None)
+        if target is None:
+            end_step("error", f'Target "{options.target}" not found')
+            message = f'Target "{options.target}" not found in aws-targets.json'
+            if not targets:
+                # The default target is created from the detected AWS account; no account means no credentials.
+                message += (
+                    ". No AWS account could be detected to create it: configure credentials "
+                    "(e.g. `aws sso login --profile <name>` or `aws configure`) and try again."
+                )
+            return fail(ResourceNotFoundError(message))
+        # Make the target region authoritative for SDK and CDK calls (aws/agentcore-cli#924).
+        restore_env = apply_target_region_to_env(target.region)
+        end_step("success")
+
+        gateway_specs: list[Any] = []
+        try:
+            gateway_specs = list(config_io.read_project_spec().agent_core_gateways or [])
+        except Exception:  # noqa: BLE001 - project read failed: no gateways
+            pass
+
+        start_step("Validate project")
+        context = preflight.validate_project(target)
+        end_step("success")
+        spec = context.project_spec
+
+        # Preview-build harnesses aren't CFN-managed; warn (skipped on teardown, which warns differently).
+        orphan_warnings: list[str] = []
+        if not context.is_teardown_deploy:
+            try:
+                pre_state = config_io.read_deployed_state()
+            except Exception:  # noqa: BLE001
+                pre_state = None
+            for orphan in find_orphan_harnesses(pre_state):
+                warning = (
+                    f'Harness "{orphan.name}" was created by the preview build and is not managed by '
+                    "CloudFormation. This deploy won't touch it, and it keeps incurring cost. To migrate it "
+                    f"to GA, run `agentcore remove harness {orphan.name} --keep` (deletes the old resource "
+                    "but keeps it in agentcore.json), then deploy again so it's recreated under CloudFormation. "
+                    "Use --discard instead if you no longer want it."
+                )
+                logger.log(warning, "warn")
+                orphan_warnings.append(warning)
+
+        if context.is_teardown_deploy and not options.auto_confirm:
+            if options.confirm_teardown is None or not options.confirm_teardown():
+                return fail(
+                    ValidationError(
+                        "This will delete all deployed resources and the CloudFormation stack. "
+                        "Run with --yes to confirm teardown."
+                    )
+                )
+
+        if context.is_teardown_deploy:
+            start_step("Validate AWS credentials")
+            validate_aws_credentials(target)
+            end_step("success")
+
+        # Pin agentcore/cdk/package.json. Previews are check-only; teardown never blocks on pinning.
+        is_preview = options.plan or options.diff
+        start_step(dependency_sync.SYNC_CDK_DEPENDENCIES_STEP)
+        try:
+            sync_result = dependency_sync.ensure_managed_dependencies(
+                context.cdk_project, check_only=is_preview, treat_skew_as_warning=context.is_teardown_deploy
+            )
+        except Exception as sync_err:
+            if not (context.is_teardown_deploy and isinstance(sync_err, DependencySyncError)):
+                sync_result = dependency_sync.failed_sync_result()
+                raise
+            sync_result = dependency_sync.teardown_sync_failure_result(sync_err)
+        for warning in sync_result.warnings:
+            logger.log(warning, "warn")
+        if sync_result.notice:
+            logger.log(sync_result.notice)
+            if options.on_notice:
+                options.on_notice(sync_result.notice)
+        end_step("warn" if sync_result.outcome == "failure-suppressed" else "success")
+
+        start_step("Build CDK project")
+        preflight.build_cdk_project(context.cdk_project)
+        end_step("success")
+
+        # Identity providers before synth (the CDK app reads credential ARNs from deployed state).
+        identity_kms_key_arn: str | None = None
+        env_check = pre_deploy_identity.assert_env_file_exists(spec, config_io.get_config_root())
+        if not env_check.success:
+            return fail(env_check.error)
+
+        # Runtime credentials from the process env (non-interactive deploy with -y).
+        env_credentials = {
+            c.env_var_name: os.environ[c.env_var_name]
+            for c in pre_deploy_identity.get_all_credentials(spec)
+            if os.environ.get(c.env_var_name)
+        }
+        runtime_credentials = SecureCredentials(env_credentials) if env_credentials else None
+        if options.runtime_credentials is not None:
+            runtime_credentials = (
+                runtime_credentials.merge(options.runtime_credentials)
+                if runtime_credentials
+                else options.runtime_credentials
+            )
+
+        deployed_credentials: dict[str, dict[str, Any]] = {}
+
+        if pre_deploy_identity.has_identity_api_providers(spec) and not options.skip_identity_setup:
+            start_step("Creating credentials...")
+            identity_result = pre_deploy_identity.setup_api_key_providers(
+                project_spec=spec,
+                config_base_dir=config_io.get_config_root(),
+                region=target.region,
+                runtime_credentials=runtime_credentials,
+                enable_kms_encryption=True,
+            )
+            if identity_result.has_errors:
+                failed = next((r for r in identity_result.results if r.status == "error" and r.error), None)
+                end_step("error", str(failed.error) if failed else "Identity setup failed")
+                return fail(
+                    failed.error if failed else RuntimeError("unknown error occurred when setting up api key providers")
+                )
+            identity_kms_key_arn = identity_result.kms_key_arn
+            for r in identity_result.results:
+                if r.credential_provider_arn:
+                    deployed_credentials[r.provider_name] = {"credentialProviderArn": r.credential_provider_arn}
+            end_step("success")
+
+        if pre_deploy_identity.has_identity_o_auth_providers(spec) and not options.skip_identity_setup:
+            start_step("Creating OAuth credentials...")
+            oauth_result = pre_deploy_identity.setup_o_auth2_providers(
+                project_spec=spec,
+                config_base_dir=config_io.get_config_root(),
+                region=target.region,
+                runtime_credentials=runtime_credentials,
+            )
+            if oauth_result.has_errors:
+                # Detailed error goes to the log; the step message is sanitized (no OAuth details).
+                failed_oauth = next((r for r in oauth_result.results if r.status == "error" and r.error), None)
+                logger.log(f"OAuth setup error: {failed_oauth.error if failed_oauth else 'unknown'}", "error")
+                end_step("error", "OAuth credential setup failed. Check the log for details.")
+                return fail(
+                    failed_oauth.error
+                    if failed_oauth
+                    else RuntimeError("an unexpected error ocurred when setting up oauth providers")
+                )
+            for r in oauth_result.results:
+                if r.credential_provider_arn:
+                    record: dict[str, Any] = {"credentialProviderArn": r.credential_provider_arn}
+                    if r.client_secret_arn is not None:
+                        record["clientSecretArn"] = r.client_secret_arn
+                    if r.callback_url is not None:
+                        record["callbackUrl"] = r.callback_url
+                    deployed_credentials[r.provider_name] = record
+            end_step("success")
+
+        # Payment credential providers stay imperative; manager/connector/roles come from CDK.
+        if pre_deploy_identity.has_payment_credential_providers(spec):
+            start_step("Setting up payment credentials...")
+            payment_result = pre_deploy_identity.setup_payment_credential_providers(
+                project_spec=spec,
+                config_base_dir=config_io.get_config_root(),
+                region=target.region,
+                runtime_credentials=runtime_credentials,
+            )
+            if payment_result.has_errors:
+                messages = "; ".join(str(e) for e in payment_result.errors)
+                end_step("error", messages)
+                logger.log(f"Payment credential setup errors: {messages}", "error")
+                return fail(
+                    payment_result.errors[0]
+                    if payment_result.errors
+                    else RuntimeError("payment deploy preflight steps failed")
+                )
+            for name, provider in payment_result.credential_providers.items():
+                deployed_credentials[name] = {"credentialProviderArn": provider.credential_provider_arn}
+            end_step("success")
+
+        # Credential ARNs go to deployed state before synth so the template can read them.
+        if deployed_credentials:
+            try:
+                existing_pre = to_jsonable(config_io.read_deployed_state())
+            except Exception:  # noqa: BLE001
+                existing_pre = {"targets": {}}
+            target_state = (existing_pre.get("targets") or {}).get(target.name) or {"resources": {}}
+            resources = target_state.setdefault("resources", {}) or {}
+            target_state["resources"] = resources
+            resources["credentials"] = deployed_credentials
+            if identity_kms_key_arn:
+                resources["identityKmsKeyArn"] = identity_kms_key_arn
+            config_io.write_deployed_state(
+                {**existing_pre, "targets": {**(existing_pre.get("targets") or {}), target.name: target_state}}
+            )
+
+        # vpcId backfill for pre-existing Container+VPC configs (reverted after synth in previews).
+        backfill = backfill_vpc_id.backfill_container_vpc_ids(config_io, spec, target.region, not is_preview)
+        if is_preview:
+            preview_restore = backfill.restore
+        if backfill.backfilled:
+            logger.log(
+                f"Resolved networkConfig.vpcId for Container+VPC build(s): {', '.join(backfill.backfilled)}", "info"
+            )
+
+        start_step("Synthesize CloudFormation")
+        io_host = create_switchable_io_host() if (options.verbose or options.on_deploy_message) else None
+        synth_result = preflight.synthesize_cdk(context.cdk_project, io_host=io_host, region=target.region)
+        toolkit_wrapper = synth_result.toolkit_wrapper
+        selection = select_target_stack(synth_result.stack_names, spec.name, target.name)
+        if not selection.success:
+            end_step("error", str(selection.error))
+            return fail(selection.error)
+        stack_name = selection.value
+        end_step("success")
+
+        start_step("Check bootstrap status")
+        bootstrap_check = preflight.check_bootstrap_needed(context.aws_targets)
+        if bootstrap_check.needs_bootstrap:
+            if options.auto_confirm:
+                logger.log("Bootstrap needed, auto-confirming...")
+                preflight.bootstrap_environment(toolkit_wrapper, target)
+            elif options.confirm_bootstrap is not None:
+                if options.confirm_bootstrap():
+                    logger.log("Bootstrap needed, confirmed by user...")
+                    preflight.bootstrap_environment(toolkit_wrapper, target)
+                else:
+                    logger.log("Bootstrap skipped by user", "warn")
+            else:
+                end_step("error", "Bootstrap required")
+                return fail(ValidationError("AWS environment needs bootstrapping. Run with --yes to auto-bootstrap."))
+        end_step("success")
+
+        # Scope to this target's stack so a sibling target's failed stack can't block the deploy.
+        start_step("Check stack status")
+        deployability = preflight.check_stack_deployability(target.region, [stack_name])
+        if not deployability.can_deploy:
+            end_step("error", deployability.message)
+            return fail(RuntimeError(deployability.message or "Stack is not in a deployable state"))
+        end_step("success")
+
+        if options.plan:
+            logger.finalize(True)
+            toolkit_wrapper.dispose()
+            toolkit_wrapper = None
+            return DeployResult(
+                success=True,
+                target_name=target.name,
+                stack_name=stack_name,
+                log_path=logger.get_relative_log_path(),
+                dependency_sync_result=sync_result,
+            )
+
+        if options.diff:
+            start_step("Run CDK diff")
+            run_diff(toolkit_wrapper, stack_name, io_host)
+            end_step("success")
+            logger.finalize(True)
+            toolkit_wrapper.dispose()
+            toolkit_wrapper = None
+            return DeployResult(
+                success=True,
+                target_name=target.name,
+                stack_name=stack_name,
+                log_path=logger.get_relative_log_path(),
+                dependency_sync_result=sync_result,
+            )
+
+        if not context.is_teardown_deploy and memory_notice.has_managed_memory_harness(config_io, spec.harnesses):
+            logger.log(memory_notice.MANAGED_MEMORY_DEPLOY_NOTICE)
+            if options.on_notice:
+                options.on_notice(memory_notice.MANAGED_MEMORY_DEPLOY_NOTICE)
+
+        has_gateways = len(gateway_specs) > 0
+        start_step("Deploying gateways..." if has_gateways else "Deploy to AWS")
+
+        if io_host is not None and (options.on_resource_event or options.on_deploy_message):
+
+            def on_message(msg: DeployMessage) -> None:
+                if options.on_resource_event:
+                    options.on_resource_event(msg.message)
+                if options.on_deploy_message:
+                    options.on_deploy_message(msg)
+
+            io_host.set_on_message(on_message)
+            io_host.set_verbose(True)
+
+        try:
+            run_deploy(toolkit_wrapper, stack_name)
+        except Exception as deploy_err:
+            if is_changeset_in_progress_error(deploy_err):
+                logger.log("Changeset conflict detected - another deployment may be in progress", "warn")
+            elif is_stack_in_progress_error(deploy_err):
+                logger.log("Stack is busy with another operation - wait for it to finish and retry", "warn")
+            raise
+
+        if io_host is not None:
+            io_host.set_verbose(False)
+            io_host.set_on_message(None)
+        end_step("success")
+
+        if context.is_teardown_deploy:
+            try:
+                existing_for_teardown = config_io.read_deployed_state()
+            except Exception:  # noqa: BLE001
+                existing_for_teardown = None
+            existing_payments = _resources_json(existing_for_teardown, target.name).get("payments")
+            if existing_payments:
+                start_step("Clean up payment credentials")
+                try:
+                    pre_deploy_identity.cleanup_payment_credential_providers(
+                        region=target.region, payments=existing_payments
+                    )
+                    end_step("success")
+                except Exception as cleanup_err:  # noqa: BLE001 - best-effort
+                    end_step("error", f"Payment cleanup: {get_error_message(cleanup_err)}")
+
+            start_step("Tear down stack")
+            torn = teardown.perform_stack_teardown(target.name, toolkit_wrapper)
+            if not torn.success:
+                end_step("error", str(torn.error))
+                return fail(torn.error)
+            end_step("success")
+            logger.finalize(True)
+            return DeployResult(
+                success=True,
+                target_name=target.name,
+                stack_name=stack_name,
+                log_path=logger.get_relative_log_path(),
+                dependency_sync_result=sync_result,
+            )
+
+        # ---- Persist deployment state -------------------------------------------------------
+        start_step("Persist deployment state")
+        outputs = cfn_outputs.get_stack_outputs(target.region, stack_name)
+        agent_names = [a.name for a in spec.runtimes or []]
+        agents = cfn_outputs.parse_agent_outputs(outputs, agent_names, stack_name)
+
+        memory_names = [m.name for m in spec.memories or []]
+        memories = cfn_outputs.parse_memory_outputs(outputs, memory_names)
+        if memory_names and len(memories) != len(memory_names):
+            logger.log(f"Deployed-state missing outputs for {len(memory_names) - len(memories)} memory(ies).", "warn")
+
+        evaluators = cfn_outputs.parse_evaluator_outputs(outputs, [e.name for e in spec.evaluators or []])
+        online_eval_configs = cfn_outputs.parse_online_eval_outputs(
+            outputs,
+            [{"name": c.name, "agent": c.agent, "endpoint": c.endpoint} for c in spec.online_eval_configs or []],
+        )
+        engine_specs = spec.policy_engines or []
+        policy_engines = cfn_outputs.parse_policy_engine_outputs(outputs, [pe.name for pe in engine_specs])
+        policies = cfn_outputs.parse_policy_outputs(
+            outputs, [{"engineName": pe.name, "policyName": p.name} for pe in engine_specs for p in pe.policies]
+        )
+        endpoint_specs = [
+            {"agentName": r.name, "endpointName": ep} for r in spec.runtimes or [] for ep in (r.endpoints or {})
+        ]
+        runtime_endpoints = cfn_outputs.parse_runtime_endpoint_outputs(outputs, endpoint_specs)
+
+        all_gateways = cfn_outputs.parse_gateway_outputs(outputs, {g.name: g for g in gateway_specs})
+        http_gateway_names = {g.name for g in gateway_specs if getattr(g, "protocol_type", None) == "None"}
+        gateways = {n: s for n, s in all_gateways.items() if n not in http_gateway_names}
+        http_gateways = {n: s for n, s in all_gateways.items() if n in http_gateway_names}
+
+        datasets = cfn_outputs.parse_dataset_outputs(outputs, [d.name for d in spec.datasets or []])
+        capacity_providers = cfn_outputs.parse_capacity_provider_outputs(
+            outputs, [cp.name for cp in spec.capacity_providers or []]
+        )
+        config_bundles = cfn_outputs.parse_config_bundle_outputs(outputs, [b.name for b in spec.config_bundles or []])
+
+        kb_specs = spec.knowledge_bases or []
+        kb_names = [kb.name for kb in kb_specs]
+        knowledge_bases = cfn_outputs.parse_knowledge_base_outputs(outputs, kb_names)
+        if kb_names and len(knowledge_bases) != len(kb_names):
+            logger.log(
+                f"Deployed-state missing outputs for {len(kb_names) - len(knowledge_bases)} knowledge base(s).", "warn"
+            )
+        if knowledge_bases:
+            try:
+                hydrate_knowledge_base_data_sources(
+                    knowledge_bases=knowledge_bases, knowledge_base_specs=kb_specs, region=target.region
+                )
+            except Exception as hydrate_err:  # noqa: BLE001
+                logger.log(f"Failed to hydrate knowledge base data sources: {get_error_message(hydrate_err)}", "warn")
+
+        payment_specs = []
+        for p in spec.payments or []:
+            connectors = []
+            for c in p.connectors:
+                if c.provision_mode == "QUICK_CREATE":
+                    connectors.append({"name": c.name, "provisionMode": "QUICK_CREATE"})
+                else:
+                    connector: dict[str, Any] = {"name": c.name}
+                    if c.provision_mode:
+                        connector["provisionMode"] = c.provision_mode
+                    connector["credentialProviderArn"] = (deployed_credentials.get(c.credential_name) or {}).get(
+                        "credentialProviderArn"
+                    )
+                    connector["credentialProviderName"] = c.credential_name
+                    connectors.append(connector)
+            payment_specs.append(
+                {
+                    "name": p.name,
+                    "authorizerType": p.authorizer_type,
+                    "autoPayment": p.auto_payment,
+                    "paymentToolAllowlist": p.payment_tool_allowlist,
+                    "networkPreferences": p.network_preferences,
+                    "connectors": connectors,
+                }
+            )
+        payments = cfn_outputs.parse_payment_outputs(outputs, payment_specs) if payment_specs else None
+
+        deployed_harnesses = cfn_outputs.parse_harness_outputs(
+            outputs, [h.name for h in spec.harnesses or []], on_warn=lambda m: logger.log(m, "warn")
+        )
+        end_step("success")
+
+        deploy_hash: str | None = None
+        try:
+            deploy_hash = change_detection.compute_project_deploy_hash(config_io)
+        except Exception:  # noqa: BLE001 - best-effort
+            pass
+
+        try:
+            existing_state = config_io.read_deployed_state()
+        except Exception:  # noqa: BLE001
+            existing_state = None
+        existing_resources = _resources_json(existing_state, target.name)
+        prev_harness_records = existing_resources.get("harnesses")
+
+        deployed_state = cfn_outputs.build_deployed_state(
+            target_name=target.name,
+            stack_name=stack_name,
+            agents=agents,
+            gateways=gateways,
+            http_gateways=http_gateways or None,
+            existing_state=existing_state,
+            identity_kms_key_arn=identity_kms_key_arn,
+            credentials=deployed_credentials,
+            memories=memories,
+            evaluators=evaluators,
+            online_eval_configs=online_eval_configs,
+            policy_engines=policy_engines,
+            policies=policies,
+            harnesses=deployed_harnesses,
+            runtime_endpoints=runtime_endpoints,
+            datasets=datasets,
+            config_bundles=config_bundles,
+            knowledge_bases=knowledge_bases,
+            payments=payments,
+            capacity_providers=capacity_providers,
+            ab_test_names=[t.name for t in spec.ab_tests or []],
+        )
+        target_resources = deployed_state["targets"][target.name]["resources"]
+        if deploy_hash:
+            target_resources["deployHash"] = deploy_hash
+
+        # CFN succeeded; a failed local write must leave a recovery trail.
+        try:
+            config_io.write_deployed_state(deployed_state)
+        except Exception as write_err:
+            logger.log(
+                f"WARNING: deploy succeeded but writing agentcore/deployed-state.json failed: {write_err}.\n"
+                f"  Stack: {stack_name} (region: {target.region})\n"
+                "  AWS resources are running but the CLI cannot track them locally.\n"
+                "  Recovery options:\n"
+                "    1) Fix the local I/O problem (disk space / permissions on agentcore/) and run "
+                "`agentcore status` to refresh.\n"
+                "    2) If you want to teardown what was deployed: `aws cloudformation delete-stack "
+                f"--stack-name {stack_name} --region {target.region}`"
+            )
+            raise
+
+        for drift in compute_harness_version_drift(prev_harness_records, deployed_harnesses):
+            logger.log(
+                f"Harness {drift.name}: config updated (v{drift.from_} → v{drift.to})"
+                if drift.from_ is not None
+                else f"Harness {drift.name}: deployed (v{drift.to})"
+            )
+
+        if gateways:
+            urls = ", ".join(f"{name}: {gw['gatewayArn']}" for name, gw in gateways.items())
+            logger.log(f"Gateway URLs: {urls}")
+            for gw in gateways.values():
+                for status in gateway_status.get_gateway_target_statuses(gw["gatewayId"], target.region):
+                    logger.log(f"  {status.name}: {gateway_status.format_target_status(status.status)}")
+
+        end_step("success")
+
+        post_deploy_warnings: list[str] = []
+
+        # Auto-payment posture is informational (notes, exit 0), never a partial-failure warning.
+        auto_payment_notices = []
+        for manager in spec.payments or []:
+            if manager.auto_payment is not False:
+                limit = manager.default_spend_limit or "10.00"
+                auto_payment_notices.append(
+                    f'Payment manager "{manager.name}": auto-payment is ENABLED — the agent will settle '
+                    f"402 responses automatically up to the per-session spend limit (${limit}) with no "
+                    "human approval. Set --auto-payment false on the manager to require manual approval."
+                )
+
+        # Enable only newly deployed online eval configs (don't re-enable ones a user disabled).
+        deployed_online_evals = target_resources.get("onlineEvalConfigs") or {}
+        previous_online_evals = existing_resources.get("onlineEvalConfigs") or {}
+        new_online_evals = [c for c in spec.online_eval_configs or [] if c.name not in previous_online_evals]
+        if new_online_evals and deployed_online_evals:
+            enable_result = post_deploy_online_evals.enable_online_eval_configs(
+                region=target.region,
+                online_eval_configs=new_online_evals,
+                deployed_online_eval_configs=deployed_online_evals,
+            )
+            if enable_result.has_errors:
+                errors = [r for r in enable_result.results if r.status == "error"]
+                logger.log(
+                    "Online eval enable warnings: " + "; ".join(f'"{e.config_name}": {e.error}' for e in errors), "warn"
+                )
+                post_deploy_warnings.extend(f'Online eval "{e.config_name}": {e.error}' for e in errors)
+
+        dataset_specs = spec.datasets or []
+        deployed_datasets = target_resources.get("datasets") or {}
+        if dataset_specs and deployed_datasets:
+            ds_result = post_deploy_datasets.sync_datasets(
+                region=target.region,
+                datasets=dataset_specs,
+                deployed_datasets=deployed_datasets,
+                config_base_dir=config_io.get_config_root(),
+            )
+            if any(r.status == "synced" for r in ds_result.results):
+                try:
+                    updated = to_jsonable(config_io.read_deployed_state())
+                except Exception:  # noqa: BLE001
+                    updated = deployed_state
+                updated_resources = ((updated.get("targets") or {}).get(target.name) or {}).get("resources")
+                if updated_resources is not None:
+                    updated_resources["datasets"] = ds_result.updated_datasets
+                    config_io.write_deployed_state(updated)
+                    deployed_state = updated
+                    target_resources = updated_resources
+            if ds_result.has_errors:
+                errors = [r for r in ds_result.results if r.status == "error"]
+                logger.log(
+                    "Dataset sync warnings: " + "; ".join(f'"{e.dataset_name}": {e.error}' for e in errors), "warn"
+                )
+                post_deploy_warnings.extend(f'Dataset "{e.dataset_name}": {e.error}' for e in errors)
+            for r in ds_result.results:
+                if r.status == "synced":
+                    logger.log(
+                        f'Dataset "{r.dataset_name}": +{r.added} added, ~{r.updated} updated, -{r.deleted} deleted'
+                    )
+
+        if kb_specs:
+            start_step("Auto-ingest knowledge bases")
+            ingest_result = post_deploy_knowledge_bases.auto_ingest_knowledge_bases(
+                region=target.region,
+                knowledge_bases=kb_specs,
+                deployed_knowledge_bases=target_resources.get("knowledgeBases") or {},
+                previous_knowledge_bases=existing_resources.get("knowledgeBases"),
+                target_name=target.name,
+                deployed_state=deployed_state,
+                project_root=os.path.abspath(os.path.join(config_io.get_config_root(), "..")),
+                on_progress=lambda msg: logger.log(msg),
+            )
+            kb_records = target_resources.get("knowledgeBases")
+            if kb_records:
+                for r in ingest_result.results:
+                    if r.status == "started" and r.new_sources_hash and r.knowledge_base_name in kb_records:
+                        kb_records[r.knowledge_base_name]["sourcesHash"] = r.new_sources_hash
+                config_io.write_deployed_state(deployed_state)
+            for r in ingest_result.results:
+                if r.status == "started":
+                    logger.log(
+                        f'Knowledge base "{r.knowledge_base_name}": ingestion started for '
+                        f"{r.started_job_count} data source(s)"
+                    )
+                elif r.status == "skipped":
+                    logger.log(f'Knowledge base "{r.knowledge_base_name}": skipped ({r.reason})')
+                else:
+                    logger.log(f'Knowledge base "{r.knowledge_base_name}": {r.error}', "warn")
+                    post_deploy_warnings.append(f'Knowledge base "{r.knowledge_base_name}": {r.error}')
+            end_step("error" if ingest_result.has_errors else "success")
+
+        has_invokable = bool(agent_names) or bool(spec.harnesses)
+        next_steps = list(AGENT_NEXT_STEPS if has_invokable else MEMORY_ONLY_NEXT_STEPS)
+        notes = list(auto_payment_notices)
+        quick_create = pca.get_quick_create_connector_authorizations(
+            region=target.region, project_spec=spec, payments=payments
+        )
+        notes.extend(pca.format_quick_create_connector_authorization(q) for q in quick_create)
+
+        has_python_agent = any(
+            (a.entrypoint or "").endswith(".py") or ".py:" in (a.entrypoint or "") for a in spec.runtimes or []
+        )
+        if (agent_names or has_gateways) and has_python_agent:
+            try:
+                ts_result = post_deploy_observability.setup_transaction_search(
+                    region=target.region, account_id=target.account, agent_names=agent_names, has_gateways=has_gateways
+                )
+                if not ts_result.success:
+                    logger.log(f"Transaction search setup warning: {ts_result.error}", "warn")
+                else:
+                    notes.append(
+                        "Transaction search enabled. It takes ~10 minutes for transaction search to be fully "
+                        "active and for traces from invocations to be indexed."
+                    )
+            except Exception as ts_err:  # noqa: BLE001
+                logger.log(f"Transaction search setup failed: {get_error_message(ts_err)}", "warn")
+
+        logger.finalize(True)
+        all_warnings = [*orphan_warnings, *post_deploy_warnings]
+        return DeployResult(
+            success=True,
+            target_name=target.name,
+            stack_name=stack_name,
+            outputs=cfn_outputs.omit_payment_authorization_outputs(outputs),
+            log_path=logger.get_relative_log_path(),
+            next_steps=next_steps,
+            notes=notes,
+            post_deploy_warnings=all_warnings or None,
+            dependency_sync_result=sync_result,
+        )
+    except Exception as exc:  # noqa: BLE001 - every failure becomes a result, as upstream
+        logger.log(get_error_message(exc), "error")
+        return fail(to_error(exc))
+    finally:
+        # Each cleanup step runs regardless of earlier failures.
+        if toolkit_wrapper is not None:
+            try:
+                toolkit_wrapper.dispose()
+            except Exception as dispose_err:  # noqa: BLE001
+                logger.log(f"CDK toolkit dispose failed: {get_error_message(dispose_err)}", "warn")
+        if preview_restore is not None:
+            try:
+                preview_restore()
+            except Exception as restore_err:  # noqa: BLE001
+                logger.log(f"Failed to revert preview vpcId backfill: {get_error_message(restore_err)}", "warn")
+        if restore_env is not None:
+            restore_env()
+
+
+__all__ = [
+    "AGENT_NEXT_STEPS",
+    "MEMORY_ONLY_NEXT_STEPS",
+    "HarnessVersionDrift",
+    "ValidatedDeployOptions",
+    "compute_harness_version_drift",
+    "handle_deploy",
+    "run_deploy",
+    "run_diff",
+    "select_target_stack",
+    "to_stack_name",
+]