agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/export/harness_mapper.py

@@ -0,0 +1,868 @@
+"""Map a harness spec onto a Strands runtime agent (port of src/cli/commands/export/harness-mapper.ts)."""
+
+from __future__ import annotations
+
+import re
+from types import SimpleNamespace
+from typing import Any
+
+from agentcore.aws.partition import arn_prefix, dns_suffix
+from agentcore.cli.commands.export.constants import (
+    ALLOWED_TOOLS_NOTE_CATEGORY,
+    AWS_SKILLS_NOTE_CATEGORY,
+    BROWSER_CODZIP_NOTE_CATEGORY,
+    CONTAINER_URI_ECR_PULL_NOTE_CATEGORY,
+    CONTAINER_URI_NOTE_CATEGORY,
+    GATEWAY_GRANT_TYPE_NOTE_CATEGORY,
+    GIT_SKILLS_CONTAINER_NOTE_CATEGORY,
+    LITELLM_NO_API_KEY_NOTE_CATEGORY,
+    MALFORMED_S3_SKILL_NOTE_CATEGORY,
+    MALFORMED_TOOL_ARN_NOTE_CATEGORY,
+    MCP_HEADER_CREDS_NOTE_CATEGORY,
+    PATH_SKILLS_NOTE_CATEGORY,
+)
+from agentcore.cli.commands.export.types import (
+    ExportNote,
+    HarnessMappingResult,
+    McpCredentialEntry,
+    ResolvedHarnessContext,
+)
+from agentcore.cli.commands.shared.filesystem_utils import build_filesystem_configurations
+from agentcore.lib import APP_DIR
+from agentcore.lib.errors.types import ValidationError
+from agentcore.primitives.credential_utils import (
+    compute_default_credential_env_var_name,
+    compute_managed_oauth_credential_name,
+)
+from agentcore.primitives.gateway import compute_default_gateway_env_var_name
+from agentcore.schema import (
+    BROWSER_ARN_PATTERN,
+    CODE_INTERPRETER_ARN_PATTERN,
+    DEFAULT_PYTHON_VERSION,
+    connection_env_token,
+    connection_id_for_target,
+    resource_id_from_arn,
+)
+from agentcore.templates.types import (
+    AgentRenderConfig,
+    GatewayProviderRenderConfig,
+    GitSkillRenderConfig,
+    HeaderCredentialRenderConfig,
+    IdentityProviderRenderConfig,
+    InlineFunctionToolRenderConfig,
+    MemoryProviderRenderConfig,
+    MountRenderConfig,
+    RemoteMcpToolRenderConfig,
+)
+
+DEFAULT_PYTHON_ENTRYPOINT = "main.py"
+
+
+# ============================================================================
+# Public entry point
+# ============================================================================
+
+
+def map_harness_to_export_config(
+    context: ResolvedHarnessContext, build_override: str | None = None
+) -> HarnessMappingResult:
+    spec, target = context.spec, context.target_agent_name
+    model = spec["model"]
+    skills = spec.get("skills") or []
+
+    build_type = resolve_build_type(spec, build_override)
+    if build_type == "CodeZip" and (spec.get("containerUri") or spec.get("dockerfile")):
+        what = (
+            f"containerUri ({spec['containerUri']})"
+            if spec.get("containerUri")
+            else f"dockerfile ({spec['dockerfile']})"
+        )
+        raise ValidationError(
+            f'Harness "{spec["name"]}" uses {what}, which requires a Container build. Re-export with --build Container.'
+        )
+
+    model_provider = resolve_model_provider(model["provider"])
+    allowed = spec.get("allowedTools") if spec.get("allowedTools") is not None else ["*"]
+    identity_provider, credential_entry = _resolve_identity_provider(spec, context)
+
+    if model["provider"] == "lite_llm" and not model.get("apiKeyArn") and not model["modelId"].startswith("bedrock/"):
+        context.export_notes.append(
+            ExportNote(
+                LITELLM_NO_API_KEY_NOTE_CATEGORY,
+                f'The LiteLLM model "{model["modelId"]}" is not a Bedrock-backed (bedrock/...) model, but the '
+                "harness has no apiKeyArn. The exported agent constructs LiteLLMModel without an API key and will "
+                "fail at first invocation if the provider requires one. Add an API-key credential to the harness "
+                "(model apiKeyArn), or use a bedrock/ model id (which authenticates via the execution role).",
+            )
+        )
+    _resolve_bedrock_mantle_policy(spec, context)
+
+    memory_providers, memory_connections = _resolve_memory_providers(spec, context)
+    gateway_providers, gateway_connections = _resolve_gateway_providers(spec, context, allowed)
+    tool_result = _resolve_browser_code_interpreter(spec, allowed, build_type, context)
+    has_execution_limits = any(spec.get(k) is not None for k in ("maxIterations", "maxTokens", "timeoutSeconds"))
+    has_skills_fetcher = len(skills) > 0
+
+    if not (len(allowed) == 1 and allowed[0] == "*"):
+        context.export_notes.append(
+            ExportNote(
+                ALLOWED_TOOLS_NOTE_CATEGORY,
+                "The harness allowedTools filter has been applied statically at code-generation time. "
+                "Tools excluded at export will not be available at runtime, and callers cannot override "
+                "the tool list per invocation (unlike the harness).",
+            )
+        )
+
+    path_skills = [s for s in skills if is_path_skill(s)]
+    if path_skills and build_type == "CodeZip":
+        context.export_notes.append(
+            ExportNote(
+                PATH_SKILLS_NOTE_CATEGORY,
+                "The following skill paths must exist on the container filesystem at runtime: "
+                f"{', '.join(str(s.get('path')) for s in path_skills)}. "
+                "For CodeZip builds, path skills are not supported — switch to a Container build and COPY the "
+                "skill directory in your Dockerfile, or use s3/git skill variants.",
+            )
+        )
+
+    if any(is_git_skill(s) for s in skills) and build_type == "Container":
+        context.export_notes.append(
+            ExportNote(
+                GIT_SKILLS_CONTAINER_NOTE_CATEGORY,
+                "The agent clones git skill repositories at runtime using `git`. The default Container base image "
+                "(`python:3.12-slim`) does not include git. Add it to your Dockerfile before deploying:\n\n"
+                "  RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*",
+            )
+        )
+
+    s3_skills = [s for s in skills if is_s3_skill(s)]
+    if s3_skills:
+        malformed: list[str] = []
+        arns: list[dict[str, str]] = []
+        for skill in s3_skills:
+            parsed = parse_s3_skill_arns(skill["s3Uri"], context.region)
+            if parsed:
+                arns.append(parsed)
+            else:
+                malformed.append(skill["s3Uri"])
+        if malformed:
+            quoted = ", ".join(f'"{u}"' for u in malformed)
+            context.export_notes.append(
+                ExportNote(
+                    MALFORMED_S3_SKILL_NOTE_CATEGORY,
+                    "These S3 skill URIs could not be parsed into a bucket, so no S3 read permission was "
+                    f"generated for them: {quoted}. The exported agent "
+                    "still attempts to fetch these skills at runtime and will fail with S3 AccessDenied. Fix the "
+                    "s3Uri values (expected `s3://<bucket>/<prefix>`) on this agent's skills in "
+                    "agentcore/agentcore.json and re-deploy.",
+                )
+            )
+        if arns:
+            policy = {
+                "Version": "2012-10-17",
+                "Statement": [
+                    {"Effect": "Allow", "Action": "s3:GetObject", "Resource": _unique(a["objectArn"] for a in arns)},
+                    {"Effect": "Allow", "Action": "s3:ListBucket", "Resource": _unique(a["bucketArn"] for a in arns)},
+                ],
+            }
+            policy_file = "s3-skills-policy.json"
+            context.generated_policy_files[policy_file] = policy
+            if policy_file not in context.additional_policies:
+                context.additional_policies.append(policy_file)
+
+    aws_skills = [s for s in skills if is_aws_skill(s)]
+    if aws_skills:
+        patterns = "; ".join(
+            ", ".join(s["awsSkills"]["paths"]) if (s.get("awsSkills") or {}).get("paths") is not None else "all"
+            for s in aws_skills
+        )
+        context.export_notes.append(
+            ExportNote(
+                AWS_SKILLS_NOTE_CATEGORY,
+                "AWS skills are a managed harness feature and are not available in standalone Strands agents. "
+                f"The following skill patterns have been omitted: {patterns}. "
+                "You can copy the equivalent skills from https://github.com/aws/agent-toolkit-for-aws/tree/main/skills "
+                "into your project and load them as path or git skills instead.",
+            )
+        )
+
+    container_uri = spec.get("containerUri")
+    if container_uri:
+        context.export_notes.append(
+            ExportNote(
+                CONTAINER_URI_NOTE_CATEGORY,
+                f"The harness used a pre-built container image as its execution environment ({container_uri}). "
+                "The generated Dockerfile extends that image directly (FROM <containerUri>) and layers the Strands "
+                "agent code on top. If your base image does not include Python 3.12+ or uv, add an install step "
+                "before the `uv sync` steps.",
+            )
+        )
+        ecr_arn = ecr_arn_from_uri(container_uri, context.region)
+        if ecr_arn:
+            context.export_notes.append(
+                ExportNote(
+                    CONTAINER_URI_ECR_PULL_NOTE_CATEGORY,
+                    f"The base image ({container_uri}) is a private ECR repository. The CodeBuild project that "
+                    "builds this agent's container is not automatically granted permission to pull it.\n\n"
+                    "Add the following to agentcore/cdk/lib/cdk-stack.ts after `this.application` is created:\n\n"
+                    "  import * as ecr from 'aws-cdk-lib/aws-ecr';\n"
+                    "  import { ContainerBuildProject } from '@aws/agentcore-cdk';\n\n"
+                    f"  const baseRepo = ecr.Repository.fromRepositoryArn(this, 'BaseImageEcrRepository', '{ecr_arn}');\n"
+                    "  baseRepo.grantPull(ContainerBuildProject.getOrCreate(this).role);",
+                )
+            )
+
+    mcp_tools, mcp_credentials = _resolve_remote_mcp_tools(spec, allowed, context)
+
+    efs = [MountRenderConfig(mount_path=ap["mountPath"]) for ap in spec.get("efsAccessPoints") or []]
+    s3 = [MountRenderConfig(mount_path=ap["mountPath"]) for ap in spec.get("s3AccessPoints") or []]
+    memory = spec.get("memory") or {}
+    is_lite = model["provider"] == "lite_llm"
+    render_config = AgentRenderConfig(
+        name=target,
+        sdk_framework="Strands",
+        target_language="Python",
+        model_provider=model_provider,  # type: ignore[arg-type]
+        has_memory=len(memory_providers) > 0,
+        has_identity=identity_provider is not None,
+        has_gateway=len(gateway_providers) > 0,
+        is_vpc=spec.get("networkMode") == "VPC",
+        build_type=build_type,  # type: ignore[arg-type]
+        memory_providers=memory_providers,
+        identity_providers=[identity_provider] if identity_provider else [],
+        gateway_providers=gateway_providers,
+        gateway_auth_types=_unique(g.auth_type for g in gateway_providers),
+        protocol="HTTP",
+        dockerfile=resolve_dockerfile_name(spec, build_type),
+        enable_otel=True,
+        has_config_bundle=False,
+        has_payment=False,
+        max_iterations=spec.get("maxIterations"),
+        max_tokens=spec.get("maxTokens"),
+        timeout_seconds=spec.get("timeoutSeconds"),
+        truncation_strategy=(spec.get("truncation") or {}).get("strategy"),
+        truncation_config=resolve_truncation_config(spec.get("truncation")),
+        remote_mcp_tools=mcp_tools,
+        session_storage_mount_path=spec.get("sessionStoragePath"),
+        efs_mounts=efs,
+        s3_mounts=s3,
+        needs_os=bool(spec.get("sessionStoragePath")) or bool(efs) or bool(s3),
+        path_skills=[s.get("path") for s in skills if is_path_skill(s)],
+        s3_skills=[s["s3Uri"] for s in s3_skills],
+        git_skills=[
+            GitSkillRenderConfig(
+                url=s["gitUrl"],
+                path=s.get("path"),
+                credential_arn=(s.get("auth") or {}).get("credentialName"),
+                username=(s.get("auth") or {}).get("username"),
+            )
+            for s in skills
+            if is_git_skill(s)
+        ],
+        has_skills_fetcher=has_skills_fetcher,
+        has_fetched_skills=any(is_s3_skill(s) or is_git_skill(s) for s in skills),
+        inline_function_tools=_resolve_inline_function_tools(spec, allowed),
+        has_browser=tool_result["hasBrowser"],
+        browser_identifier_env_var=tool_result.get("browserIdentifierEnvVar"),
+        has_code_interpreter=tool_result["hasCodeInterpreter"],
+        code_interpreter_identifier_env_var=tool_result.get("codeInterpreterIdentifierEnvVar"),
+        has_shell=is_builtin_included("shell", allowed),
+        has_file_operations=is_builtin_included("file_operations", allowed),
+        has_execution_limits=has_execution_limits,
+        is_export_harness=True,
+        model_id=model["modelId"],
+        model_max_tokens=model.get("maxTokens"),
+        litellm_api_base=model.get("apiBase") if is_lite and model.get("apiBase") else None,
+        litellm_additional_params=model.get("additionalParams") if is_lite and model.get("additionalParams") else None,
+        system_prompt_text=context.system_prompt,
+        actor_id=memory.get("actorId") if memory.get("mode") == "existing" else None,
+        **_bedrock_mantle_render_config(spec),
+    )
+
+    connections = [*memory_connections, *gateway_connections, *tool_result["connections"]]
+    agent_env_spec = _build_agent_env_spec(context, target, build_type, connections)
+
+    git_credentials: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for skill in skills:
+        name = (skill.get("auth") or {}).get("credentialName") if is_git_skill(skill) else None
+        if not name:
+            continue
+        cred = resource_id_from_arn(name)
+        if cred in seen:
+            continue
+        seen.add(cred)
+        git_credentials.append({"authorizerType": "ApiKeyCredentialProvider", "name": cred})
+
+    return HarnessMappingResult(
+        render_config=render_config,
+        agent_env_spec=agent_env_spec,
+        credential_entry=credential_entry,
+        mcp_credential_entries=mcp_credentials,
+        git_credential_entries=git_credentials,
+    )
+
+
+def _unique(values: Any) -> list[Any]:
+    out: list[Any] = []
+    for v in values:
+        if v not in out:
+            out.append(v)
+    return out
+
+
+# ============================================================================
+# AgentEnvSpec
+# ============================================================================
+
+
+def _build_agent_env_spec(
+    context: ResolvedHarnessContext, target: str, build_type: str, connections: list[dict[str, Any]]
+) -> dict[str, Any]:
+    spec = context.spec
+    agent: dict[str, Any] = {"name": target, "build": build_type}
+    dockerfile = resolve_dockerfile_name(spec, build_type)
+    if dockerfile:
+        agent["dockerfile"] = dockerfile
+    agent.update(
+        {
+            "entrypoint": DEFAULT_PYTHON_ENTRYPOINT,
+            "codeLocation": f"{APP_DIR}/{target}/",
+            "runtimeVersion": DEFAULT_PYTHON_VERSION,
+            "networkMode": spec.get("networkMode") or "PUBLIC",
+            "protocol": "HTTP",
+        }
+    )
+    if spec.get("networkMode") == "VPC" and spec.get("networkConfig"):
+        agent["networkConfig"] = spec["networkConfig"]
+    if spec.get("authorizerType"):
+        agent["authorizerType"] = spec["authorizerType"]
+    if spec.get("authorizerConfiguration"):
+        agent["authorizerConfiguration"] = spec["authorizerConfiguration"]
+    lifecycle = spec.get("lifecycleConfig")
+    if lifecycle:
+        agent["lifecycleConfiguration"] = {
+            k: lifecycle[k] for k in ("idleRuntimeSessionTimeout", "maxLifetime") if lifecycle.get(k) is not None
+        }
+    if spec.get("executionRoleArn"):
+        agent["executionRoleArn"] = spec["executionRoleArn"]
+    env_vars = [{"name": k, "value": v} for k, v in (spec.get("environmentVariables") or {}).items()]
+    if env_vars:
+        agent["envVars"] = env_vars
+    if connections:
+        agent["connections"] = connections
+    if context.additional_policies:
+        agent["additionalPolicies"] = list(context.additional_policies)
+    if spec.get("tags"):
+        agent["tags"] = spec["tags"]
+    agent.update(
+        build_filesystem_configurations(
+            spec.get("sessionStoragePath"), spec.get("efsAccessPoints"), spec.get("s3AccessPoints")
+        )
+    )
+    return agent
+
+
+# ============================================================================
+# Connection helpers
+# ============================================================================
+
+
+def external_connection_id(kind: str, arn: str | None) -> str:
+    return connection_id_for_target(SimpleNamespace(type=kind, arn=arn))  # type: ignore[arg-type]
+
+
+def connection_env_var_name(prefix: str, connection_id: str, suffix: str) -> str:
+    return f"{prefix}_{connection_env_token(connection_id)}_{suffix}"
+
+
+def to_connection_gateway_auth(outbound: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not outbound:
+        return None
+    if "awsIam" in outbound:
+        return {"awsIam": {}}
+    if "none" in outbound:
+        return {"none": {}}
+    oauth = outbound["oauth"]
+    grant = {"USER_FEDERATION": "AUTHORIZATION_CODE", "CLIENT_CREDENTIALS": "CLIENT_CREDENTIALS"}.get(
+        oauth.get("grantType") or ""
+    )
+    out: dict[str, Any] = {"providerArn": oauth["providerArn"], "scopes": oauth["scopes"]}
+    if grant:
+        out["grantType"] = grant
+    if oauth.get("customParameters"):
+        out["customParameters"] = oauth["customParameters"]
+    return {"oauth": out}
+
+
+def grant_type_to_auth_flow(grant_type: str | None) -> str | None:
+    if grant_type in (None, "CLIENT_CREDENTIALS"):
+        return "M2M"
+    if grant_type == "USER_FEDERATION":
+        return "USER_FEDERATION"
+    return None
+
+
+# ============================================================================
+# Model provider
+# ============================================================================
+
+
+def resolve_model_provider(provider: str) -> str:
+    return {"bedrock": "Bedrock", "open_ai": "OpenAI", "gemini": "Gemini", "lite_llm": "LiteLLM"}[provider]
+
+
+def _is_proprietary_openai_model(model_id: str) -> bool:
+    return model_id.startswith("openai.") and "gpt-oss" not in model_id
+
+
+def is_bedrock_mantle_model(spec: dict[str, Any]) -> bool:
+    model = spec["model"]
+    return model["provider"] == "bedrock" and model.get("apiFormat") in ("responses", "chat_completions")
+
+
+def _bedrock_mantle_render_config(spec: dict[str, Any]) -> dict[str, Any]:
+    if not is_bedrock_mantle_model(spec):
+        return {}
+    model = spec["model"]
+    return {
+        "bedrock_mantle": True,
+        "mantle_api_format": model["apiFormat"],
+        "mantle_proprietary": _is_proprietary_openai_model(model["modelId"]),
+        "model_temperature": model.get("temperature"),
+        "model_top_p": model.get("topP"),
+    }
+
+
+def _resolve_bedrock_mantle_policy(spec: dict[str, Any], context: ResolvedHarnessContext) -> None:
+    if not is_bedrock_mantle_model(spec):
+        return
+    prefix = arn_prefix(context.region or "us-east-1")
+    policy = {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Action": "bedrock-mantle:CreateInference",
+                "Resource": f"{prefix}:bedrock-mantle:*:*:project/default",
+            },
+            {"Effect": "Allow", "Action": "bedrock-mantle:CallWithBearerToken", "Resource": "*"},
+        ],
+    }
+    policy_file = "bedrock-mantle-policy.json"
+    context.generated_policy_files[policy_file] = policy
+    if policy_file not in context.additional_policies:
+        context.additional_policies.append(policy_file)
+
+
+# ============================================================================
+# Identity / memory / gateway
+# ============================================================================
+
+
+def _resolve_identity_provider(
+    spec: dict[str, Any], context: ResolvedHarnessContext
+) -> tuple[IdentityProviderRenderConfig | None, dict[str, Any] | None]:
+    model = spec["model"]
+    if model["provider"] == "bedrock":
+        return None, None
+    api_key_arn = model.get("apiKeyArn")
+    if not api_key_arn:
+        return None, None
+    for credential in context.project_spec.get("credentials") or []:
+        if "apiKeyArn" in credential:
+            matches = credential.get("apiKeyArn") == api_key_arn
+        elif "credentialProviderArn" in credential:
+            matches = credential.get("credentialProviderArn") == api_key_arn
+        else:
+            matches = False
+        if matches:
+            name = credential["name"]
+            return IdentityProviderRenderConfig(
+                name=name, env_var_name=compute_default_credential_env_var_name(name)
+            ), None
+    match = re.search(r"/apikeycredentialprovider/([^/]+)$", api_key_arn)
+    name = match.group(1) if match else f"{context.project_spec['name']}{resolve_model_provider(model['provider'])}"
+    return (
+        IdentityProviderRenderConfig(name=name, env_var_name=compute_default_credential_env_var_name(name)),
+        {"authorizerType": "ApiKeyCredentialProvider", "name": name},
+    )
+
+
+def _strategy_types(context: ResolvedHarnessContext, memory_name: str) -> list[str]:
+    entry = next((m for m in context.project_spec.get("memories") or [] if m["name"] == memory_name), None)
+    return [s["type"] for s in (entry or {}).get("strategies") or []]
+
+
+def _resolve_memory_providers(
+    spec: dict[str, Any], context: ResolvedHarnessContext
+) -> tuple[list[MemoryProviderRenderConfig], list[dict[str, Any]]]:
+    memory = spec.get("memory") or {}
+    if memory.get("mode") != "existing":
+        return [], []
+    name, arn = memory.get("name"), memory.get("arn")
+    if name:
+        return [
+            MemoryProviderRenderConfig(
+                name=name, env_var_name=f"MEMORY_{name.upper()}_ID", strategies=_strategy_types(context, name)
+            )
+        ], []
+    if arn:
+        deployed = (context.deployed_resources or {}).get("memories") or {}
+        resolved = next((n for n, state in deployed.items() if (state or {}).get("memoryArn") == arn), None)
+        if resolved:
+            return [
+                MemoryProviderRenderConfig(
+                    name=resolved,
+                    env_var_name=f"MEMORY_{resolved.upper()}_ID",
+                    strategies=_strategy_types(context, resolved),
+                )
+            ], []
+        connection_id = external_connection_id("memory", arn)
+        env_var = connection_env_var_name("MEMORY", connection_id, "ID")
+        context.local_env_vars[env_var] = resource_id_from_arn(arn)
+        return (
+            [MemoryProviderRenderConfig(name=connection_id, env_var_name=env_var, strategies=[])],
+            [{"id": connection_id, "to": {"type": "memory", "arn": arn}, "access": "readwrite"}],
+        )
+    return [], []
+
+
+def _resolve_gateway_providers(
+    spec: dict[str, Any], context: ResolvedHarnessContext, allowed: list[str]
+) -> tuple[list[GatewayProviderRenderConfig], list[dict[str, Any]]]:
+    providers: list[GatewayProviderRenderConfig] = []
+    connections: list[dict[str, Any]] = []
+    for tool in spec.get("tools") or []:
+        if tool.get("type") != "agentcore_gateway":
+            continue
+        config = tool.get("config") or {}
+        if "agentCoreGateway" not in config:
+            continue
+        if not matches_allowed_tools(tool["name"], allowed):
+            continue
+        gw = config["agentCoreGateway"]
+        gateway_arn = gw["gatewayArn"]
+        deployed = (((context.deployed_resources or {}).get("mcp") or {}).get("gateways")) or {}
+        match = next((n for n, state in deployed.items() if (state or {}).get("gatewayArn") == gateway_arn), None)
+        if match:
+            project_gateway = next(
+                (g for g in context.project_spec.get("agentCoreGateways") or [] if g["name"] == match), None
+            )
+            auth_type = (project_gateway or {}).get("authorizerType") or "AWS_IAM"
+            provider = GatewayProviderRenderConfig(
+                name=match, env_var_name=compute_default_gateway_env_var_name(match), auth_type=auth_type
+            )
+            jwt = ((project_gateway or {}).get("authorizerConfiguration") or {}).get("customJwtAuthorizer")
+            if auth_type == "CUSTOM_JWT" and jwt:
+                provider.discovery_url = jwt.get("discoveryUrl")
+                provider.credential_provider_name = compute_managed_oauth_credential_name(match)
+                if jwt.get("allowedScopes"):
+                    provider.scopes = " ".join(jwt["allowedScopes"])
+            providers.append(provider)
+            continue
+
+        outbound = gw.get("outboundAuth")
+        if outbound:
+            auth_type = "CUSTOM_JWT" if "oauth" in outbound else "AWS_IAM" if "awsIam" in outbound else "NONE"
+        else:
+            auth_type = "AWS_IAM"
+        connection_id = external_connection_id("gateway", gateway_arn)
+        target: dict[str, Any] = {"type": "gateway", "arn": gateway_arn}
+        mapped = to_connection_gateway_auth(outbound)
+        if mapped is not None:
+            target["outboundAuth"] = mapped
+        connections.append({"id": connection_id, "to": target})
+        url_env = connection_env_var_name("GATEWAY", connection_id, "URL")
+        context.local_env_vars[url_env] = derive_gateway_url(gateway_arn)
+        provider = GatewayProviderRenderConfig(name=tool["name"], env_var_name=url_env, auth_type=auth_type)
+        if auth_type == "CUSTOM_JWT" and outbound and "oauth" in outbound:
+            oauth = outbound["oauth"]
+            provider.credential_provider_name = resource_id_from_arn(oauth["providerArn"])
+            if oauth.get("scopes"):
+                provider.scopes = " ".join(oauth["scopes"])
+            auth_flow = grant_type_to_auth_flow(oauth.get("grantType"))
+            if auth_flow:
+                provider.auth_flow = auth_flow
+            if oauth.get("customParameters"):
+                provider.custom_parameters = oauth["customParameters"]
+            if not auth_flow:
+                context.export_notes.append(
+                    ExportNote(
+                        GATEWAY_GRANT_TYPE_NOTE_CATEGORY,
+                        f'Gateway tool "{tool["name"]}" uses OAuth grant type "{oauth.get("grantType")}", which the '
+                        "generated MCP client cannot express (the AgentCore Identity decorator supports only M2M and "
+                        "USER_FEDERATION flows). Update mcp_client/client.py to perform the token exchange manually, or "
+                        "reconfigure the gateway to use CLIENT_CREDENTIALS or AUTHORIZATION_CODE.",
+                    )
+                )
+        providers.append(provider)
+    return providers, connections
+
+
+# ============================================================================
+# Tools
+# ============================================================================
+
+
+def _resolve_inline_function_tools(spec: dict[str, Any], allowed: list[str]) -> list[InlineFunctionToolRenderConfig]:
+    return [
+        InlineFunctionToolRenderConfig(
+            name=t["name"],
+            description=t["config"]["inlineFunction"]["description"],
+            input_schema=t["config"]["inlineFunction"]["inputSchema"],
+        )
+        for t in spec.get("tools") or []
+        if t.get("type") == "inline_function" and matches_allowed_tools(t["name"], allowed)
+    ]
+
+
+def _resolve_remote_mcp_tools(
+    spec: dict[str, Any], allowed: list[str], context: ResolvedHarnessContext
+) -> tuple[list[RemoteMcpToolRenderConfig], list[McpCredentialEntry]]:
+    tools: list[RemoteMcpToolRenderConfig] = []
+    entries: list[McpCredentialEntry] = []
+    for tool in spec.get("tools") or []:
+        if tool.get("type") != "remote_mcp" or not matches_allowed_tools(tool["name"], allowed):
+            continue
+        config = tool.get("config") or {}
+        if "remoteMcp" not in config:
+            continue
+        remote = config["remoteMcp"]
+        headers = remote.get("headers") or {}
+        header_credentials: list[HeaderCredentialRenderConfig] | None = None
+        if headers:
+            header_credentials = []
+            tool_prefix = re.sub(r"[^A-Za-z0-9]", "", tool["name"])
+            for header in headers:
+                cred = f"{context.project_spec['name']}Mcp{tool_prefix}{re.sub(r'[^A-Za-z0-9]', '', header)}"
+                env_var = compute_default_credential_env_var_name(cred)
+                header_credentials.append(
+                    HeaderCredentialRenderConfig(header_key=header, credential_name=cred, env_var_name=env_var)
+                )
+                entries.append(
+                    McpCredentialEntry(
+                        credential={"authorizerType": "ApiKeyCredentialProvider", "name": cred},
+                        env_var_name=env_var,
+                        value=headers.get(header) or "",
+                    )
+                )
+            context.export_notes.append(
+                ExportNote(
+                    MCP_HEADER_CREDS_NOTE_CATEGORY,
+                    f'MCP tool "{tool["name"]}" has request headers managed via AgentCore Identity. '
+                    "Credential entries added to agentcore.json; values written to agentcore/.env.local. "
+                    "Credentials are provisioned automatically on `agentcore deploy`.\n\n"
+                    + "\n".join(f"  {h.credential_name}  (env var: {h.env_var_name})" for h in header_credentials),
+                )
+            )
+        tools.append(
+            RemoteMcpToolRenderConfig(name=tool["name"], url=remote["url"], header_credentials=header_credentials)
+        )
+    return tools, entries
+
+
+def _resolve_browser_code_interpreter(
+    spec: dict[str, Any], allowed: list[str], build_type: str, context: ResolvedHarnessContext
+) -> dict[str, Any]:
+    result: dict[str, Any] = {"connections": [], "hasBrowser": False, "hasCodeInterpreter": False}
+    if _is_tool_included("agentcore_browser", spec, allowed):
+        if build_type != "Container":
+            context.export_notes.append(
+                ExportNote(
+                    BROWSER_CODZIP_NOTE_CATEGORY,
+                    "The browser tool requires a Container build to run. In a CodeZip (Lambda-style) runtime the "
+                    "Playwright node driver cannot be executed and the tool will fail at invocation time.\n\n"
+                    "Re-export with `--build Container` to include browser tool support:\n\n"
+                    f"  agentcore export harness --name {spec['name']} --target-agent-name {context.target_agent_name} "
+                    "--build Container",
+                )
+            )
+        else:
+            result["hasBrowser"] = True
+            raw = _extract_raw_tool_arn(spec, "agentcore_browser", "agentCoreBrowser", "browserArn")
+            arn = _valid_tool_arn(raw, "browser")
+            if arn:
+                cid = external_connection_id("browser", arn)
+                env_var = connection_env_var_name("BROWSER", cid, "ID")
+                result["connections"].append({"id": cid, "to": {"type": "browser", "arn": arn}})
+                result["browserIdentifierEnvVar"] = env_var
+                context.local_env_vars[env_var] = resource_id_from_arn(arn)
+            else:
+                if raw:
+                    context.export_notes.append(_malformed_tool_arn_note("browser", raw))
+                result["connections"].append({"id": "browser-default", "to": {"type": "browser"}})
+    if _is_tool_included("agentcore_code_interpreter", spec, allowed):
+        result["hasCodeInterpreter"] = True
+        raw = _extract_raw_tool_arn(
+            spec, "agentcore_code_interpreter", "agentCoreCodeInterpreter", "codeInterpreterArn"
+        )
+        arn = _valid_tool_arn(raw, "code-interpreter")
+        if arn:
+            cid = external_connection_id("codeInterpreter", arn)
+            env_var = connection_env_var_name("CODE_INTERPRETER", cid, "ID")
+            result["connections"].append({"id": cid, "to": {"type": "codeInterpreter", "arn": arn}})
+            result["codeInterpreterIdentifierEnvVar"] = env_var
+            context.local_env_vars[env_var] = resource_id_from_arn(arn)
+        else:
+            if raw:
+                context.export_notes.append(_malformed_tool_arn_note("code-interpreter", raw))
+            result["connections"].append({"id": "codeInterpreter-default", "to": {"type": "codeInterpreter"}})
+    return result
+
+
+def _malformed_tool_arn_note(kind: str, raw: str) -> ExportNote:
+    return ExportNote(
+        MALFORMED_TOOL_ARN_NOTE_CATEGORY,
+        f'The {kind} tool specified ARN "{raw}", which is not a valid bedrock-agentcore {kind} ARN. '
+        f"The exported agent will use the AWS-managed default {kind} instead (a different resource, granted "
+        f"broader `{kind}/*` permissions). If you intended to target a specific {kind}, fix the ARN in the "
+        "connection on this agent in agentcore/agentcore.json and re-deploy.",
+    )
+
+
+def _extract_raw_tool_arn(spec: dict[str, Any], tool_type: str, config_key: str, arn_field: str) -> str | None:
+    tool = next((t for t in spec.get("tools") or [] if t.get("type") == tool_type), None)
+    config = (tool or {}).get("config") or {}
+    if config_key not in config:
+        return None
+    return (config.get(config_key) or {}).get(arn_field)
+
+
+def _valid_tool_arn(arn: str | None, kind: str) -> str | None:
+    if not arn:
+        return None
+    pattern = BROWSER_ARN_PATTERN if kind == "browser" else CODE_INTERPRETER_ARN_PATTERN
+    return arn if pattern.search(arn) else None
+
+
+def _is_tool_included(tool_type: str, spec: dict[str, Any], allowed: list[str]) -> bool:
+    tool = next((t for t in spec.get("tools") or [] if t.get("type") == tool_type), None)
+    return bool(tool) and matches_allowed_tools(tool["name"], allowed)
+
+
+# ============================================================================
+# Helpers
+# ============================================================================
+
+
+def resolve_build_type(spec: dict[str, Any], override: str | None = None) -> str:
+    if override:
+        return override
+    return "Container" if spec.get("containerUri") or spec.get("dockerfile") else "CodeZip"
+
+
+def resolve_dockerfile_name(spec: dict[str, Any], build_type: str) -> str | None:
+    if build_type != "Container":
+        return None
+    if spec.get("dockerfile"):
+        return spec["dockerfile"]
+    if spec.get("containerUri"):
+        return "Dockerfile"
+    return None
+
+
+def derive_gateway_url(gateway_arn: str) -> str:
+    parts = gateway_arn.split(":")
+    region = parts[3] if len(parts) > 3 else "us-east-1"
+    gateway_id = parts[-1].replace("gateway/", "", 1)
+    return f"https://{gateway_id}.gateway.bedrock-agentcore.{region}.{dns_suffix(region)}/mcp"
+
+
+def ecr_arn_from_uri(uri: str, region: str | None = None) -> str | None:
+    match = re.match(r"^(\d{12})\.dkr\.ecr\.([^.]+)\.[^/]+/([^:@]+)", uri)
+    if not match:
+        return None
+    account, ecr_region, repo = match.group(1), match.group(2) or region, match.group(3)
+    if not ecr_region or not repo:
+        return None
+    return f"{arn_prefix(ecr_region)}:ecr:{ecr_region}:{account}:repository/{repo}"
+
+
+def is_path_skill(skill: dict[str, Any]) -> bool:
+    return "path" in skill and "gitUrl" not in skill
+
+
+def is_s3_skill(skill: dict[str, Any]) -> bool:
+    return "s3Uri" in skill
+
+
+def is_git_skill(skill: dict[str, Any]) -> bool:
+    return "gitUrl" in skill
+
+
+def is_aws_skill(skill: dict[str, Any]) -> bool:
+    return "awsSkills" in skill
+
+
+def parse_s3_skill_arns(s3_uri: str, region: str | None = None) -> dict[str, str] | None:
+    without_scheme = re.sub(r"^s3://", "", s3_uri)
+    bucket, *prefix_parts = without_scheme.split("/")
+    if not bucket:
+        return None
+    bucket_arn = f"{arn_prefix(region or 'us-east-1')}:s3:::{bucket}"
+    prefix = re.sub(r"/+$", "", "/".join(prefix_parts))
+    return {
+        "bucket": bucket,
+        "bucketArn": bucket_arn,
+        "objectArn": f"{bucket_arn}/{prefix}/*" if prefix else f"{bucket_arn}/*",
+    }
+
+
+def fnmatch(pattern: str, value: str) -> bool:
+    escaped = re.sub(r"[.+^${}()|\[\]\\]", lambda m: "\\" + m.group(0), pattern)
+    return re.fullmatch(escaped.replace("*", ".*").replace("?", "."), value, re.S) is not None
+
+
+def matches_allowed_tools(tool_name: str, patterns: list[str]) -> bool:
+    if "*" in patterns:
+        return True
+    for pattern in patterns:
+        if pattern == tool_name:
+            return True
+        if pattern.startswith("@"):
+            slash = pattern.find("/", 1)
+            p_server = pattern[1:] if slash == -1 else pattern[1:slash]
+            p_tool = "*" if slash == -1 else pattern[slash + 1 :]
+            name_slash = tool_name.find("/")
+            if name_slash == -1:
+                if fnmatch(f"{p_server}_{p_tool}", tool_name):
+                    return True
+            elif fnmatch(p_server, tool_name[:name_slash]) and fnmatch(p_tool, tool_name[name_slash + 1 :]):
+                return True
+        elif fnmatch(pattern, tool_name):
+            return True
+    return False
+
+
+def is_builtin_included(name: str, patterns: list[str]) -> bool:
+    return matches_allowed_tools(f"builtin/{name}", patterns)
+
+
+def resolve_truncation_config(truncation: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not truncation or not truncation.get("config"):
+        return None
+    strategy, config = truncation.get("strategy"), truncation["config"]
+    if strategy == "sliding_window" and "slidingWindow" in config:
+        window = config.get("slidingWindow") or {}
+        return {"window_size": window["messagesCount"]} if window.get("messagesCount") is not None else None
+    if strategy == "summarization" and "summarization" in config:
+        s = config.get("summarization") or {}
+        key_map = {
+            "summaryRatio": "summary_ratio",
+            "preserveRecentMessages": "preserve_recent_messages",
+            "summarizationSystemPrompt": "summarization_system_prompt",
+        }
+        out = {v: s[k] for k, v in key_map.items() if s.get(k) is not None}
+        return out or None
+    return None
+
+
+__all__ = [
+    "fnmatch",
+    "is_path_skill",
+    "map_harness_to_export_config",
+    "matches_allowed_tools",
+    "parse_s3_skill_arns",
+    "resolve_truncation_config",
+]