agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cloudformation/outputs.py

@@ -0,0 +1,566 @@
+"""Stack outputs -> deployed state (port of ``cloudformation/outputs.ts``).
+
+Parsed records are plain dicts keyed exactly like upstream's deployed-state JSON (camelCase), with
+optional fields omitted rather than set to ``None``. ``build_deployed_state`` returns the same JSON
+shape, which ``ConfigIO.write_deployed_state`` validates against the ``DeployedState`` schema.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from agentcore.aws.account import create_aws_client
+from agentcore.cloudformation.logical_ids import to_pascal_id
+from agentcore.cloudformation.stack_discovery import get_stack_name
+
+StackOutputs = dict[str, str]
+Record = dict[str, Any]
+
+
+def _get(obj: Any, key: str, default: Any = None) -> Any:
+    """Read ``key`` (camelCase) from a mapping, or its snake_case attribute from a model."""
+    if obj is None:
+        return default
+    if isinstance(obj, Mapping):
+        return obj.get(key, default)
+    snake = re.sub(r"(?<!^)(?=[A-Z])", "_", key).lower()
+    return getattr(obj, snake, default)
+
+
+def omit_payment_authorization_outputs(outputs: StackOutputs) -> StackOutputs:
+    return {k: v for k, v in outputs.items() if not k.startswith("Payment") or not k.endswith("AuthorizationUrl")}
+
+
+def get_stack_outputs(region: str, stack_name: str) -> StackOutputs:
+    """Fetch CloudFormation stack outputs (DescribeStacks)."""
+    cfn = create_aws_client("cloudformation", region)
+    resp = cfn.describe_stacks(StackName=stack_name)
+    stacks = resp.get("Stacks") or []
+    if not stacks:
+        raise RuntimeError(f"Stack {stack_name} not found")
+    outputs: StackOutputs = {}
+    for output in stacks[0].get("Outputs") or []:
+        key, value = output.get("OutputKey"), output.get("OutputValue")
+        if key and value:
+            outputs[key] = value
+    return outputs
+
+
+def _find_key(keys: Sequence[str], prefix: str) -> str | None:
+    return next((k for k in keys if k.startswith(prefix)), None)
+
+
+# ---------------------------------------------------------------------------
+# Gateways
+# ---------------------------------------------------------------------------
+
+_GATEWAY_OUTPUT = re.compile(r"^Gateway(.+?)(Id|Arn|Url)Output")
+_GATEWAY_TARGET_OUTPUT = re.compile(r"^GatewayTarget(.+?)IdOutput")
+
+
+def parse_gateway_outputs(outputs: StackOutputs, gateway_specs: Mapping[str, Any]) -> dict[str, Record]:
+    """``Gateway{Name}(Id|Arn|Url)Output{Hash}`` and ``GatewayTarget{Name}IdOutput{Hash}``."""
+    gateways: dict[str, Record] = {}
+    gateway_names = list(gateway_specs.keys())
+    gateway_id_map = {to_pascal_id(name): name for name in gateway_names}
+    target_outputs: list[tuple[str, str]] = []
+
+    for key, value in outputs.items():
+        # Target pattern first (more specific) to avoid false matches with the gateway pattern.
+        target_match = _GATEWAY_TARGET_OUTPUT.match(key)
+        if target_match:
+            if target_match.group(1):
+                target_outputs.append((target_match.group(1), value))
+            continue
+        match = _GATEWAY_OUTPUT.match(key)
+        if not match:
+            continue
+        logical_gateway, output_type = match.group(1), match.group(2)
+        gateway_name = gateway_id_map.get(logical_gateway, logical_gateway)
+        state = gateways.setdefault(gateway_name, {"gatewayId": gateway_name, "gatewayArn": ""})
+        if output_type == "Id":
+            state["gatewayId"] = value
+        elif output_type == "Arn":
+            state["gatewayArn"] = value
+        elif output_type == "Url":
+            state["gatewayUrl"] = value
+
+    target_to_gateway: dict[str, tuple[str, str]] = {}
+    for gw_name in gateway_names:
+        targets = _get(gateway_specs[gw_name], "targets")
+        if isinstance(targets, list):
+            for target in targets:
+                target_name = _get(target, "name")
+                target_to_gateway[to_pascal_id(target_name)] = (gw_name, target_name)
+
+    for logical_target, target_id in target_outputs:
+        mapping = target_to_gateway.get(logical_target)
+        gw_state = gateways.get(mapping[0]) if mapping else None
+        if mapping and gw_state is not None:
+            gw_state.setdefault("targets", {})[mapping[1]] = {"targetId": target_id}
+
+    return gateways
+
+
+# ---------------------------------------------------------------------------
+# Agents (runtimes)
+# ---------------------------------------------------------------------------
+
+_AGENT_OUTPUT = re.compile(
+    r"^ApplicationAgent(.+?)(RuntimeId|RuntimeArn|RoleArn|MemoryIds|BrowserId|CodeInterpreterId)Output"
+)
+_AGENT_FIELDS = {
+    "RuntimeId": "runtimeId",
+    "RuntimeArn": "runtimeArn",
+    "RoleArn": "roleArn",
+    "MemoryIds": "memoryIds",
+    "BrowserId": "browserId",
+    "CodeInterpreterId": "codeInterpreterId",
+}
+
+
+def parse_agent_outputs(outputs: StackOutputs, agent_names: Sequence[str], _stack_name: str = "") -> dict[str, Record]:
+    """``ApplicationAgent{AgentName}{OutputType}Output{Hash}``."""
+    agent_id_map = {to_pascal_id(name): name for name in agent_names}
+    by_agent: dict[str, dict[str, str]] = {}
+    for key, value in outputs.items():
+        match = _AGENT_OUTPUT.match(key)
+        if not match:
+            continue
+        agent_name = agent_id_map.get(match.group(1), match.group(1))
+        by_agent.setdefault(agent_name, {})[_AGENT_FIELDS[match.group(2)]] = value
+
+    agents: dict[str, Record] = {}
+    for agent_name, fields in by_agent.items():
+        if not fields.get("runtimeId") or not fields.get("runtimeArn") or not fields.get("roleArn"):
+            continue
+        state: Record = {
+            "runtimeId": fields["runtimeId"],
+            "runtimeArn": fields["runtimeArn"],
+            "roleArn": fields["roleArn"],
+        }
+        if fields.get("memoryIds"):
+            state["memoryIds"] = fields["memoryIds"].split(",")
+        if fields.get("browserId"):
+            state["browserId"] = fields["browserId"]
+        if fields.get("codeInterpreterId"):
+            state["codeInterpreterId"] = fields["codeInterpreterId"]
+        agents[agent_name] = state
+    return agents
+
+
+# ---------------------------------------------------------------------------
+# Simple Id/Arn resources
+# ---------------------------------------------------------------------------
+
+
+def _parse_id_arn(
+    outputs: StackOutputs, names: Sequence[str], pascal: Callable[[str], str], id_field: str, arn_field: str
+) -> dict[str, Record]:
+    result: dict[str, Record] = {}
+    keys = list(outputs.keys())
+    for name in names:
+        p = pascal(name)
+        id_key = _find_key(keys, f"Application{p}IdOutput")
+        arn_key = _find_key(keys, f"Application{p}ArnOutput")
+        if id_key and arn_key:
+            result[name] = {id_field: outputs[id_key], arn_field: outputs[arn_key]}
+    return result
+
+
+def parse_memory_outputs(outputs: StackOutputs, memory_names: Sequence[str]) -> dict[str, Record]:
+    """``ApplicationMemory{PascalName}(Id|Arn)Output{Hash}``."""
+    return _parse_id_arn(outputs, memory_names, lambda n: f"Memory{to_pascal_id(n)}", "memoryId", "memoryArn")
+
+
+def parse_knowledge_base_data_source_outputs(outputs: StackOutputs, knowledge_base_name: str) -> list[Record]:
+    """Per-DataSource outputs for one KB, ordered by index; incomplete pairs are dropped."""
+    pascal = to_pascal_id("KnowledgeBase", knowledge_base_name)
+    pattern = re.compile(rf"^Application{re.escape(pascal)}DataSource(\d+)(Id|Uri)Output")
+    indexed: dict[int, dict[str, str]] = {}
+    for key, value in outputs.items():
+        match = pattern.match(key)
+        if not match:
+            continue
+        slot = indexed.setdefault(int(match.group(1)), {})
+        slot["dataSourceId" if match.group(2) == "Id" else "uri"] = value
+    return [
+        {"dataSourceId": slot["dataSourceId"], "uri": slot["uri"]}
+        for _, slot in sorted(indexed.items())
+        if slot.get("dataSourceId") and slot.get("uri")
+    ]
+
+
+def parse_knowledge_base_outputs(outputs: StackOutputs, knowledge_base_names: Sequence[str]) -> dict[str, Record]:
+    """``ApplicationKnowledgeBase{Pascal}(Id|Arn)Output{Hash}`` plus per-DS outputs."""
+    kbs = _parse_id_arn(
+        outputs,
+        knowledge_base_names,
+        lambda n: to_pascal_id("KnowledgeBase", n),
+        "knowledgeBaseId",
+        "knowledgeBaseArn",
+    )
+    for name, record in kbs.items():
+        record["dataSources"] = parse_knowledge_base_data_source_outputs(outputs, name)
+    return kbs
+
+
+def parse_evaluator_outputs(outputs: StackOutputs, evaluator_names: Sequence[str]) -> dict[str, Record]:
+    return _parse_id_arn(
+        outputs, evaluator_names, lambda n: to_pascal_id("Evaluator", n), "evaluatorId", "evaluatorArn"
+    )
+
+
+def parse_online_eval_outputs(
+    outputs: StackOutputs, online_eval_specs: Sequence[Mapping[str, Any]]
+) -> dict[str, Record]:
+    """``ApplicationOnlineEval{PascalName}(Id|Arn)Output{Hash}``; specs are ``{name, agent?, endpoint?}``."""
+    configs: dict[str, Record] = {}
+    keys = list(outputs.keys())
+    for spec in online_eval_specs:
+        pascal = to_pascal_id("OnlineEval", spec["name"])
+        id_key = _find_key(keys, f"Application{pascal}IdOutput")
+        arn_key = _find_key(keys, f"Application{pascal}ArnOutput")
+        if id_key and arn_key:
+            record: Record = {
+                "onlineEvaluationConfigId": outputs[id_key],
+                "onlineEvaluationConfigArn": outputs[arn_key],
+            }
+            if spec.get("agent"):
+                record["agent"] = spec["agent"]
+            if spec.get("endpoint"):
+                record["endpoint"] = spec["endpoint"]
+            configs[spec["name"]] = record
+    return configs
+
+
+def parse_policy_engine_outputs(outputs: StackOutputs, engine_names: Sequence[str]) -> dict[str, Record]:
+    return _parse_id_arn(
+        outputs, engine_names, lambda n: to_pascal_id("PolicyEngine", n), "policyEngineId", "policyEngineArn"
+    )
+
+
+def parse_policy_outputs(outputs: StackOutputs, policy_specs: Sequence[Mapping[str, str]]) -> dict[str, Record]:
+    """``ApplicationPolicy{EnginePascal}{PolicyPascal}(Id|Arn)Output{Hash}``; keyed ``engine/policy``."""
+    policies: dict[str, Record] = {}
+    keys = list(outputs.keys())
+    for spec in policy_specs:
+        engine_name, policy_name = spec["engineName"], spec["policyName"]
+        pascal = to_pascal_id("Policy", engine_name, policy_name)
+        id_key = _find_key(keys, f"Application{pascal}IdOutput")
+        arn_key = _find_key(keys, f"Application{pascal}ArnOutput")
+        if id_key and arn_key:
+            policies[f"{engine_name}/{policy_name}"] = {
+                "policyId": outputs[id_key],
+                "policyArn": outputs[arn_key],
+                "engineName": engine_name,
+            }
+    return policies
+
+
+def parse_runtime_endpoint_outputs(
+    outputs: StackOutputs, endpoint_specs: Sequence[Mapping[str, str]]
+) -> dict[str, Record]:
+    """``ApplicationAgent{AgentPascal}Endpoint{AgentPascal}{EndpointPascal}(Id|Arn)Output{Hash}``."""
+    endpoints: dict[str, Record] = {}
+    keys = list(outputs.keys())
+    for spec in endpoint_specs:
+        agent_name, endpoint_name = spec["agentName"], spec["endpointName"]
+        prefix = f"ApplicationAgent{to_pascal_id(agent_name)}{to_pascal_id('Endpoint', agent_name, endpoint_name)}"
+        id_key = _find_key(keys, f"{prefix}IdOutput")
+        arn_key = _find_key(keys, f"{prefix}ArnOutput")
+        if id_key and arn_key:
+            endpoints[f"{agent_name}/{endpoint_name}"] = {
+                "endpointId": outputs[id_key],
+                "endpointArn": outputs[arn_key],
+            }
+    return endpoints
+
+
+def parse_dataset_outputs(outputs: StackOutputs, dataset_names: Sequence[str]) -> dict[str, Record]:
+    return _parse_id_arn(outputs, dataset_names, lambda n: to_pascal_id("Dataset", n), "datasetId", "datasetArn")
+
+
+def parse_capacity_provider_outputs(outputs: StackOutputs, names: Sequence[str]) -> dict[str, Record]:
+    return _parse_id_arn(
+        outputs, names, lambda n: to_pascal_id("CapacityProvider", n), "capacityProviderId", "capacityProviderArn"
+    )
+
+
+def _default_warn(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+def parse_harness_outputs(
+    outputs: StackOutputs,
+    harness_names: Sequence[str],
+    on_warn: Callable[[str], None] = _default_warn,
+) -> dict[str, Record]:
+    """``ApplicationHarness{Pascal}{Id,Arn,Status,AgentRuntimeArn,Version}Output`` + ``...RoleRoleArnOutput``."""
+    harnesses: dict[str, Record] = {}
+    keys = list(outputs.keys())
+    for harness_name in harness_names:
+        pascal = to_pascal_id("Harness", harness_name)
+        id_key = _find_key(keys, f"Application{pascal}IdOutput")
+        arn_key = _find_key(keys, f"Application{pascal}ArnOutput")
+        status_key = _find_key(keys, f"Application{pascal}StatusOutput")
+        runtime_arn_key = _find_key(keys, f"Application{pascal}AgentRuntimeArnOutput")
+        role_arn_key = _find_key(keys, f"Application{pascal}RoleRoleArnOutput")
+        # Version is optional: stacks deployed before config versioning don't emit it.
+        version_key = _find_key(keys, f"Application{pascal}VersionOutput")
+        version_raw = outputs[version_key] if version_key else None
+        version = int(version_raw) if version_raw is not None and re.fullmatch(r"[0-9]+", version_raw) else None
+
+        if id_key and arn_key and status_key and role_arn_key:
+            record: Record = {
+                "harnessId": outputs[id_key],
+                "harnessArn": outputs[arn_key],
+                "status": outputs[status_key],
+                "roleArn": outputs[role_arn_key],
+            }
+            if version is not None:
+                record["harnessVersion"] = version
+            if runtime_arn_key:
+                record["agentRuntimeArn"] = outputs[runtime_arn_key]
+            record["provisioner"] = "cloudformation"
+            harnesses[harness_name] = record
+            continue
+
+        missing = [
+            label
+            for label, key in (("Id", id_key), ("Arn", arn_key), ("Status", status_key), ("RoleArn", role_arn_key))
+            if not key
+        ]
+        if len(missing) == 4:
+            on_warn(
+                f'Harness "{harness_name}" produced no CloudFormation outputs; it will not appear in '
+                "`agentcore status` or be invocable until the next successful deploy."
+            )
+        else:
+            on_warn(
+                f'Harness "{harness_name}" is missing CloudFormation output(s): {", ".join(missing)}. '
+                "Skipping it in deployed-state — it will not appear in `agentcore status` or be invocable. "
+                "Re-run `agentcore deploy`; if this persists, the harness stack output template may be malformed."
+            )
+    return harnesses
+
+
+def parse_config_bundle_outputs(outputs: StackOutputs, bundle_names: Sequence[str]) -> dict[str, Record]:
+    bundles: dict[str, Record] = {}
+    keys = list(outputs.keys())
+    for bundle_name in bundle_names:
+        pascal = to_pascal_id("ConfigBundle", bundle_name)
+        id_key = _find_key(keys, f"Application{pascal}IdOutput")
+        arn_key = _find_key(keys, f"Application{pascal}ArnOutput")
+        version_key = _find_key(keys, f"Application{pascal}VersionIdOutput")
+        if id_key and arn_key and version_key:
+            bundles[bundle_name] = {
+                "bundleId": outputs[id_key],
+                "bundleArn": outputs[arn_key],
+                "versionId": outputs[version_key],
+            }
+    return bundles
+
+
+def _to_payment_cdk_id(name: str) -> str:
+    """Strip underscores (must match ``toCdkId()`` in the vended cdk-stack.ts)."""
+    return name.replace("_", "")
+
+
+def parse_payment_outputs(outputs: StackOutputs, payment_specs: Sequence[Mapping[str, Any]]) -> dict[str, Record]:
+    """``Payment{name}ManagerArn``/``ManagerId``/... outputs (names with underscores stripped)."""
+    payments: dict[str, Record] = {}
+    for spec in payment_specs:
+        mgr_id = _to_payment_cdk_id(spec["name"])
+        manager_arn = outputs.get(f"Payment{mgr_id}ManagerArn")
+        manager_id = outputs.get(f"Payment{mgr_id}ManagerId")
+        process_role = outputs.get(f"Payment{mgr_id}ProcessPaymentRoleArn")
+        retrieval_role = outputs.get(f"Payment{mgr_id}ResourceRetrievalRoleArn")
+        if not manager_arn or not manager_id or not process_role or not retrieval_role:
+            continue
+
+        connectors: dict[str, Record] = {}
+        for conn in spec.get("connectors") or []:
+            connector_id = outputs.get(f"Payment{mgr_id}{_to_payment_cdk_id(conn['name'])}ConnectorId")
+            if not connector_id:
+                continue
+            if conn.get("provisionMode") == "QUICK_CREATE":
+                record: Record = {"connectorId": connector_id, "provisionMode": "QUICK_CREATE"}
+                if conn.get("credentialProviderName"):
+                    record["credentialProviderName"] = conn["credentialProviderName"]
+                connectors[conn["name"]] = record
+            elif conn.get("credentialProviderArn"):
+                record = {"connectorId": connector_id}
+                if conn.get("provisionMode"):
+                    record["provisionMode"] = conn["provisionMode"]
+                record["credentialProviderArn"] = conn["credentialProviderArn"]
+                if conn.get("credentialProviderName"):
+                    record["credentialProviderName"] = conn["credentialProviderName"]
+                connectors[conn["name"]] = record
+
+        payment: Record = {
+            "managerId": manager_id,
+            "managerArn": manager_arn,
+            "connectors": connectors,
+            "processPaymentRoleArn": process_role,
+            "resourceRetrievalRoleArn": retrieval_role,
+        }
+        if spec.get("authorizerType"):
+            payment["authorizerType"] = spec["authorizerType"]
+        if spec.get("autoPayment") is not None:
+            payment["autoPayment"] = spec["autoPayment"]
+        if spec.get("paymentToolAllowlist"):
+            payment["paymentToolAllowlist"] = spec["paymentToolAllowlist"]
+        if spec.get("networkPreferences"):
+            payment["networkPreferences"] = spec["networkPreferences"]
+        payments[spec["name"]] = payment
+    return payments
+
+
+# ---------------------------------------------------------------------------
+# Deployed state
+# ---------------------------------------------------------------------------
+
+
+def _state_dict(existing_state: Any) -> dict[str, Any] | None:
+    """Existing deployed state as camelCase JSON (accepts a ``DeployedState`` model or a dict)."""
+    if existing_state is None:
+        return None
+    dump = getattr(existing_state, "model_dump", None)
+    if callable(dump):
+        return dump(mode="json", by_alias=True)
+    return dict(existing_state)
+
+
+def _non_empty(value: Mapping[str, Any] | None) -> bool:
+    return bool(value) and len(value) > 0  # type: ignore[arg-type]
+
+
+def build_deployed_state(
+    *,
+    target_name: str,
+    stack_name: str,
+    agents: Mapping[str, Record],
+    gateways: Mapping[str, Record],
+    http_gateways: Mapping[str, Record] | None = None,
+    existing_state: Any = None,
+    identity_kms_key_arn: str | None = None,
+    credentials: Mapping[str, Record] | None = None,
+    memories: Mapping[str, Record] | None = None,
+    evaluators: Mapping[str, Record] | None = None,
+    online_eval_configs: Mapping[str, Record] | None = None,
+    policy_engines: Mapping[str, Record] | None = None,
+    policies: Mapping[str, Record] | None = None,
+    runtime_endpoints: Mapping[str, Record] | None = None,
+    harnesses: Mapping[str, Record] | None = None,
+    datasets: Mapping[str, Record] | None = None,
+    config_bundles: Mapping[str, Record] | None = None,
+    knowledge_bases: Mapping[str, Record] | None = None,
+    payments: Mapping[str, Record] | None = None,
+    capacity_providers: Mapping[str, Record] | None = None,
+    ab_test_names: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Build the deployed-state JSON for ``target_name``, merged over ``existing_state``'s other targets."""
+    existing = _state_dict(existing_state)
+    existing_resources = ((existing or {}).get("targets") or {}).get(target_name, {}).get("resources") or {}
+
+    resources: Record = {}
+    if agents:
+        resources["runtimes"] = dict(agents)
+    if _non_empty(memories):
+        resources["memories"] = dict(memories)  # type: ignore[arg-type]
+    if _non_empty(policy_engines):
+        resources["policyEngines"] = dict(policy_engines)  # type: ignore[arg-type]
+    if _non_empty(policies):
+        resources["policies"] = dict(policies)  # type: ignore[arg-type]
+    resources["stackName"] = stack_name
+    if identity_kms_key_arn is not None:
+        resources["identityKmsKeyArn"] = identity_kms_key_arn
+
+    if gateways:
+        resources["mcp"] = {"gateways": dict(gateways)}
+    if _non_empty(http_gateways):
+        resources["gateways"] = dict(http_gateways)  # type: ignore[arg-type]
+    if _non_empty(credentials):
+        resources["credentials"] = dict(credentials)  # type: ignore[arg-type]
+    if _non_empty(evaluators):
+        resources["evaluators"] = dict(evaluators)  # type: ignore[arg-type]
+    if _non_empty(online_eval_configs):
+        resources["onlineEvalConfigs"] = dict(online_eval_configs)  # type: ignore[arg-type]
+    if _non_empty(runtime_endpoints):
+        resources["runtimeEndpoints"] = dict(runtime_endpoints)  # type: ignore[arg-type]
+    if _non_empty(datasets):
+        resources["datasets"] = dict(datasets)  # type: ignore[arg-type]
+    if _non_empty(knowledge_bases):
+        resources["knowledgeBases"] = dict(knowledge_bases)  # type: ignore[arg-type]
+
+    # Config bundles from CFN outputs (preferred) or carried forward from existing state (legacy).
+    if _non_empty(config_bundles):
+        resources["configBundles"] = dict(config_bundles)  # type: ignore[arg-type]
+    elif _non_empty(existing_resources.get("configBundles")):
+        resources["configBundles"] = existing_resources["configBundles"]
+
+    # AB tests are managed post-deploy; carry them forward, pruning tests no longer in the spec.
+    existing_ab_tests = existing_resources.get("abTests") or {}
+    if existing_ab_tests:
+        carried = (
+            existing_ab_tests
+            if ab_test_names is None
+            else {name: v for name, v in existing_ab_tests.items() if name in ab_test_names}
+        )
+        if carried:
+            resources["abTests"] = carried
+
+    # CFN-sourced harness records are authoritative; carry forward only orphan (imperative) records
+    # the current outputs don't cover, so they stay visible to detection/cleanup.
+    existing_harnesses = existing_resources.get("harnesses") or {}
+    carried_orphans = {
+        name: record
+        for name, record in existing_harnesses.items()
+        if not (harnesses or {}).get(name) and record.get("provisioner") != "cloudformation"
+    }
+    merged_harnesses = {**carried_orphans, **(harnesses or {})}
+    if merged_harnesses:
+        resources["harnesses"] = merged_harnesses
+
+    if _non_empty(payments):
+        resources["payments"] = dict(payments)  # type: ignore[arg-type]
+    if _non_empty(capacity_providers):
+        resources["capacityProviders"] = dict(capacity_providers)  # type: ignore[arg-type]
+
+    return {"targets": {**((existing or {}).get("targets") or {}), target_name: {"resources": resources}}}
+
+
+def get_stack_outputs_by_project(region: str, project_name: str, target_name: str = "default") -> StackOutputs:
+    """Discover the stack via tags, then DescribeStacks for its outputs."""
+    stack_name = get_stack_name(region, project_name, target_name)
+    if not stack_name:
+        raise RuntimeError(f'No AgentCore stack found for project "{project_name}" target "{target_name}"')
+    return get_stack_outputs(region, stack_name)
+
+
+__all__ = [
+    "StackOutputs",
+    "build_deployed_state",
+    "get_stack_outputs",
+    "get_stack_outputs_by_project",
+    "omit_payment_authorization_outputs",
+    "parse_agent_outputs",
+    "parse_capacity_provider_outputs",
+    "parse_config_bundle_outputs",
+    "parse_dataset_outputs",
+    "parse_evaluator_outputs",
+    "parse_gateway_outputs",
+    "parse_harness_outputs",
+    "parse_knowledge_base_data_source_outputs",
+    "parse_knowledge_base_outputs",
+    "parse_memory_outputs",
+    "parse_online_eval_outputs",
+    "parse_payment_outputs",
+    "parse_policy_engine_outputs",
+    "parse_policy_outputs",
+    "parse_runtime_endpoint_outputs",
+]

