agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/_harness_validation.py

@@ -0,0 +1,163 @@
+"""`add harness` flag validation (port of ``validateAddHarnessOptions`` in src/cli/commands/add/validate.ts).
+
+``options`` is a dict keyed by upstream camelCase CLI option names (``AddHarnessCliOptions``).
+``memory`` is ``False`` for ``--no-memory`` (Commander's negated boolean), ``True``/absent otherwise.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentcore.cli.commands.add._common import ValidationResult
+from agentcore.cli.commands.add.auth_options import validate_jwt_authorizer_options
+from agentcore.cli.commands.shared.arn_utils import ARN_VALIDATION_MESSAGE, is_valid_arn
+from agentcore.cli.commands.shared.vpc_utils import validate_vpc_options
+from agentcore.schema import validate_api_format
+
+VALID_HARNESS_TOOLS = ("agentcore_browser", "agentcore_code_interpreter", "remote_mcp", "agentcore_gateway")
+VALID_GATEWAY_OUTBOUND_AUTH = ("awsIam", "none", "oauth")
+VALID_MEMORY_MODES = ("managed", "existing", "disabled")
+# Managed harness memory excludes CUSTOM (only the four; CUSTOM is for standalone memory).
+VALID_MANAGED_STRATEGIES = ("SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE", "EPISODIC")
+RUNTIME_AUTHORIZER_TYPES = ("AWS_IAM", "CUSTOM_JWT")
+
+
+def _api_format_result(result: Any) -> tuple[bool, str | None]:
+    if isinstance(result, dict):
+        return bool(result.get("valid")), result.get("error")
+    return bool(getattr(result, "valid", False)), getattr(result, "error", None)
+
+
+def validate_add_harness_options(options: dict[str, Any]) -> ValidationResult:
+    o = options
+    if o.get("apiFormat"):
+        provider = o.get("modelProvider") or "bedrock"
+        valid, error = _api_format_result(validate_api_format(o["apiFormat"], provider))
+        if not valid:
+            return ValidationResult(False, error)
+
+    # Any --container value is a container build (a dockerfile path AND a prebuilt image URI both
+    # run CodeBuild), so both require --vpc-id in VPC mode.
+    harness_build_type = "Container" if o.get("container") else None
+    vpc = validate_vpc_options(o, harness_build_type)
+    if not vpc.valid:
+        return ValidationResult(False, vpc.error)
+
+    if o.get("tools"):
+        tool_names = [s.strip() for s in o["tools"].split(",")]
+        for tool in tool_names:
+            if tool not in VALID_HARNESS_TOOLS:
+                return ValidationResult(False, f"Unknown tool '{tool}'. Valid tools: {', '.join(VALID_HARNESS_TOOLS)}")
+        if "remote_mcp" in tool_names:
+            if not o.get("mcpName"):
+                return ValidationResult(False, "--mcp-name is required when --tools includes remote_mcp")
+            if not o.get("mcpUrl"):
+                return ValidationResult(False, "--mcp-url is required when --tools includes remote_mcp")
+        if "agentcore_gateway" in tool_names and not o.get("gatewayArn"):
+            return ValidationResult(False, "--gateway-arn is required when --tools includes agentcore_gateway")
+
+    outbound = o.get("gatewayOutboundAuth")
+    if outbound:
+        if outbound not in VALID_GATEWAY_OUTBOUND_AUTH:
+            return ValidationResult(
+                False,
+                f"Invalid --gateway-outbound-auth '{outbound}'. Use: {', '.join(VALID_GATEWAY_OUTBOUND_AUTH)}",
+            )
+        if outbound == "oauth":
+            if not o.get("gatewayProviderArn"):
+                return ValidationResult(
+                    False, "--gateway-provider-arn is required when --gateway-outbound-auth is oauth"
+                )
+            if not o.get("gatewayScopes"):
+                return ValidationResult(False, "--gateway-scopes is required when --gateway-outbound-auth is oauth")
+
+    if (o.get("gatewayGrantType") is not None or o.get("gatewayCustomParameters") is not None) and outbound != "oauth":
+        return ValidationResult(
+            False,
+            "--gateway-grant-type and --gateway-custom-parameters are only valid with --gateway-outbound-auth oauth",
+        )
+
+    no_memory = o.get("memory") is False
+    memory_tuning_given = any(
+        o.get(k) is not None for k in ("memoryActorId", "memoryMessagesCount", "memoryTopK", "memoryRelevanceScore")
+    )
+    managed_only_flags = any(
+        o.get(k) is not None for k in ("memoryStrategies", "memoryEventExpiryDays", "memoryEncryptionKeyArn")
+    )
+    memory_arn, memory_name, memory_mode = o.get("memoryArn"), o.get("memoryName"), o.get("memoryMode")
+    if memory_arn and memory_name:
+        return ValidationResult(False, "--memory-arn and --memory-name are mutually exclusive")
+    if memory_arn and not is_valid_arn(memory_arn):
+        return ValidationResult(False, f"--memory-arn: {ARN_VALIDATION_MESSAGE}")
+    if no_memory and (memory_arn or memory_name or memory_tuning_given or managed_only_flags):
+        return ValidationResult(
+            False,
+            "--no-memory cannot be combined with --memory-arn, --memory-name, memory tuning flags, or managed-memory "
+            "flags (--memory-strategies, --memory-event-expiry-days, --memory-encryption-key-arn)",
+        )
+
+    if memory_mode and memory_mode not in VALID_MEMORY_MODES:
+        return ValidationResult(False, f"Invalid --memory-mode '{memory_mode}'. Use {', '.join(VALID_MEMORY_MODES)}.")
+    if no_memory and memory_mode in ("managed", "existing"):
+        return ValidationResult(False, "--no-memory cannot be combined with --memory-mode managed/existing")
+    if memory_mode == "existing" and not memory_arn and not memory_name:
+        return ValidationResult(False, "--memory-mode existing requires --memory-arn or --memory-name")
+    if (memory_arn or memory_name) and memory_mode in ("managed", "disabled"):
+        return ValidationResult(
+            False,
+            "--memory-arn/--memory-name reference an existing memory and cannot be combined with --memory-mode "
+            f"{memory_mode}",
+        )
+    if memory_tuning_given and not memory_arn and not memory_name and memory_mode != "existing":
+        return ValidationResult(
+            False,
+            "memory tuning flags (--memory-actor-id, --memory-messages-count, --memory-top-k, "
+            "--memory-relevance-score) require an existing memory (--memory-arn, --memory-name, or --memory-mode "
+            "existing)",
+        )
+    if managed_only_flags and memory_mode and memory_mode != "managed":
+        return ValidationResult(
+            False,
+            "--memory-strategies, --memory-event-expiry-days, and --memory-encryption-key-arn are only valid with "
+            "--memory-mode managed",
+        )
+    if o.get("memoryStrategies"):
+        bad = [
+            s for s in (x.strip() for x in o["memoryStrategies"].split(",")) if s and s not in VALID_MANAGED_STRATEGIES
+        ]
+        if bad:
+            return ValidationResult(
+                False,
+                f"Invalid managed memory strateg{'ies' if len(bad) > 1 else 'y'}: {', '.join(bad)}. "
+                f"Valid: {', '.join(VALID_MANAGED_STRATEGIES)}",
+            )
+
+    authorizer_type = o.get("authorizerType")
+    if authorizer_type:
+        if authorizer_type not in RUNTIME_AUTHORIZER_TYPES:
+            return ValidationResult(False, "Invalid authorizer type. Use AWS_IAM or CUSTOM_JWT")
+        if authorizer_type == "CUSTOM_JWT":
+            jwt = validate_jwt_authorizer_options(o)
+            if not jwt.valid:
+                return jwt
+
+    if o.get("clientId") and authorizer_type != "CUSTOM_JWT":
+        return ValidationResult(False, "OAuth client credentials are only valid with CUSTOM_JWT authorizer")
+
+    private_endpoint_keys = (
+        "privateEndpointLatticeArn",
+        "privateEndpointVpcId",
+        "privateEndpointSubnets",
+        "privateEndpointIpType",
+        "privateEndpointSecurityGroups",
+        "privateEndpointRoutingDomain",
+        "privateEndpointTags",
+        "privateEndpointOverrides",
+    )
+    if any(o.get(k) for k in private_endpoint_keys) and authorizer_type != "CUSTOM_JWT":
+        return ValidationResult(False, "--private-endpoint-* flags are only valid with CUSTOM_JWT authorizer")
+
+    return ValidationResult(True)
+
+
+__all__ = ["VALID_HARNESS_TOOLS", "VALID_MANAGED_STRATEGIES", "validate_add_harness_options"]