agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/cli/env/multi.py

@@ -0,0 +1,282 @@
+import asyncio
+
+import click
+
+from agent_env.artifact import EnvironmentArtifact, EnvironmentUniverseArtifact
+from agent_env.cli.utils import detect_base_metadata, env_provider_type_option, skips_local_validation
+from agent_env.env import Env, MultiEnv
+
+
+def parse_env_ref(ref: str) -> tuple[str, int | None]:
+    """Parse 'id' or 'id:version' format."""
+    if ":" in ref:
+        id_part, version_part = ref.split(":", 1)
+        return id_part, int(version_part)
+    return ref, None
+
+
+@click.group(name="multi")
+def multi():
+    """MultiEnv commands."""
+    pass
+
+
+@multi.command()
+@click.option("--id", "env_id", required=True, help="Env id")
+@click.option("--mcp-server", "mcp_servers", multiple=True, help="MCPServerEnv id[:version]")
+@click.option("--website", "websites", multiple=True, help="WebsiteEnv id[:version]")
+@click.option("--metadata", "metadata_pairs", multiple=True, help="Metadata key=value pair (repeatable)")
+@click.option("--name", default=None, help="Name agents see this env's MCP server under, e.g. crm -> mcp__crm__<tool> (default: env + 4 random digits per deploy)")
+@env_provider_type_option("What deploys the env: 'gateway' (a gateway in front of its servers and websites, whatever their own "
+                          "env_provider_type), or the type of an installed agent_env.env_providers plugin, which deploys them all", "multi")
+@click.option("--validate", "run_validation", is_flag=True, default=False, help="Validate the environment after registering it")
+def put(env_id: str, mcp_servers: tuple[str, ...], websites: tuple[str, ...], metadata_pairs: tuple[str, ...], name: str | None, env_provider_type: str,
+        run_validation: bool):
+    """Create a MultiEnv from MCPServerEnv and/or WebsiteEnv ids."""
+
+    if not mcp_servers and not websites:
+        click.echo("Error: At least one of --mcp-server or --website must be provided.", err=True)
+        raise SystemExit(1)
+
+    mcp_server_envs = []
+    for ref in mcp_servers:
+        server_id, server_version = parse_env_ref(ref)
+        click.echo(f"Fetching MCPServerEnv: id={server_id} version={server_version or 'latest'}...")
+        env = Env.get(server_id, version=server_version)
+        if env.type != "mcp_server":
+            click.echo(f"Error: {server_id} is type '{env.type}', expected 'mcp_server'", err=True)
+            raise SystemExit(1)
+        mcp_server_envs.append(env)
+        click.echo(f"  Found: id={env.id} version={env.version}")
+
+    website_envs = []
+    for ref in websites:
+        website_id, website_version = parse_env_ref(ref)
+        click.echo(f"Fetching WebsiteEnv: id={website_id} version={website_version or 'latest'}...")
+        env = Env.get(website_id, version=website_version)
+        if env.type != "website":
+            click.echo(f"Error: {website_id} is type '{env.type}', expected 'website'", err=True)
+            raise SystemExit(1)
+        website_envs.append(env)
+        click.echo(f"  Found: id={env.id} version={env.version}")
+
+    user_metadata = {}
+    for pair in metadata_pairs:
+        if "=" not in pair:
+            raise SystemExit(f"Invalid metadata format '{pair}', expected key=value")
+        key, value = pair.split("=", 1)
+        user_metadata[key] = value
+    metadata = detect_base_metadata()
+    metadata.update(user_metadata)
+
+    refusal = MultiEnv(id=env_id, version=None, mcp_server_envs=mcp_server_envs, website_envs=website_envs, name=name,
+                       env_provider_type=env_provider_type).deploy_refusal()
+    if refusal:
+        click.echo(f"Error: {refusal}", err=True)
+        raise SystemExit(1)
+    click.echo(f"Creating MultiEnv...")
+    multi_env = MultiEnv.put(id=env_id, mcp_server_envs=mcp_server_envs, website_envs=website_envs, metadata=metadata if metadata else None, name=name,
+                             env_provider_type=env_provider_type)
+    click.echo(f"Created MultiEnv: id={multi_env.id} version={multi_env.version} env_provider_type={multi_env.env_provider_type}")
+    if run_validation and not skips_local_validation(multi_env.id, "env"):
+        click.echo("\nValidating environment...")
+        instance_id = asyncio.run(multi_env.validate(on_progress=click.echo))
+        click.echo(f"Validation task: {instance_id}")
+
+
+@multi.command(name="load-environment-universe-artifact")
+@click.option("--env-instance-id", "env_instance_id", required=True, help="Deployed env instance ID")
+@click.option("--environment-universe-artifact-id", "environment_universe_artifact_id",
+              required=True, help="EnvironmentUniverseArtifact id")
+@click.option("--snapshot-after-load/--no-snapshot-after-load", "snapshot_after_load", default=None,
+              help="After a full re-ingest, bake a clean snapshot so later loads of this "
+                   "universe restore from an image instead of re-ingesting every service. "
+                   "Defaults to AGENT_ENV_SNAPSHOT_AFTER_LOAD (off).")
+def load_environment_universe_artifact(env_instance_id: str, environment_universe_artifact_id: str,
+                                       snapshot_after_load: bool | None):
+    """Load an environment universe artifact into a deployed env."""
+    from agent_env.store.base import NotFoundError
+
+    from agent_env.env.store import get_env_instance_store
+    try:
+        deployed_env = get_env_instance_store().get(env_instance_id)
+    except NotFoundError:
+        click.echo(f"Error: Instance '{env_instance_id}' not found", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Instance: {env_instance_id} (env={deployed_env.env_id} v{deployed_env.env_version})")
+    if getattr(deployed_env, "sandbox_type", None):
+        click.echo(f"Sandbox backend: {deployed_env.sandbox_type}")
+    env = Env.get(deployed_env.env_id, deployed_env.env_version)
+    env = asyncio.run(type(env).from_deployed_env(deployed_env))
+
+    if not hasattr(env, "load_environment_universe_artifact"):
+        click.echo(f"Error: Env type '{env.type}' does not support load_environment_universe_artifact", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Fetching environment universe artifact: id={environment_universe_artifact_id}...")
+    universe_artifact = EnvironmentUniverseArtifact.get(environment_universe_artifact_id)
+    click.echo(f"Found environment universe artifact: id={universe_artifact.id} version={universe_artifact.version}")
+
+    click.echo("Loading environment universe artifact...")
+    from agent_env.env.envs.multi_env import MultiEnv
+
+    if isinstance(env, MultiEnv):
+        result = asyncio.run(env.load_environment_universe_artifact(
+            universe_artifact, snapshot_after_load=snapshot_after_load,
+        ))
+    else:
+        if snapshot_after_load:
+            click.echo(f"Note: env type '{env.type}' has no servicedb to snapshot; "
+                       "--snapshot-after-load ignored")
+        result = asyncio.run(env.load_environment_universe_artifact(universe_artifact))
+    click.echo("Successfully loaded all environment artifacts into env")
+
+    # Which path ran decides whether this load could time out at all, so say it out
+    # loud. Measured on a 13-service / ~8.7GB universe: restore ~4min, re-ingest
+    # ~3.5min on 8 vCPU but a FAILURE on the 1-vCPU default. Restore is not
+    # reliably faster -- it is bounded, which is the part that matters.
+    if getattr(result, "restored_from_snapshot", False):
+        click.echo(f"Restored from snapshot image: {result.snapshot_db_image_artifact_id}")
+    else:
+        click.echo("Re-ingested every service over HTTP (no clean snapshot matched); each "
+                   "service was racing its own 600s timeout")
+        if result.snapshot_baked:
+            click.echo("Baked a clean snapshot; the next load of this universe can restore "
+                       "from it instead of re-ingesting")
+        elif result.snapshot_baked is False:
+            click.echo(f"Snapshot bake did not produce a reusable snapshot: {result.snapshot_bake_error}")
+
+    if result.metadata_filepaths:
+        click.echo("Metadata files downloaded:")
+        for key, path in result.metadata_filepaths.items():
+            click.echo(f"  {key} -> {path}")
+
+
+@multi.command(name="load-environment-artifact")
+@click.option("--env-instance-id", "env_instance_id", required=True, help="Deployed env instance ID")
+@click.option("--environment-artifact-id", "environment_artifact_id",
+              required=True, help="EnvironmentArtifact id")
+def load_environment_artifact(env_instance_id: str, environment_artifact_id: str):
+    """Load an environment artifact into a deployed env."""
+    from agent_env.store.base import NotFoundError
+
+    from agent_env.env.store import get_env_instance_store
+    try:
+        deployed_env = get_env_instance_store().get(env_instance_id)
+    except NotFoundError:
+        click.echo(f"Error: Instance '{env_instance_id}' not found", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Instance: {env_instance_id} (env={deployed_env.env_id} v{deployed_env.env_version})")
+    env = Env.get(deployed_env.env_id, deployed_env.env_version)
+    env = asyncio.run(type(env).from_deployed_env(deployed_env))
+
+    if not hasattr(env, "load_environment_artifact"):
+        click.echo(f"Error: Env type '{env.type}' does not support load_environment_artifact", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Fetching environment artifact: id={environment_artifact_id}...")
+    environment_artifact = EnvironmentArtifact.get(environment_artifact_id)
+    click.echo(f"Found environment artifact: id={environment_artifact.id} version={environment_artifact.version}")
+
+    click.echo("Loading environment artifact...")
+    asyncio.run(env.load_environment_artifact(environment_artifact))
+    click.echo("Loaded environment artifact into env")
+
+
+@multi.command()
+@click.option("--id", "env_id", required=True, help="MultiEnv id")
+@click.option("--version", "env_version", type=int, default=None, help="Env version (default: latest)")
+def validate(env_id: str, env_version: int | None):
+    """Validate a MultiEnv's environment card and persist it to env metadata."""
+    from agent_env.store.base import NotFoundError
+    from agent_env.task_step.task_steps.env_card_validator import VALIDATED_ENVIRONMENT_CARD_KEY
+
+    try:
+        env = Env.get(env_id, env_version)
+    except NotFoundError:
+        click.echo(f"Error: Env '{env_id}' not found", err=True)
+        raise SystemExit(1)
+
+    if not isinstance(env, MultiEnv):
+        click.echo(f"Error: Env '{env_id}' is type '{env.type}', expected 'multi'", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Validating env: id={env.id} version={env.version}")
+    instance_id = asyncio.run(env.validate(on_progress=click.echo))
+    click.echo(f"Task instance: {instance_id}")
+
+    env = Env.get(env_id, env.version)
+    card_val = env.metadata.get(VALIDATED_ENVIRONMENT_CARD_KEY)
+    click.secho("\nEnvironment card:", bold=True)
+    if not card_val:
+        click.echo("  (not validated)")
+    elif card_val.get("accessible"):
+        missing = [f for f, v in card_val.get("required_fields", {}).items() if not v.get("present")]
+        click.secho(f"  ACCESSIBLE: {card_val.get('children_count', 0)} child env(s); extensions={card_val.get('extensions', [])}; tools={card_val.get('tools', [])}", fg="green")
+        if missing:
+            click.secho(f"  missing required fields: {missing}", fg="yellow")
+    else:
+        click.secho(f"  NOT ACCESSIBLE: {card_val.get('error', 'no card')}", fg="magenta")
+
+
+@multi.command(name="validate-universe-compatibility")
+@click.option("--env-id", required=True, help="MultiEnv id")
+@click.option("--env-version", type=int, default=None, help="Env version (default: latest)")
+@click.option("--universe-artifact-id", required=True, help="EnvironmentUniverseArtifact id")
+def validate_universe_compatibility(env_id: str, env_version: int | None, universe_artifact_id: str):
+    """Validate universe artifact compatibility with a MultiEnv via load/export roundtrip."""
+    from agent_env.store.base import NotFoundError
+
+    try:
+        env = Env.get(env_id, env_version)
+    except NotFoundError:
+        click.echo(f"Error: Env '{env_id}' not found", err=True)
+        raise SystemExit(1)
+
+    if not isinstance(env, MultiEnv):
+        click.echo(f"Error: Env '{env_id}' is type '{env.type}', expected 'multi'", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Validating env={env.id} v{env.version} universe={universe_artifact_id}")
+    instance_id = asyncio.run(env.validate_universe_compatibility(universe_artifact_id=universe_artifact_id, on_progress=click.echo))
+    click.echo(f"Task instance: {instance_id}")
+
+    from agent_env.env.env_artifact_store import get_env_artifact_store
+    from agent_env.env.env_artifact_store import EnvArtifactType, get_env_artifact_store
+    results = get_env_artifact_store().get_by_env(env_id, env_version=env.version, type=EnvArtifactType.UNIVERSE_COMPATIBILITY)
+    doc = next((r for r in results if r["artifact_id"] == universe_artifact_id), None)
+    compat = doc["data"] if doc else {}
+
+    overall = compat.get("compatible")
+    click.echo(click.style(f"\nUniverse compatibility: {'COMPATIBLE' if overall else 'INCOMPATIBLE'}", fg="green" if overall else "magenta"))
+    for svc_name, svc_result in sorted(compat.get("services", {}).items()):
+        svc_compat = svc_result.get("compatible")
+        click.echo(click.style(f"\n  {svc_name}: {'COMPATIBLE' if svc_compat else 'INCOMPATIBLE'}", fg="green" if svc_compat else "magenta"))
+        for issue in svc_result.get("issues", []):
+            critical = issue.get("critical")
+            color = "red" if critical else "yellow"
+            marker = "CRITICAL" if critical else "warning"
+            click.echo(click.style(f"    [{issue['phase']}] [{marker}] {issue['entity']}.{issue['field']}: {issue['type']} - {issue['detail']}", fg=color))
+
+    if compat.get("exported_universe_artifact_id"):
+        click.echo(f"\nExported universe artifact: {compat['exported_universe_artifact_id']}")
+
+
+@multi.command(name="compatible-universes")
+@click.option("--env-id", required=True, help="MultiEnv id")
+@click.option("--env-version", type=int, default=None, help="Env version (default: all versions)")
+def compatible_universes(env_id: str, env_version: int | None):
+    """List universe compatibility results for an env."""
+    from agent_env.env.env_artifact_store import get_env_artifact_store
+
+    from agent_env.env.env_artifact_store import EnvArtifactType
+    results = get_env_artifact_store().get_by_env(env_id, env_version=env_version, type=EnvArtifactType.UNIVERSE_COMPATIBILITY)
+    if not results:
+        click.echo(f"No compatibility results found for env {env_id}")
+        return
+    for r in results:
+        compat = r["data"].get("compatible", False)
+        status = click.style("COMPATIBLE", fg="green") if compat else click.style("INCOMPATIBLE", fg="magenta")
+        click.echo(f"  universe={r['artifact_id']} v{r['artifact_version']}: {status}")

agent_env/cli/env/service_db.py

@@ -0,0 +1,99 @@
+"""CLI commands for ServiceDBEnv."""
+
+from pathlib import Path
+
+import click
+
+from agent_env.artifact import DockerImageArtifact
+from agent_env.cli.utils import build_platform_option, detect_env_metadata
+from agent_env.env.envs.service_db import ServiceDBEnv
+from agent_env.config import get_config
+from agent_env.utils.docker_build import build_image
+
+# Path to ServiceDB Dockerfile
+SERVICE_DB_DOCKERFILE = Path(__file__).parent.parent.parent / "env" / "envs" / "service_db" / "Dockerfile"
+SERVICE_DB_IMAGE_NAME = "agent-env-service-db"
+DB_WEB_DOCKERFILE = Path(__file__).parent.parent.parent / "env" / "envs" / "service_db" / "Dockerfile.db-web"
+DB_WEB_IMAGE_NAME = "agent-env-db-web"
+DB_MCP_DOCKERFILE = Path(__file__).parent.parent.parent / "env" / "envs" / "service_db" / "Dockerfile.db-mcp"
+DB_MCP_IMAGE_NAME = "agent-env-db-mcp"
+
+
+@click.group(name="service-db")
+def service_db():
+    """ServiceDB environment commands."""
+    pass
+
+
+@service_db.command()
+@click.option("--id", "env_id", default=None, help="Env id (default: config default_service_db_env_id)")
+@click.option("--metadata", "metadata_pairs", multiple=True, help="Metadata key=value pair (repeatable)")
+@build_platform_option
+def put(env_id: str, metadata_pairs: tuple[str, ...], build_platform: str):
+    """Build and upload a ServiceDB environment."""
+    if not env_id:
+        env_id = get_config().default_service_db_env_id
+
+    click.echo(f"Building ServiceDB image from {SERVICE_DB_DOCKERFILE}...")
+
+    # Build Docker image
+    build_image(SERVICE_DB_DOCKERFILE, SERVICE_DB_DOCKERFILE.parent, SERVICE_DB_IMAGE_NAME, platform=build_platform)
+    click.echo("Docker build successful")
+
+    # Create DB DockerImageArtifact
+    click.echo("Creating DB DockerImageArtifact...")
+    db_artifact = DockerImageArtifact.put(
+        id=f"service-db-{env_id}",
+        description=f"ServiceDB PostgreSQL image for {env_id}",
+        image_name=SERVICE_DB_IMAGE_NAME,
+    )
+    click.echo(f"Created DB DockerImageArtifact: id={db_artifact.id} version={db_artifact.version}")
+
+    # Build db-web image (build instead of pull to avoid docker save manifest issues on Apple Silicon)
+    click.echo(f"Building db-web image from {DB_WEB_DOCKERFILE}...")
+    build_image(DB_WEB_DOCKERFILE, DB_WEB_DOCKERFILE.parent, DB_WEB_IMAGE_NAME, platform=build_platform)
+    click.echo("db-web build successful")
+
+    # Create db-web DockerImageArtifact
+    click.echo("Creating db-web DockerImageArtifact...")
+    db_web_artifact = DockerImageArtifact.put(
+        id=f"db-web-{env_id}",
+        description="db-web lightweight web UI for database inspection",
+        image_name=DB_WEB_IMAGE_NAME,
+    )
+    click.echo(f"Created db-web DockerImageArtifact: id={db_web_artifact.id} version={db_web_artifact.version}")
+
+    # Build db-mcp image (PostgreSQL MCP server for direct DB access)
+    click.echo(f"Building db-mcp image from {DB_MCP_DOCKERFILE}...")
+    build_image(DB_MCP_DOCKERFILE, DB_MCP_DOCKERFILE.parent, DB_MCP_IMAGE_NAME, platform=build_platform)
+    click.echo("db-mcp build successful")
+
+    # Create db-mcp DockerImageArtifact
+    click.echo("Creating db-mcp DockerImageArtifact...")
+    db_mcp_artifact = DockerImageArtifact.put(
+        id=f"db-mcp-{env_id}",
+        description="db-mcp PostgreSQL MCP server for direct DB access",
+        image_name=DB_MCP_IMAGE_NAME,
+    )
+    click.echo(f"Created db-mcp DockerImageArtifact: id={db_mcp_artifact.id} version={db_mcp_artifact.version}")
+
+    user_metadata = {}
+    for pair in metadata_pairs:
+        if "=" not in pair:
+            click.echo(f"Invalid metadata format '{pair}', expected key=value", err=True)
+            raise click.Abort()
+        key, value = pair.split("=", 1)
+        user_metadata[key] = value
+    metadata = detect_env_metadata(SERVICE_DB_DOCKERFILE, SERVICE_DB_DOCKERFILE.parent)
+    metadata.update(user_metadata)
+
+    # Create ServiceDBEnv
+    click.echo("Creating ServiceDBEnv...")
+    env = ServiceDBEnv.put(
+        id=env_id,
+        db_docker_image_artifact=db_artifact,
+        db_web_docker_image_artifact=db_web_artifact,
+        db_mcp_docker_image_artifact=db_mcp_artifact,
+        metadata=metadata if metadata else None,
+    )
+    click.echo(f"Created ServiceDBEnv: id={env.id} version={env.version}")

agent_env/cli/env/snapshot.py

@@ -0,0 +1,35 @@
+"""Snapshot a deployed MultiEnv's servicedb as a pre-loaded Docker image."""
+
+import asyncio
+import logging
+
+import click
+
+from agent_env.env.snapshot_store import EnvSnapshot
+
+logger = logging.getLogger(__name__)
+
+
+async def run_snapshot(instance_id: str) -> EnvSnapshot:
+    """Core snapshot logic. Returns the EnvSnapshot.
+
+    Can be called directly from tests or wrapped by the CLI command.
+    """
+    return await EnvSnapshot.create(instance_id)
+
+
+@click.command()
+@click.option("--instance-id", required=True, help="Deployed env instance ID")
+def snapshot(instance_id: str):
+    """Snapshot a deployed MultiEnv's servicedb as a pre-loaded Docker image."""
+    try:
+        result = asyncio.run(run_snapshot(instance_id))
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+    click.echo(click.style("Snapshot complete!", fg="green"))
+    click.echo(f"  instance_id: {result.instance_id}")
+    click.echo(f"  env_id: {result.env_id}")
+    click.echo(f"  environment_universe_id: {result.environment_universe_id}")
+    click.echo(f"  is_clean: {result.is_clean}")
+    click.echo(f"  db_image_artifact: {result.db_image_artifact_id} v{result.db_image_artifact_version}")

agent_env/cli/env/state/__init__.py

@@ -0,0 +1,6 @@
+"""Out-of-band lifecycle commands for an env's durable state store."""
+
+from .init import init_env_state
+from .teardown import teardown_env_state
+
+__all__ = ["init_env_state", "teardown_env_state"]

agent_env/cli/env/state/init.py

@@ -0,0 +1,108 @@
+"""Pre-initialize a durable remote state store for an env, decoupled from a deploy.
+
+Runs the same ``acquire`` + ``prepare`` a deploy would, but out-of-band and with a long TTL, so a
+long-running store can be stood up ahead of time and referenced later by its ``instance_id``
+"""
+
+import asyncio
+
+import click
+
+from agent_env.env import Env, MultiEnv
+from agent_env.store.routing import run_scope
+
+# A durable store can't be shorter-lived than a normal run, so the floor is the default run TTL
+# (agent-env's current default, mirrored from cli/env/deploy.py).
+MIN_TTL_SECONDS = 10800  # 3 hours (= default run TTL)
+DEFAULT_TTL_SECONDS = 2592000  # 30 days
+MAX_TTL_SECONDS = 31536000  # 365 days
+
+
+def _resolve_environment_names(env: Env) -> list[str]:
+    """One schema per DB-client environment. A MultiEnv contributes its MCP + website environments; a
+    standalone servicedb-backed env contributes its single one.
+
+    Must match the list the gateway passes to ``prepare`` at deploy (``EnvironmentGatewayProvider._all_environments``,
+    the authoritative one) — including the ``website_browser`` server the gateway auto-adds whenever an
+    env has websites. A name missing here yields a base without that schema, and the deploy then builds
+    it a silently-empty overlay."""
+    if isinstance(env, MultiEnv):
+        names = [e.environment_name for e in env.mcp_server_envs] + [
+            e.environment_name for e in env.website_envs
+        ]
+        if env.website_envs:
+            from agent_env.config import get_config
+
+            names.append(Env.get(get_config().default_website_browser_env_id).environment_name)
+    elif hasattr(env, "environment_name"):
+        names = [env.environment_name]
+    else:
+        return []
+    return list(dict.fromkeys(names))
+
+# TODO: right now this takes an `--id` param because the schemas to initialize the EnvStateInstance with is
+# derived from the env. Refactor this to use environment_cards, and consolidate _resolve_environment_names with the 
+# same logic in EnvironmentGatewayProvider._all_environments, so that the code can't drift
+@click.command(name="init-env-state")
+@click.option("--id", "env_id", required=True, help="Env id")
+@click.option("--env-state-type", "env_state_type", default=None,
+              help="Env state type to initialize (required). Only external types — those that "
+                   "allocate a store upstream of the gateway — can be pre-initialized out-of-band. "
+                   "Which are registered depends on the installed config.toml.")
+@click.option("--ttl-seconds", type=click.IntRange(min=MIN_TTL_SECONDS, max=MAX_TTL_SECONDS),
+              default=DEFAULT_TTL_SECONDS,
+              help=f"Store lifetime in seconds (min {MIN_TTL_SECONDS}, max {MAX_TTL_SECONDS}, "
+                   f"default {DEFAULT_TTL_SECONDS} = 30 days)")
+def init_env_state(env_id: str, env_state_type: str | None, ttl_seconds: int):
+    """Pre-initialize a durable remote state store for an env and print its instance id."""
+    from agent_env.providers.env_state import (
+        acquire_state_for_deploy,
+        build_state_provider,
+    )
+
+    if not env_state_type:
+        raise click.BadParameter("an env state type must be supplied", param_hint="'--env-state-type'")
+    state_type = env_state_type
+
+    try:
+        build_state_provider(state_type)  # resolve before any Mongo/AWS work, so a typo fails fast
+    except ValueError as e:
+        raise click.BadParameter(str(e), param_hint="'--env-state-type'") from e
+
+    click.echo(f"Fetching env: id={env_id}...")
+    env = Env.get(env_id)
+    click.echo(f"Found env: id={env.id} version={env.version} type={env.type}")
+
+    environment_names = _resolve_environment_names(env)
+    if not environment_names:
+        raise click.BadParameter(
+            f"env type '{env.type}' has no environments to back with a DB state store",
+            param_hint="'--id'",
+        )
+    click.echo(f"Environments (one schema each): {', '.join(environment_names)}")
+
+    click.echo(f"Initializing {env_state_type} store (ttl={ttl_seconds}s)...")
+
+    async def _init() -> "EnvStateInstance | None":
+        inst = await acquire_state_for_deploy(
+            env_state_type=state_type, ttl_seconds=ttl_seconds, name_hint=env_id,
+        )
+        if inst is not None:
+            await build_state_provider(state_type).prepare(environment_names, instance=inst)
+        return inst
+
+    with run_scope(env.id):
+        instance = asyncio.run(_init())
+    if instance is None:
+        raise click.BadParameter(
+            f"env state type '{env_state_type}' cannot be pre-initialized out-of-band",
+            param_hint="'--env-state-type'",
+        )
+
+    click.echo("Initialized!")
+    click.echo(f"  host:      {instance.metadata.get('host')}")
+    click.echo(f"  database:  {instance.metadata.get('dbname')}")
+    click.echo(f"  schemas:   {', '.join(environment_names)}")
+    click.echo(f"  created:   {instance.created_at_utc}")
+    click.echo(f"  expires:   {instance.expires_at_utc}")
+    click.echo("Env State Instance ID: " + click.style(instance.instance_id, fg="green"))

agent_env/cli/env/state/teardown.py

@@ -0,0 +1,44 @@
+"""Tear down a durable env-state store initialized via ``env init-env-state``.
+
+Idempotent: tearing down an instance whose store is already gone — or an unknown instance id — logs and no-ops
+rather than erroring, so a future TTL reaper and a manual teardown can race without conflict.
+"""
+
+import asyncio
+
+import click
+
+
+@click.command(name="teardown-env-state")
+@click.option("--instance-id", "instance_id", required=True, help="Env state instance id (esi-…)")
+def teardown_env_state(instance_id: str):
+    """Tear down an env-state store by instance id and retire its record."""
+    from agent_env.providers.env_state import build_state_provider, get_env_state_instance_store
+    from agent_env.store.base import NotFoundError
+
+    try:
+        instance = get_env_state_instance_store().get(instance_id)
+    except NotFoundError:
+        click.echo(f"No env state instance {instance_id} found; nothing to tear down.")
+        return
+
+    kind = instance.metadata.get("kind")
+    if kind == "base":
+        click.secho(
+            f"⚠ {instance_id} is a persistent BASE (database "
+            f"{instance.metadata.get('dbname')!r}). Tearing it down DROPS the shared base database "
+            "and everything materialized in it. Any run overlay still pointing at this base "
+            "(base_env_state_instance_id) will be orphaned — its data source disappears.",
+            fg="yellow",
+        )
+    elif kind == "run_overlay":
+        click.echo(
+            f"{instance_id} is a persistent RUN_OVERLAY over base "
+            f"{instance.metadata.get('base_env_state_instance_id')!r}; dropping only its overlay "
+            "schemas + run role. The shared base is preserved (not orphaned)."
+        )
+
+    click.echo(f"Tearing down env state instance {instance_id} ({instance.state_type})...")
+    provider = build_state_provider(instance.state_type)
+    asyncio.run(provider.teardown(instance))
+    click.echo("Done. " + click.style(f"{instance_id} torn down / retired", fg="green"))