agentcore/cloudformation/stack_discovery.py

@@ -0,0 +1,75 @@
+"""Discover AgentCore stacks by tag (port of ``cloudformation/stack-discovery.ts``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws.account import create_aws_client
+
+TAG_PROJECT_NAME = "agentcore:project-name"
+TAG_TARGET_NAME = "agentcore:target-name"
+
+
+@dataclass(frozen=True)
+class DiscoveredStack:
+    stack_name: str
+    stack_arn: str
+    target_name: str
+
+
+def parse_stack_name_from_arn(arn: str) -> str | None:
+    """Stack name from ``arn:aws:cloudformation:region:account:stack/NAME/ID``; None for non-stack ARNs."""
+    if ":stack/" not in arn:
+        return None
+    stack_path = arn.split(":stack/", 1)[1]
+    if not stack_path:
+        return None
+    stack_name = stack_path.split("/")[0]
+    return stack_name or None
+
+
+def discover_stacks_by_project(region: str, project_name: str) -> list[DiscoveredStack]:
+    """All stacks tagged with ``project_name`` (Resource Groups Tagging API, all pages)."""
+    tagging = create_aws_client("resourcegroupstaggingapi", region)
+    stacks: list[DiscoveredStack] = []
+    token: str | None = None
+    while True:
+        params: dict[str, Any] = {
+            "TagFilters": [{"Key": TAG_PROJECT_NAME, "Values": [project_name]}],
+            "ResourceTypeFilters": ["cloudformation:stack"],
+        }
+        if token:
+            params["PaginationToken"] = token
+        response = tagging.get_resources(**params)
+        for resource in response.get("ResourceTagMappingList") or []:
+            arn = resource.get("ResourceARN")
+            if not arn:
+                continue
+            stack_name = parse_stack_name_from_arn(arn)
+            if not stack_name:
+                continue
+            target_tag = next((t for t in resource.get("Tags") or [] if t.get("Key") == TAG_TARGET_NAME), None)
+            target_name = (target_tag or {}).get("Value") or "default"
+            stacks.append(DiscoveredStack(stack_name=stack_name, stack_arn=arn, target_name=target_name))
+        token = response.get("PaginationToken")
+        if not token:
+            return stacks
+
+
+def find_stack(region: str, project_name: str, target_name: str = "default") -> DiscoveredStack | None:
+    return next((s for s in discover_stacks_by_project(region, project_name) if s.target_name == target_name), None)
+
+
+def get_stack_name(region: str, project_name: str, target_name: str = "default") -> str | None:
+    stack = find_stack(region, project_name, target_name)
+    return stack.stack_name if stack else None
+
+
+__all__ = [
+    "DiscoveredStack",
+    "discover_stacks_by_project",
+    "find_stack",
+    "get_stack_name",
+    "parse_stack_name_from_arn",
+]