agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/_harness_cli.py

@@ -0,0 +1,557 @@
+"""`agentcore add harness` command (the registerCommands half of src/cli/primitives/HarnessPrimitive.ts)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any, NoReturn
+
+import typer
+
+from agentcore.cli.errors import get_error_message
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.operations.deploy.managed_memory_notice import MANAGED_MEMORY_ADD_NOTICE
+from agentcore.primitives._harness_validation import validate_add_harness_options
+from agentcore.primitives.auth_utils import JwtConfigOptions
+from agentcore.primitives.base import ADDITIONAL_PARAMS_JSON_ERROR, emit_json
+
+if TYPE_CHECKING:
+    from agentcore.primitives.harness import HarnessPrimitive
+
+
+def _commander_invalid(flag: str, raw: str, reason: str) -> NoReturn:
+    """Commander's InvalidArgumentError output for a custom argParser (exit 1)."""
+    sys.stderr.write(f"error: option '{flag}' argument '{raw}' is invalid. {reason}\n")
+    raise typer.Exit(1)
+
+
+def _js_number(raw: str) -> float | None:
+    """``Number(raw)``; None for NaN."""
+    text = raw.strip()
+    if text == "":
+        return 0.0
+    try:
+        if text.lower().startswith(("0x", "0o", "0b")):
+            return float(int(text, 0))
+        if text.lower() in ("infinity", "+infinity"):
+            return float("inf")
+        if text.lower() == "-infinity":
+            return float("-inf")
+        if any(c in text.lower() for c in ("n", "_")):  # reject "nan", "inf", digit separators
+            return None
+        return float(text)
+    except ValueError:
+        return None
+
+
+def strict_int(raw: str | None, flag: str, label: str) -> int | None:
+    """Port of ``strictInt``: only the canonical decimal integer the user typed (``String(n) === trimmed``)."""
+    if raw is None:
+        return None
+    trimmed = raw.strip()
+    n = _js_number(trimmed)
+    canonical = n is not None and n == n and abs(n) != float("inf") and float(n).is_integer()
+    if not canonical or str(int(n)) != trimmed:  # type: ignore[arg-type]
+        _commander_invalid(flag, raw, f'{label} must be an integer, got "{raw}"')
+    return int(n)  # type: ignore[arg-type]
+
+
+def strict_float(raw: str | None, flag: str, label: str) -> float | None:
+    """Port of ``strictFloat``: finite numbers only."""
+    if raw is None:
+        return None
+    n = _js_number(raw)
+    if n is None or n != n or abs(n) == float("inf") or raw.strip() == "":
+        _commander_invalid(flag, raw, f'{label} must be a number, got "{raw}"')
+    return int(n) if float(n).is_integer() else n  # type: ignore[arg-type]
+
+
+def collect_key_value(values: list[str] | None) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for value in values or []:
+        eq = value.find("=")
+        if eq <= 0:
+            sys.stderr.write(f'Error: Invalid KEY=VALUE pair: "{value}" (expected KEY=VALUE with a non-empty key)\n')
+            raise typer.Exit(1)
+        result[value[:eq]] = value[eq + 1 :]
+    return result
+
+
+def _csv(value: str | None, drop_empty: bool = False) -> list[str] | None:
+    if value is None:
+        return None
+    parts = [s.strip() for s in value.split(",")]
+    return [p for p in parts if p] if drop_empty else parts
+
+
+def _fail(message: str, as_json: bool) -> NoReturn:
+    if as_json:
+        emit_json({"success": False, "error": message})
+    else:
+        typer.echo(message, err=True)
+    raise typer.Exit(1)
+
+
+def parse_json_record_flag(value: str | None, flag: str, as_json: bool) -> dict[str, str] | None:
+    if value is None:
+        return None
+    try:
+        parsed = json.loads(value)
+    except ValueError:
+        _fail(f"Invalid {flag}: not valid JSON", as_json)
+    if not isinstance(parsed, dict):
+        _fail(f"Invalid {flag}: expected a JSON object of string values", as_json)
+    for k, v in parsed.items():
+        if not isinstance(v, str):
+            _fail(f'Invalid {flag}: value for "{k}" must be a string', as_json)
+    return dict(parsed)
+
+
+def build_private_endpoint_from_flags(o: dict[str, Any]) -> dict[str, Any] | None:
+    if o.get("privateEndpointLatticeArn"):
+        return {"selfManagedLatticeResource": {"resourceConfigurationIdentifier": o["privateEndpointLatticeArn"]}}
+    if o.get("privateEndpointVpcId"):
+        resource: dict[str, Any] = {
+            "vpcIdentifier": o["privateEndpointVpcId"],
+            "subnetIds": _csv(o.get("privateEndpointSubnets")) or [],
+            "endpointIpAddressType": o.get("privateEndpointIpType"),
+        }
+        if o.get("privateEndpointSecurityGroups"):
+            resource["securityGroupIds"] = _csv(o["privateEndpointSecurityGroups"])
+        if o.get("privateEndpointRoutingDomain"):
+            resource["routingDomain"] = o["privateEndpointRoutingDomain"]
+        if o.get("privateEndpointTags"):
+            resource["tags"] = json.loads(o["privateEndpointTags"])
+        return {"managedVpcResource": resource}
+    return None
+
+
+def register_add_harness(primitive: HarnessPrimitive, add_app: typer.Typer) -> None:
+    @add_app.command("harness", help="Add a harness to the project")
+    def add_harness(
+        name: str | None = typer.Option(
+            None, "--name", help="Harness name (start with letter, alphanumeric + underscores, max 48 chars)"
+        ),
+        model_provider: str | None = typer.Option(
+            None, "--model-provider", help="Model provider: bedrock, open_ai, gemini, lite_llm"
+        ),
+        model_id: str | None = typer.Option(
+            None, "--model-id", help="Model ID (e.g., anthropic.claude-3-5-sonnet-20240620-v1:0)"
+        ),
+        api_format: str | None = typer.Option(
+            None,
+            "--api-format",
+            help="API format: converse_stream, responses, chat_completions (bedrock); responses, chat_completions "
+            "(open_ai)",
+        ),
+        api_key_arn: str | None = typer.Option(
+            None, "--api-key-arn", help="API key ARN for non-Bedrock providers (optional for lite_llm)"
+        ),
+        api_base: str | None = typer.Option(
+            None, "--api-base", help="Base URL for the model provider API endpoint (lite_llm only)"
+        ),
+        additional_params: str | None = typer.Option(
+            None,
+            "--additional-params",
+            help="Provider-specific params passed through unchanged, as a JSON object (lite_llm only)",
+        ),
+        temperature: str | None = typer.Option(None, "--temperature", help="Model sampling temperature (0-2)"),
+        top_p: str | None = typer.Option(None, "--top-p", help="Model nucleus-sampling top-p (0-1)"),
+        top_k: str | None = typer.Option(None, "--top-k", help="Model top-k sampling (gemini only)"),
+        model_max_tokens: str | None = typer.Option(
+            None, "--model-max-tokens", help="Model-config max output tokens per turn (distinct from --max-tokens)"
+        ),
+        container: str | None = typer.Option(None, "--container", help="Container image URI or path to a Dockerfile"),
+        memory: bool = typer.Option(
+            True, " /--no-memory", help="Disable memory for this harness (this is the default)", show_default=False
+        ),
+        memory_name: str | None = typer.Option(None, "--memory-name", help="Use an existing memory by name"),
+        memory_arn: str | None = typer.Option(None, "--memory-arn", help="Use an existing memory by ARN"),
+        memory_actor_id: str | None = typer.Option(
+            None, "--memory-actor-id", help="Deploy-time ActorId scoping memory access for the harness"
+        ),
+        memory_messages_count: str | None = typer.Option(
+            None, "--memory-messages-count", help="Number of recent memory messages to load into context"
+        ),
+        memory_top_k: str | None = typer.Option(
+            None, "--memory-top-k", help="Memory retrieval: items to retrieve per namespace"
+        ),
+        memory_relevance_score: str | None = typer.Option(
+            None, "--memory-relevance-score", help="Memory retrieval: minimum relevance score (0-1)"
+        ),
+        memory_mode: str | None = typer.Option(
+            None, "--memory-mode", help="Memory mode: disabled (default), managed, or existing"
+        ),
+        memory_strategies: str | None = typer.Option(
+            None,
+            "--memory-strategies",
+            help="Managed memory strategies (comma-separated): SEMANTIC,SUMMARIZATION,USER_PREFERENCE,EPISODIC",
+        ),
+        memory_event_expiry_days: str | None = typer.Option(
+            None, "--memory-event-expiry-days", help="Managed memory event retention in days (3-365)"
+        ),
+        memory_encryption_key_arn: str | None = typer.Option(
+            None, "--memory-encryption-key-arn", help="Managed memory KMS CMK ARN (create-only)"
+        ),
+        max_iterations: str | None = typer.Option(None, "--max-iterations", help="Max iterations"),
+        max_tokens: str | None = typer.Option(
+            None, "--max-tokens", help="Max execution tokens per invocation (harness loop cap)"
+        ),
+        timeout: str | None = typer.Option(None, "--timeout", help="Timeout in seconds"),
+        truncation_strategy: str | None = typer.Option(
+            None, "--truncation-strategy", help="Truncation strategy: sliding_window, summarization, or none"
+        ),
+        network_mode: str | None = typer.Option(None, "--network-mode", help="Network mode: PUBLIC or VPC"),
+        subnets: str | None = typer.Option(None, "--subnets", help="Comma-separated subnet IDs (for VPC mode)"),
+        security_groups: str | None = typer.Option(
+            None, "--security-groups", help="Comma-separated security group IDs (for VPC mode)"
+        ),
+        vpc_id: str | None = typer.Option(
+            None, "--vpc-id", help="VPC ID for dockerfile (container) builds in VPC mode"
+        ),
+        idle_timeout: str | None = typer.Option(None, "--idle-timeout", help="Idle timeout in seconds"),
+        max_lifetime: str | None = typer.Option(None, "--max-lifetime", help="Max lifetime in seconds"),
+        session_storage: str | None = typer.Option(
+            None, "--session-storage", help="Mount path for persistent session storage (e.g., /mnt/data/)"
+        ),
+        efs_access_point: list[str] | None = typer.Option(
+            None,
+            "--efs-access-point",
+            help="EFS access point mount as <accessPointArn>:<mountPath> (repeatable, VPC mode; max 2)",
+        ),
+        s3_access_point: list[str] | None = typer.Option(
+            None,
+            "--s3-access-point",
+            help="S3 Files access point mount as <accessPointArn>:<mountPath> (repeatable, VPC mode; max 2)",
+        ),
+        allowed_tools: str | None = typer.Option(
+            None,
+            "--allowed-tools",
+            help='Comma-separated allow-list of tools the agent may use (e.g. "*" or names)',
+        ),
+        env: list[str] | None = typer.Option(
+            None, "--env", help="Harness environment variable as KEY=VALUE (repeatable)"
+        ),
+        tag: list[str] | None = typer.Option(None, "--tag", help="Harness-level tag as KEY=VALUE (repeatable)"),
+        with_invoke_script: bool = typer.Option(
+            False, "--with-invoke-script", help="Generate a standalone Python invoke script"
+        ),
+        system_prompt: str | None = typer.Option(
+            None,
+            "--system-prompt",
+            help='System prompt text (written to system-prompt.md; defaults to "You are a helpful assistant")',
+        ),
+        tools: str | None = typer.Option(
+            None,
+            "--tools",
+            help="Comma-separated tools: agentcore_browser, agentcore_code_interpreter, remote_mcp, agentcore_gateway",
+        ),
+        mcp_name: str | None = typer.Option(
+            None, "--mcp-name", help="Remote MCP tool name (required when --tools includes remote_mcp)"
+        ),
+        mcp_url: str | None = typer.Option(
+            None, "--mcp-url", help="Remote MCP endpoint URL (required when --tools includes remote_mcp)"
+        ),
+        mcp_headers: str | None = typer.Option(
+            None, "--mcp-headers", help="Remote MCP request headers as a JSON object (with --tools remote_mcp)"
+        ),
+        gateway_arn: str | None = typer.Option(
+            None, "--gateway-arn", help="Gateway ARN (required when --tools includes agentcore_gateway)"
+        ),
+        gateway_outbound_auth: str | None = typer.Option(
+            None,
+            "--gateway-outbound-auth",
+            help="Gateway outbound auth: awsIam, none, oauth (requires --gateway-provider-arn and --gateway-scopes)",
+        ),
+        gateway_provider_arn: str | None = typer.Option(
+            None, "--gateway-provider-arn", help="OAuth provider ARN for gateway outbound auth"
+        ),
+        gateway_scopes: str | None = typer.Option(
+            None, "--gateway-scopes", help="Comma-separated OAuth scopes for gateway outbound auth"
+        ),
+        gateway_grant_type: str | None = typer.Option(
+            None, "--gateway-grant-type", help="Gateway OAuth grant type: CLIENT_CREDENTIALS or USER_FEDERATION"
+        ),
+        gateway_custom_parameters: str | None = typer.Option(
+            None, "--gateway-custom-parameters", help="Gateway OAuth custom parameters as a JSON object"
+        ),
+        authorizer_type: str | None = typer.Option(
+            None, "--authorizer-type", help="Authorizer type: AWS_IAM or CUSTOM_JWT"
+        ),
+        discovery_url: str | None = typer.Option(None, "--discovery-url", help="OIDC discovery URL (for CUSTOM_JWT)"),
+        allowed_audience: str | None = typer.Option(
+            None, "--allowed-audience", help="Comma-separated allowed audiences (for CUSTOM_JWT)"
+        ),
+        allowed_clients: str | None = typer.Option(
+            None, "--allowed-clients", help="Comma-separated allowed client IDs (for CUSTOM_JWT)"
+        ),
+        allowed_scopes: str | None = typer.Option(
+            None, "--allowed-scopes", help="Comma-separated allowed scopes (for CUSTOM_JWT)"
+        ),
+        custom_claims: str | None = typer.Option(
+            None, "--custom-claims", help="Custom claims JSON array (for CUSTOM_JWT)"
+        ),
+        client_id: str | None = typer.Option(None, "--client-id", help="OAuth client ID (for CUSTOM_JWT)"),
+        client_secret: str | None = typer.Option(None, "--client-secret", help="OAuth client secret (for CUSTOM_JWT)"),
+        private_endpoint_lattice_arn: str | None = typer.Option(
+            None,
+            "--private-endpoint-lattice-arn",
+            help="PrivateLink: VPC Lattice resource-config id/ARN to reach the OIDC discovery endpoint (for "
+            "CUSTOM_JWT)",
+        ),
+        private_endpoint_vpc_id: str | None = typer.Option(
+            None,
+            "--private-endpoint-vpc-id",
+            help="PrivateLink: VPC id for a service-managed endpoint to the OIDC discovery endpoint (for CUSTOM_JWT)",
+        ),
+        private_endpoint_subnets: str | None = typer.Option(
+            None,
+            "--private-endpoint-subnets",
+            help="PrivateLink: comma-separated subnet IDs (with --private-endpoint-vpc-id)",
+        ),
+        private_endpoint_ip_type: str | None = typer.Option(
+            None,
+            "--private-endpoint-ip-type",
+            help="PrivateLink: endpoint IP address type: IPV4 or IPV6 (with --private-endpoint-vpc-id)",
+        ),
+        private_endpoint_security_groups: str | None = typer.Option(
+            None,
+            "--private-endpoint-security-groups",
+            help="PrivateLink: comma-separated security group IDs, max 5 (with --private-endpoint-vpc-id)",
+        ),
+        private_endpoint_routing_domain: str | None = typer.Option(
+            None,
+            "--private-endpoint-routing-domain",
+            help="PrivateLink: routing domain (with --private-endpoint-vpc-id)",
+        ),
+        private_endpoint_tags: str | None = typer.Option(
+            None, "--private-endpoint-tags", help="PrivateLink: tags JSON object (with --private-endpoint-vpc-id)"
+        ),
+        private_endpoint_overrides: str | None = typer.Option(
+            None,
+            "--private-endpoint-overrides",
+            help="PrivateLink: JSON array (max 5) of {domain, privateEndpoint} per-domain overrides (for CUSTOM_JWT)",
+        ),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        # Commander runs argParsers (strictInt/strictFloat/collectKeyValue) before the action.
+        n_temperature = strict_float(temperature, "--temperature <n>", "--temperature")
+        n_top_p = strict_float(top_p, "--top-p <n>", "--top-p")
+        n_top_k = strict_int(top_k, "--top-k <n>", "--top-k")
+        n_model_max_tokens = strict_int(model_max_tokens, "--model-max-tokens <n>", "--model-max-tokens")
+        n_messages = strict_int(memory_messages_count, "--memory-messages-count <n>", "--memory-messages-count")
+        n_memory_top_k = strict_int(memory_top_k, "--memory-top-k <n>", "--memory-top-k")
+        n_relevance = strict_float(memory_relevance_score, "--memory-relevance-score <n>", "--memory-relevance-score")
+        n_expiry = strict_int(memory_event_expiry_days, "--memory-event-expiry-days <n>", "--memory-event-expiry-days")
+        n_max_iterations = strict_int(max_iterations, "--max-iterations <n>", "--max-iterations")
+        n_max_tokens = strict_int(max_tokens, "--max-tokens <n>", "--max-tokens")
+        n_timeout = strict_int(timeout, "--timeout <seconds>", "--timeout")
+        n_idle = strict_int(idle_timeout, "--idle-timeout <seconds>", "--idle-timeout")
+        n_lifetime = strict_int(max_lifetime, "--max-lifetime <seconds>", "--max-lifetime")
+        env_vars = collect_key_value(env)
+        tag_map = collect_key_value(tag)
+
+        cli: dict[str, Any] = {
+            "name": name,
+            "modelProvider": model_provider,
+            "modelId": model_id,
+            "apiFormat": api_format,
+            "apiKeyArn": api_key_arn,
+            "apiBase": api_base,
+            "additionalParams": additional_params,
+            "temperature": n_temperature,
+            "topP": n_top_p,
+            "topK": n_top_k,
+            "modelMaxTokens": n_model_max_tokens,
+            "container": container,
+            "memory": memory,
+            "memoryMode": memory_mode,
+            "memoryStrategies": memory_strategies,
+            "memoryEventExpiryDays": n_expiry,
+            "memoryEncryptionKeyArn": memory_encryption_key_arn,
+            "memoryName": memory_name,
+            "memoryArn": memory_arn,
+            "memoryActorId": memory_actor_id,
+            "memoryMessagesCount": n_messages,
+            "memoryTopK": n_memory_top_k,
+            "memoryRelevanceScore": n_relevance,
+            "maxIterations": n_max_iterations,
+            "maxTokens": n_max_tokens,
+            "timeout": n_timeout,
+            "truncationStrategy": truncation_strategy,
+            "networkMode": network_mode,
+            "subnets": subnets,
+            "securityGroups": security_groups,
+            "vpcId": vpc_id,
+            "idleTimeout": n_idle,
+            "maxLifetime": n_lifetime,
+            "sessionStorage": session_storage,
+            "allowedTools": allowed_tools,
+            "systemPrompt": system_prompt,
+            "tools": tools,
+            "mcpName": mcp_name,
+            "mcpUrl": mcp_url,
+            "mcpHeaders": mcp_headers,
+            "gatewayArn": gateway_arn,
+            "gatewayOutboundAuth": gateway_outbound_auth,
+            "gatewayProviderArn": gateway_provider_arn,
+            "gatewayScopes": gateway_scopes,
+            "gatewayGrantType": gateway_grant_type,
+            "gatewayCustomParameters": gateway_custom_parameters,
+            "authorizerType": authorizer_type,
+            "discoveryUrl": discovery_url,
+            "allowedAudience": allowed_audience,
+            "allowedClients": allowed_clients,
+            "allowedScopes": allowed_scopes,
+            "customClaims": custom_claims,
+            "clientId": client_id,
+            "clientSecret": client_secret,
+            "privateEndpointLatticeArn": private_endpoint_lattice_arn,
+            "privateEndpointVpcId": private_endpoint_vpc_id,
+            "privateEndpointSubnets": private_endpoint_subnets,
+            "privateEndpointIpType": private_endpoint_ip_type,
+            "privateEndpointSecurityGroups": private_endpoint_security_groups,
+            "privateEndpointRoutingDomain": private_endpoint_routing_domain,
+            "privateEndpointTags": private_endpoint_tags,
+            "privateEndpointOverrides": private_endpoint_overrides,
+        }
+        try:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+
+            validation = validate_add_harness_options(cli)
+            if not validation.valid:
+                _fail(validation.error or "", as_json)
+
+            if not (name or as_json):
+                from agentcore.cli import interactive
+
+                interactive.require_tty()
+                primitive.add_interactive()
+                raise typer.Exit(0)
+
+            if not name:
+                _fail("--name is required", as_json)
+
+            from agentcore.primitives.harness import (
+                DEFAULT_BEDROCK_MANTLE_MODEL_ID,
+                DEFAULT_MODEL_IDS,
+                AddHarnessOptions,
+                emit_harness_add_failure,
+                parse_access_points,
+                parse_container_flag,
+            )
+
+            provider = model_provider or "bedrock"
+            is_mantle = provider == "bedrock" and api_format in ("responses", "chat_completions")
+            resolved_model_id = model_id or (
+                DEFAULT_BEDROCK_MANTLE_MODEL_ID if is_mantle else DEFAULT_MODEL_IDS.get(provider)
+            )
+            container_option = parse_container_flag(container)
+
+            parsed_params = None
+            if additional_params:
+                try:
+                    parsed_params = json.loads(additional_params)
+                except ValueError:
+                    _fail(ADDITIONAL_PARAMS_JSON_ERROR, as_json)
+
+            headers = parse_json_record_flag(mcp_headers, "--mcp-headers", as_json)
+            custom_params = parse_json_record_flag(gateway_custom_parameters, "--gateway-custom-parameters", as_json)
+
+            jwt_config = None
+            if authorizer_type == "CUSTOM_JWT" and discovery_url:
+                jwt_config = JwtConfigOptions(
+                    discovery_url=discovery_url,
+                    allowed_audience=_csv(allowed_audience),
+                    allowed_clients=_csv(allowed_clients),
+                    allowed_scopes=_csv(allowed_scopes),
+                    custom_claims=json.loads(custom_claims) if custom_claims else None,
+                    client_id=client_id,
+                    client_secret=client_secret,
+                    private_endpoint=build_private_endpoint_from_flags(cli),
+                    private_endpoint_overrides=json.loads(private_endpoint_overrides)
+                    if private_endpoint_overrides
+                    else None,
+                )
+
+            result = primitive.add(
+                AddHarnessOptions(
+                    name=name,
+                    model_provider=provider,
+                    model_id=resolved_model_id,  # type: ignore[arg-type]
+                    api_format=api_format,
+                    api_key_arn=api_key_arn,
+                    api_base=api_base,
+                    additional_params=parsed_params,
+                    temperature=n_temperature,
+                    top_p=n_top_p,
+                    top_k=n_top_k,
+                    model_max_tokens=n_model_max_tokens,
+                    container_uri=container_option.get("containerUri"),
+                    dockerfile_path=container_option.get("dockerfilePath"),
+                    skip_memory=memory is False,
+                    memory_mode=memory_mode,
+                    memory_strategies=_csv(memory_strategies, drop_empty=True),
+                    memory_event_expiry_days=n_expiry,
+                    memory_encryption_key_arn=memory_encryption_key_arn,
+                    memory_name=memory_name,
+                    memory_arn=memory_arn,
+                    memory_actor_id=memory_actor_id,
+                    messages_count=n_messages,
+                    memory_top_k=n_memory_top_k,
+                    memory_relevance_score=n_relevance,
+                    max_iterations=n_max_iterations,
+                    max_tokens=n_max_tokens,
+                    timeout_seconds=n_timeout,
+                    truncation_strategy=truncation_strategy,
+                    network_mode=network_mode,
+                    subnets=_csv(subnets),
+                    security_groups=_csv(security_groups),
+                    vpc_id=vpc_id,
+                    idle_timeout=n_idle,
+                    max_lifetime=n_lifetime,
+                    session_storage_path=session_storage,
+                    efs_access_points=parse_access_points(efs_access_point),
+                    s3_access_points=parse_access_points(s3_access_point),
+                    allowed_tools=_csv(allowed_tools, drop_empty=True),
+                    environment_variables=env_vars or None,
+                    tags=tag_map or None,
+                    with_invoke_script=with_invoke_script or None,
+                    system_prompt=system_prompt,
+                    selected_tools=_csv(tools),
+                    mcp_name=mcp_name,
+                    mcp_url=mcp_url,
+                    mcp_headers=headers,
+                    gateway_arn=gateway_arn,
+                    gateway_outbound_auth=gateway_outbound_auth,
+                    gateway_provider_arn=gateway_provider_arn,
+                    gateway_scopes=_csv(gateway_scopes),
+                    gateway_grant_type=gateway_grant_type,
+                    gateway_custom_parameters=custom_params,
+                    authorizer_type=authorizer_type,
+                    jwt_config=jwt_config,
+                )
+            )
+            if not result.success:
+                emit_harness_add_failure(result, as_json)
+                raise typer.Exit(1)
+            if as_json:
+                emit_json({"success": True, **result.value})
+            else:
+                typer.echo(f"Added harness '{result.value['harnessName']}'.")
+                if result.value.get("memoryMode") == "managed":
+                    typer.echo(f"\n{MANAGED_MEMORY_ADD_NOTICE}")
+            raise typer.Exit(0)
+        except typer.Exit:
+            raise
+        except Exception as exc:  # noqa: BLE001 - command boundary, as upstream
+            if as_json:
+                emit_json({"success": False, "error": get_error_message(exc)})
+            else:
+                typer.echo(get_error_message(exc), err=True)
+            raise typer.Exit(1) from None
+
+
+__all__ = ["collect_key_value", "register_add_harness", "strict_float", "strict_int"]