agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/harness.py

@@ -0,0 +1,706 @@
+"""Harness add/remove (port of src/cli/primitives/HarnessPrimitive.ts).
+
+A harness lives in ``app/<name>/harness.json`` (+ ``system-prompt.md``) and is listed in
+``agentcore.json`` ``harnesses``. Specs are handled in their camelCase JSON form and validated on
+write by ``ConfigIO``. ``register_commands`` also registers the harness ``add/remove tool`` and
+``add/remove skill`` subcommands.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+from dataclasses import dataclass, field, fields
+from typing import Any, Literal
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.errors import get_error_message
+from agentcore.lib import APP_DIR
+from agentcore.lib.errors.types import BaseError, ResourceNotFoundError, ValidationError, to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.operations.harness.orphan import OrphanHarness, find_orphan_harnesses
+from agentcore.operations.harness.skill_utils import validate_git_skill_credential
+from agentcore.primitives.auth_utils import (
+    JwtConfigOptions,
+    build_authorizer_config_from_jwt_config,
+    create_managed_oauth_credential,
+)
+from agentcore.primitives.base import (
+    SOURCE_CODE_NOTE,
+    BasePrimitive,
+    RemovableResource,
+    RemovalPreview,
+    SchemaChange,
+    emit_json,
+)
+
+OrphanAction = Literal["keep", "discard"]
+
+# Port of tui/screens/harness/types.ts defaults.
+DEFAULT_MODEL_IDS: dict[str, str] = {
+    "bedrock": "global.anthropic.claude-sonnet-4-6",
+    "open_ai": "gpt-5",
+    "gemini": "gemini-2.5-flash",
+    "lite_llm": "anthropic/claude-sonnet-4-5",
+}
+DEFAULT_BEDROCK_MANTLE_MODEL_ID = "openai.gpt-oss-120b"
+DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant"
+
+
+@dataclass
+class AddHarnessOptions:
+    """Port of ``AddHarnessOptions`` (snake_case attributes of the upstream camelCase keys)."""
+
+    name: str
+    model_provider: str = "bedrock"
+    model_id: str = DEFAULT_MODEL_IDS["bedrock"]
+    api_format: str | None = None
+    api_key_arn: str | None = None
+    api_base: str | None = None
+    additional_params: dict[str, Any] | None = None
+    temperature: float | None = None
+    top_p: float | None = None
+    top_k: int | None = None
+    model_max_tokens: int | None = None
+    system_prompt: str | None = None
+    skip_memory: bool | None = None
+    memory_mode: str | None = None
+    memory_strategies: list[str] | None = None
+    memory_event_expiry_days: int | None = None
+    memory_encryption_key_arn: str | None = None
+    memory_name: str | None = None
+    memory_arn: str | None = None
+    memory_actor_id: str | None = None
+    messages_count: int | None = None
+    memory_top_k: int | None = None
+    memory_relevance_score: float | None = None
+    container_uri: str | None = None
+    dockerfile_path: str | None = None
+    max_iterations: int | None = None
+    max_tokens: int | None = None
+    timeout_seconds: float | None = None
+    truncation_strategy: str | None = None
+    network_mode: str | None = None
+    subnets: list[str] | None = None
+    security_groups: list[str] | None = None
+    vpc_id: str | None = None
+    idle_timeout: int | None = None
+    max_lifetime: int | None = None
+    session_storage_path: str | None = None
+    efs_access_points: list[dict[str, str]] | None = None
+    s3_access_points: list[dict[str, str]] | None = None
+    allowed_tools: list[str] | None = None
+    environment_variables: dict[str, str] | None = None
+    tags: dict[str, str] | None = None
+    with_invoke_script: bool | None = None
+    dockerfile_base_dir: str | None = None
+    selected_tools: list[str] | None = None
+    mcp_name: str | None = None
+    mcp_url: str | None = None
+    mcp_headers: dict[str, str] | None = None
+    gateway_arn: str | None = None
+    gateway_outbound_auth: str | None = None
+    gateway_provider_arn: str | None = None
+    gateway_scopes: list[str] | None = None
+    gateway_grant_type: str | None = None
+    gateway_custom_parameters: dict[str, str] | None = None
+    authorizer_type: str | None = None
+    jwt_config: JwtConfigOptions | None = None
+    skills: list[dict[str, Any]] | None = field(default=None)
+    config_base_dir: str | None = None
+
+
+_CAMEL = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def _snake(key: str) -> str:
+    return _CAMEL.sub("_", key).lower()
+
+
+def _jwt_from_dict(value: Any) -> JwtConfigOptions | None:
+    if value is None or isinstance(value, JwtConfigOptions):
+        return value
+    names = {f.name for f in fields(JwtConfigOptions)}
+    return JwtConfigOptions(**{_snake(k): v for k, v in value.items() if _snake(k) in names})
+
+
+def add_options_from_dict(d: dict[str, Any]) -> AddHarnessOptions:
+    """Build options from upstream's camelCase ``AddHarnessOptions`` dict (``None`` = undefined)."""
+    names = {f.name for f in fields(AddHarnessOptions)}
+    kwargs: dict[str, Any] = {}
+    for key, value in d.items():
+        attr = _snake(key)
+        if attr in names and value is not None:
+            kwargs[attr] = value
+    if "jwt_config" in kwargs:
+        kwargs["jwt_config"] = _jwt_from_dict(kwargs["jwt_config"])
+    if "model_id" not in kwargs:
+        kwargs["model_id"] = DEFAULT_MODEL_IDS.get(
+            kwargs.get("model_provider", "bedrock"), DEFAULT_MODEL_IDS["bedrock"]
+        )
+    return AddHarnessOptions(**kwargs)
+
+
+def _num(value: Any) -> Any:
+    """JS numbers print integral floats without a fraction (300.0 -> 300)."""
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return value
+
+
+def parse_container_flag(value: str | None) -> dict[str, str]:
+    """Dockerfile path (relative prefix or Dockerfile suffix) vs. container image URI."""
+    if not value:
+        return {}
+    if value.endswith(("Dockerfile", ".dockerfile")) or value.startswith(("./", "../")):
+        return {"dockerfilePath": value}
+    return {"containerUri": value}
+
+
+def parse_access_points(raw: list[str] | None) -> list[dict[str, str]] | None:
+    """``<accessPointArn>:<mountPath>`` entries, split on the LAST colon (the ARN contains colons)."""
+    if not raw:
+        return None
+    result = []
+    for entry in raw:
+        sep = entry.rfind(":")
+        if sep <= 0 or sep == len(entry) - 1:
+            raise Exception(f'Invalid access point "{entry}" (expected <accessPointArn>:<mountPath>)')
+        result.append({"accessPointArn": entry[:sep], "mountPath": entry[sep + 1 :]})
+    return result
+
+
+def js_error_object(err: BaseException) -> dict[str, Any]:
+    """``JSON.parse(JSON.stringify(err))``: typed errors carry own ``name``/``errorSource``; plain Errors are ``{}``."""
+    if isinstance(err, BaseError):
+        return {"name": err.name, "errorSource": err.error_source}
+    return {}
+
+
+class HarnessPrimitive(BasePrimitive):
+    kind = "harness"
+    label = "Harness"
+
+    add_options_from_dict = staticmethod(add_options_from_dict)
+    parse_container_flag = staticmethod(parse_container_flag)
+
+    # --- add ----------------------------------------------------------------------------
+
+    def add(self, options: AddHarnessOptions | dict[str, Any]) -> Ok[dict[str, Any]] | Err[Exception]:
+        if isinstance(options, dict):
+            options = add_options_from_dict(options)
+        try:
+            config_base_dir = options.config_base_dir or find_config_root()
+            if not config_base_dir:
+                return Err(ResourceNotFoundError("No agentcore project found. Run `agentcore create` first."))
+            config_io = ConfigIO(base_dir=config_base_dir)
+            project = to_jsonable(self.read_project_spec(config_io))
+            harnesses = list(project.get("harnesses") or [])
+            if any(h["name"] == options.name for h in harnesses):
+                raise ValueError(f'{self.label} "{options.name}" already exists.')
+
+            memory_ref = self._build_memory_ref(options)
+
+            dockerfile: str | None = None
+            if options.dockerfile_path:
+                project_root = os.path.dirname(config_base_dir)
+                base = options.dockerfile_base_dir or project_root
+                src = (
+                    options.dockerfile_path
+                    if os.path.isabs(options.dockerfile_path)
+                    else os.path.abspath(os.path.join(base, options.dockerfile_path))
+                )
+                if not os.path.exists(src):
+                    return Err(ResourceNotFoundError(f"Dockerfile not found at: {src}"))
+                app_dir = os.path.join(project_root, APP_DIR, options.name)
+                os.makedirs(app_dir, exist_ok=True)
+                dockerfile = os.path.basename(src)
+                shutil.copyfile(src, os.path.join(app_dir, dockerfile))
+
+            tools = self._build_tools(options)
+
+            skills: list[dict[str, Any]] = []
+            for s in options.skills or []:
+                if s.get("s3Uri"):
+                    skills.append({"s3Uri": s["s3Uri"]})
+                elif s.get("gitUrl"):
+                    if s.get("credentialName"):
+                        validation = validate_git_skill_credential(project, s["credentialName"])
+                        if not validation.success:
+                            return validation
+                    entry: dict[str, Any] = {"gitUrl": s["gitUrl"]}
+                    if s.get("gitPath"):
+                        entry["path"] = s["gitPath"]
+                    if s.get("credentialName"):
+                        auth = {"credentialName": s["credentialName"]}
+                        if s.get("username"):
+                            auth["username"] = s["username"]
+                        entry["auth"] = auth
+                    skills.append(entry)
+                elif s.get("awsSkills") is not None:
+                    skills.append({"awsSkills": {"paths": s["awsSkills"]} if s["awsSkills"] else {}})
+                else:
+                    skills.append({"path": s.get("path")})
+
+            model: dict[str, Any] = {"provider": options.model_provider, "modelId": options.model_id}
+            if options.api_format:
+                model["apiFormat"] = options.api_format
+            if options.api_key_arn:
+                model["apiKeyArn"] = options.api_key_arn
+            if options.api_base:
+                model["apiBase"] = options.api_base
+            if options.additional_params:
+                model["additionalParams"] = options.additional_params
+            for key, value in (
+                ("temperature", options.temperature),
+                ("topP", options.top_p),
+                ("topK", options.top_k),
+                ("maxTokens", options.model_max_tokens),
+            ):
+                if value is not None:
+                    model[key] = _num(value)
+
+            spec: dict[str, Any] = {"name": options.name, "model": model, "tools": tools, "skills": skills}
+            if options.system_prompt:
+                spec["systemPrompt"] = options.system_prompt
+            if options.allowed_tools:
+                spec["allowedTools"] = options.allowed_tools
+            if memory_ref:
+                spec["memory"] = memory_ref
+            if options.container_uri:
+                spec["containerUri"] = options.container_uri
+            if dockerfile:
+                spec["dockerfile"] = dockerfile
+            for key, value in (
+                ("maxIterations", options.max_iterations),
+                ("maxTokens", options.max_tokens),
+                ("timeoutSeconds", options.timeout_seconds),
+            ):
+                if value is not None:
+                    spec[key] = _num(value)
+            if options.truncation_strategy:
+                spec["truncation"] = {"strategy": options.truncation_strategy}
+            if options.network_mode:
+                spec["networkMode"] = options.network_mode
+            if options.network_mode == "VPC" and options.subnets and options.security_groups:
+                network: dict[str, Any] = {"subnets": options.subnets, "securityGroups": options.security_groups}
+                if options.vpc_id:
+                    network["vpcId"] = options.vpc_id
+                spec["networkConfig"] = network
+            lifecycle = self._build_lifecycle_config(options)
+            if lifecycle:
+                spec["lifecycleConfig"] = lifecycle
+            if options.session_storage_path:
+                spec["sessionStoragePath"] = options.session_storage_path
+            if options.efs_access_points:
+                spec["efsAccessPoints"] = options.efs_access_points
+            if options.s3_access_points:
+                spec["s3AccessPoints"] = options.s3_access_points
+            if options.environment_variables:
+                spec["environmentVariables"] = options.environment_variables
+            if options.tags:
+                spec["tags"] = options.tags
+            if options.authorizer_type:
+                spec["authorizerType"] = options.authorizer_type
+            if options.authorizer_type == "CUSTOM_JWT" and options.jwt_config:
+                spec["authorizerConfiguration"] = build_authorizer_config_from_jwt_config(options.jwt_config)
+
+            config_io.write_harness_spec(options.name, spec)
+
+            harness_dir = config_io.get_path_resolver().get_harness_dir(options.name)
+            prompt = options.system_prompt if (options.system_prompt or "").strip() else DEFAULT_SYSTEM_PROMPT
+            with open(os.path.join(harness_dir, "system-prompt.md"), "w", encoding="utf-8") as fh:
+                fh.write(prompt)
+
+            if options.with_invoke_script:
+                from agentcore.templates.template_root import get_template_path
+
+                template = get_template_path("harness", "invoke.py.template").read_text(encoding="utf-8")
+                template = template.replace("{{HARNESS_ARN}}", "<your-harness-arn>", 1)
+                template = template.replace("{{REGION}}", "<your-region>", 1)
+                with open(os.path.join(harness_dir, "invoke.py"), "w", encoding="utf-8") as fh:
+                    fh.write(template)
+
+            project["harnesses"] = [*harnesses, {"name": options.name, "path": f"app/{options.name}"}]
+            self.write_project_spec(project, config_io)
+
+            if options.jwt_config and options.jwt_config.client_id and options.jwt_config.client_secret:
+                create_managed_oauth_credential(
+                    options.name,
+                    options.jwt_config,
+                    lambda spec_: self.write_project_spec(spec_, config_io),
+                    lambda: self.read_project_spec(config_io),
+                    config_base_dir,
+                )
+
+            return Ok({"harnessName": options.name, "memoryMode": memory_ref["mode"] if memory_ref else None})
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    @staticmethod
+    def _build_tools(options: AddHarnessOptions) -> list[dict[str, Any]]:
+        tools: list[dict[str, Any]] = []
+        for tool_type in options.selected_tools or []:
+            if tool_type == "agentcore_browser":
+                tools.append({"type": "agentcore_browser", "name": "browser"})
+            elif tool_type == "agentcore_code_interpreter":
+                tools.append({"type": "agentcore_code_interpreter", "name": "code-interpreter"})
+            elif tool_type == "remote_mcp" and options.mcp_name and options.mcp_url:
+                remote: dict[str, Any] = {"url": options.mcp_url}
+                if options.mcp_headers:
+                    remote["headers"] = options.mcp_headers
+                tools.append({"type": "remote_mcp", "name": options.mcp_name, "config": {"remoteMcp": remote}})
+            elif tool_type == "agentcore_gateway" and options.gateway_arn:
+                outbound: dict[str, Any] | None = None
+                if options.gateway_outbound_auth == "awsIam":
+                    outbound = {"awsIam": {}}
+                elif options.gateway_outbound_auth == "none":
+                    outbound = {"none": {}}
+                elif (
+                    options.gateway_outbound_auth == "oauth" and options.gateway_provider_arn and options.gateway_scopes
+                ):
+                    oauth: dict[str, Any] = {
+                        "providerArn": options.gateway_provider_arn,
+                        "scopes": options.gateway_scopes,
+                    }
+                    if options.gateway_grant_type:
+                        oauth["grantType"] = options.gateway_grant_type
+                    if options.gateway_custom_parameters:
+                        oauth["customParameters"] = options.gateway_custom_parameters
+                    outbound = {"oauth": oauth}
+                gateway: dict[str, Any] = {"gatewayArn": options.gateway_arn}
+                if outbound:
+                    gateway["outboundAuth"] = outbound
+                tools.append({"type": "agentcore_gateway", "name": "gateway", "config": {"agentCoreGateway": gateway}})
+        return tools
+
+    @staticmethod
+    def _build_lifecycle_config(options: AddHarnessOptions) -> dict[str, Any] | None:
+        if options.idle_timeout is None and options.max_lifetime is None:
+            return None
+        config: dict[str, Any] = {}
+        if options.idle_timeout is not None:
+            config["idleRuntimeSessionTimeout"] = _num(options.idle_timeout)
+        if options.max_lifetime is not None:
+            config["maxLifetime"] = _num(options.max_lifetime)
+        return config
+
+    @staticmethod
+    def _build_memory_ref(options: AddHarnessOptions) -> dict[str, Any]:
+        """existing (a reference or --memory-mode existing) > managed (explicit) > disabled (default)."""
+        if options.memory_arn or options.memory_name or options.memory_mode == "existing":
+            ref: dict[str, Any] = {"mode": "existing"}
+            if options.memory_name:
+                ref["name"] = options.memory_name
+            if options.memory_arn:
+                ref["arn"] = options.memory_arn
+            if options.memory_actor_id:
+                ref["actorId"] = options.memory_actor_id
+            if options.messages_count is not None:
+                ref["messagesCount"] = _num(options.messages_count)
+            if options.memory_top_k is not None or options.memory_relevance_score is not None:
+                tuning: dict[str, Any] = {}
+                if options.memory_top_k is not None:
+                    tuning["topK"] = _num(options.memory_top_k)
+                if options.memory_relevance_score is not None:
+                    tuning["relevanceScore"] = _num(options.memory_relevance_score)
+                ref["retrievalConfig"] = tuning
+            return ref
+        managed_requested = (
+            options.memory_mode == "managed"
+            or len(options.memory_strategies or []) > 0
+            or options.memory_event_expiry_days is not None
+            or options.memory_encryption_key_arn is not None
+        )
+        if managed_requested:
+            ref = {"mode": "managed"}
+            if options.memory_strategies:
+                ref["strategies"] = options.memory_strategies
+            if options.memory_event_expiry_days is not None:
+                ref["eventExpiryDuration"] = _num(options.memory_event_expiry_days)
+            if options.memory_encryption_key_arn:
+                ref["encryptionKeyArn"] = options.memory_encryption_key_arn
+            return ref
+        return {"mode": "disabled"}
+
+    # --- remove -------------------------------------------------------------------------
+
+    def remove(self, name: str, orphan_action: OrphanAction | None = None) -> Ok[None] | Err[Exception]:
+        try:
+            config_root = find_config_root()
+            if not config_root:
+                return Err(ResourceNotFoundError("No agentcore project found."))
+            config_io = ConfigIO(base_dir=config_root)
+            project = to_jsonable(self.read_project_spec(config_io))
+            deployed_state = self._read_state(config_io)
+
+            orphans = find_orphan_harnesses(deployed_state, name)
+            if orphans:
+                return self._remove_orphan(name, orphans, orphan_action, config_io, project)
+
+            if not any(h["name"] == name for h in project.get("harnesses") or []):
+                return Err(ResourceNotFoundError(f'Harness "{name}" not found.'))
+
+            if orphan_action:
+                return Err(
+                    ValidationError(
+                        f'--keep/--discard only apply to a preview-build (orphan) harness. "{name}" is managed by '
+                        "CloudFormation; remove it without those flags and run `agentcore deploy` to delete it from AWS."
+                    )
+                )
+
+            self._remove_from_spec(name, config_io, project)
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    @staticmethod
+    def _read_state(config_io: ConfigIO) -> dict[str, Any] | None:
+        try:
+            return to_jsonable(config_io.read_deployed_state())
+        except Exception:  # noqa: BLE001 - `.catch(() => undefined)`
+            return None
+
+    def _remove_orphan(
+        self,
+        name: str,
+        orphans: list[OrphanHarness],
+        action: OrphanAction | None,
+        config_io: ConfigIO,
+        project: dict[str, Any],
+    ) -> Ok[None] | Err[Exception]:
+        if not action:
+            return Err(
+                ValidationError(
+                    f'No changes were made — "{name}" was not deleted. It was created by the preview build and is '
+                    "not managed by CloudFormation, so CloudFormation cannot delete it. Removing it deletes the "
+                    "resource directly from your AWS account. Re-run with an explicit choice:\n"
+                    "  --keep     delete it from AWS but keep it in agentcore.json (it moves to GA; the next "
+                    "`agentcore deploy` recreates it under CloudFormation)\n"
+                    "  --discard  delete it from AWS and remove it from agentcore.json (you no longer want it)"
+                )
+            )
+
+        from agentcore.aws.agentcore_harness import delete_harness, is_harness_not_found_error
+
+        for orphan in orphans:
+            try:
+                delete_harness(region=orphan.region, harness_id=orphan.harness_id)
+            except Exception as exc:  # noqa: BLE001
+                if not is_harness_not_found_error(exc):
+                    return Err(
+                        Exception(
+                            f'Failed to delete orphan harness "{name}" ({orphan.harness_id}) in {orphan.region}: '
+                            f"{get_error_message(exc)}. Local state was left unchanged — resolve the error and retry."
+                        )
+                    )
+
+        state = self._read_state(config_io)
+        if state:
+            for orphan in orphans:
+                harnesses = (((state.get("targets") or {}).get(orphan.target_name) or {}).get("resources") or {}).get(
+                    "harnesses"
+                )
+                if harnesses is not None:
+                    harnesses.pop(orphan.name, None)
+            config_io.write_deployed_state(state)
+
+        if action == "discard" and any(h["name"] == name for h in project.get("harnesses") or []):
+            self._remove_from_spec(name, config_io, project)
+        return Ok(None)
+
+    def _remove_from_spec(self, name: str, config_io: ConfigIO, project: dict[str, Any]) -> None:
+        project["harnesses"] = [h for h in project.get("harnesses") or [] if h["name"] != name]
+        memory_name = f"{name}Memory"
+        if any(m["name"] == memory_name for m in project.get("memories") or []):
+            project["memories"] = [m for m in project.get("memories") or [] if m["name"] != memory_name]
+        self.write_project_spec(project, config_io)
+        shutil.rmtree(config_io.get_path_resolver().get_harness_dir(name), ignore_errors=True)
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        project = to_jsonable(self.read_project_spec())
+        harnesses = project.get("harnesses") or []
+        if not any(h["name"] == name for h in harnesses):
+            raise Exception(f'Harness "{name}" not found.')
+        memory_name = f"{name}Memory"
+        has_memory = any(m["name"] == memory_name for m in project.get("memories") or [])
+        summary = [f"Removing harness: {name}"]
+        if has_memory:
+            summary.append(f"Removing associated memory: {memory_name}")
+        after = {**project, "harnesses": [h for h in harnesses if h["name"] != name]}
+        if has_memory:
+            after["memories"] = [m for m in project.get("memories") or [] if m["name"] != memory_name]
+        return RemovalPreview(summary, [f"app/{name}"], [SchemaChange("agentcore/agentcore.json", project, after)])
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(h["name"]) for h in to_jsonable(self.read_project_spec()).get("harnesses") or []]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def is_orphan(self, name: str) -> bool:
+        try:
+            config_root = find_config_root()
+            if not config_root:
+                return False
+            return len(find_orphan_harnesses(self._read_state(ConfigIO(base_dir=config_root)), name)) > 0
+        except Exception:  # noqa: BLE001
+            return False
+
+    # --- CLI ----------------------------------------------------------------------------
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        from agentcore.cli.commands.add.skill_command import register_add_skill
+        from agentcore.cli.commands.add.tool_command import register_add_tool
+        from agentcore.cli.commands.remove.skill_command import register_remove_skill
+        from agentcore.cli.commands.remove.tool_command import register_remove_tool
+        from agentcore.primitives._harness_cli import register_add_harness
+
+        register_add_harness(self, add_app)
+        self._register_harness_remove_subcommand(remove_app)
+        register_add_tool(add_app)
+        register_add_skill(add_app)
+        register_remove_tool(remove_app)
+        register_remove_skill(remove_app)
+
+    def _register_harness_remove_subcommand(self, remove_app: typer.Typer) -> None:
+        @remove_app.command(self.kind, help=f"Remove {self.article} {self.label.lower()} from the project")
+        def remove_command(
+            name: str | None = typer.Option(None, "--name", help="Name of resource to remove [non-interactive]"),
+            yes: bool = typer.Option(False, "-y", "--yes", help="Skip confirmation prompt [non-interactive]"),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+            keep: bool = typer.Option(
+                False,
+                "--keep",
+                help="For a preview-build orphan: delete it from AWS but keep it in agentcore.json (it moves to GA; "
+                "the next deploy recreates it under CloudFormation)",
+            ),
+            discard: bool = typer.Option(
+                False,
+                "--discard",
+                help="For a preview-build orphan: delete it from AWS and remove it from agentcore.json",
+            ),
+        ) -> None:
+            self._run_harness_remove(name, yes, as_json, keep, discard)
+
+    def _run_harness_remove(self, name: str | None, yes: bool, as_json: bool, keep: bool, discard: bool) -> None:
+        try:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+            if keep and discard:
+                emit_json({"success": False, "error": "--keep and --discard are mutually exclusive"})
+                raise typer.Exit(1)
+            action: OrphanAction | None = "keep" if keep else "discard" if discard else None
+
+            if name or yes or as_json or action:
+                if not name:
+                    emit_json({"success": False, "error": "--name is required"})
+                    raise typer.Exit(1)
+                result = self.remove(name, action)
+                if not result.success and not action and not as_json and self.is_orphan(name):
+                    typer.echo(f"Error: {get_error_message(result.error)}", err=True)
+                    raise typer.Exit(1)
+                emit_json(
+                    {
+                        "success": result.success,
+                        "resourceType": self.kind,
+                        "resourceName": name,
+                        "message": f"Removed {self.label.lower()} '{name}'" if result.success else None,
+                        "note": SOURCE_CODE_NOTE if result.success else None,
+                        "error": None if result.success else get_error_message(result.error),
+                    }
+                )
+                raise typer.Exit(0 if result.success else 1)
+
+            interactive.require_tty()
+            self.remove_interactive()
+        except typer.Exit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            if as_json:
+                emit_json({"success": False, "error": get_error_message(exc)})
+            else:
+                typer.echo(f"Error: {get_error_message(exc)}", err=True)
+            raise typer.Exit(1) from None
+
+    def remove_interactive(self) -> None:
+        """RemoveFlow for harnesses: orphans get the delete-and-keep / delete-and-discard choice."""
+        removable = self.get_removable()
+        if not removable:
+            typer.echo(f"No {self.label.lower()} resources to remove.")
+            return
+        name = interactive.select(
+            f"Select {self.article} {self.label.lower()} to remove",
+            [interactive.Choice(r.name, r.name) for r in removable],
+        )
+        action: OrphanAction | None = None
+        if self.is_orphan(name):
+            choice = interactive.select(
+                f'"{name}" was created by the preview build and is not managed by CloudFormation. '
+                "Removing it deletes it directly from your AWS account.",
+                [
+                    interactive.Choice(
+                        "Delete from AWS and keep in agentcore.json",
+                        "keep",
+                        "It moves to GA; the next `agentcore deploy` recreates it under CloudFormation",
+                    ),
+                    interactive.Choice(
+                        "Delete from AWS and remove from agentcore.json", "discard", "You no longer want it"
+                    ),
+                    interactive.Choice("Cancel", "cancel"),
+                ],
+            )
+            if choice == "cancel":
+                typer.echo("Cancelled.")
+                return
+            action = choice
+        else:
+            preview = self.preview_remove(name)
+            for line in preview.summary:
+                typer.echo(f"  {line}")
+            for directory in preview.directories_to_delete:
+                typer.echo(f"  Delete directory: {directory}")
+            if not interactive.confirm(f"Remove {self.label.lower()} '{name}'?", default=False):
+                typer.echo("Cancelled.")
+                return
+        result = self.remove(name, action)
+        if not result.success:
+            typer.echo(f"Error: {get_error_message(result.error)}", err=True)
+            raise typer.Exit(1)
+        typer.echo(f"Removed {self.label.lower()} '{name}'")
+        typer.echo(SOURCE_CODE_NOTE)
+
+    def add_interactive(self) -> None:
+        from agentcore.primitives._harness_wizard import run_add_harness_wizard
+
+        run_add_harness_wizard(self)
+
+
+def emit_harness_add_failure(result: Err[Exception], as_json: bool) -> None:
+    """``console.log(JSON.stringify(result))`` / ``console.error(result.error)`` for a failed add."""
+    if as_json:
+        typer.echo(json.dumps({"success": False, "error": js_error_object(result.error)}, separators=(",", ":")))
+    else:
+        name = result.error.name if isinstance(result.error, BaseError) else "Error"
+        sys.stderr.write(f"{name}: {get_error_message(result.error)}\n")
+
+
+__all__ = [
+    "DEFAULT_BEDROCK_MANTLE_MODEL_ID",
+    "DEFAULT_MODEL_IDS",
+    "AddHarnessOptions",
+    "HarnessPrimitive",
+    "add_options_from_dict",
+    "parse_access_points",
+    "parse_container_flag",
+]
+
+PRIMITIVE = HarnessPrimitive()