@aws/agentcore 0.30.0 → 0.31.0

package/dist/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -711,7 +711,7 @@ exports[`Assets Directory Snapshots > CDK assets > cdk/cdk/package.json should m
     "typescript": "~5.9.3"
   },
   "dependencies": {
-    "@aws/agentcore-cdk": "0.1.0-alpha.53",
+    "@aws/agentcore-cdk": "0.1.0-alpha.54",
     "aws-cdk-lib": "~2.261.0",
     "constructs": "~10.7.0"
   }
@@ -872,6 +872,15 @@ exports[`Assets Directory Snapshots > File listing > should match the expected f
   "python/http/autogen/base/model/__init__.py",
   "python/http/autogen/base/model/load.py",
   "python/http/autogen/base/pyproject.toml",
+  "python/http/bma/base/Dockerfile",
+  "python/http/bma/base/README.md",
+  "python/http/bma/base/bma-acr-policy.json",
+  "python/http/bma/base/client.py",
+  "python/http/bma/base/lifecycle/server.py",
+  "python/http/bma/base/otel/collector.yaml",
+  "python/http/bma/base/plugins/acr-report/.codex-plugin/plugin.json",
+  "python/http/bma/base/plugins/acr-report/skills/acr-report/SKILL.md",
+  "python/http/bma/base/pyproject.toml",
   "python/http/googleadk/base/README.md",
   "python/http/googleadk/base/gitignore.template",
   "python/http/googleadk/base/main.py",
@@ -3848,6 +3857,1099 @@ packages = ["."]
 "
 `;
 
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/Dockerfile should match snapshot 1`] = `
+"FROM public.ecr.aws/lambda/microvms:al2023-minimal
+
+# OS setup
+RUN dnf install -y tar gzip findutils shadow-utils ca-certificates \\
+ && dnf clean all \\
+ && useradd -m -u 1000 app
+
+# Codex
+RUN curl -fsSL https://chatgpt.com/codex/install.sh -o /tmp/install-codex.sh \\
+ && CODEX_NON_INTERACTIVE=1 CODEX_INSTALL_DIR=/opt/bma/bin CODEX_HOME=/opt/bma/codex \\
+    sh /tmp/install-codex.sh \\
+ && chmod -R a+rX /opt/bma \\
+ && rm /tmp/install-codex.sh
+
+# CloudWatch agent
+RUN arch=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') \\
+ && curl -fsSL -o /tmp/cwagent.rpm \\
+    https://amazoncloudwatch-agent.s3.amazonaws.com/amazon_linux/\${arch}/latest/amazon-cloudwatch-agent.rpm \\
+ && rpm -i /tmp/cwagent.rpm \\
+ && rm /tmp/cwagent.rpm
+
+# uv and Python
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+ENV UV_PYTHON_INSTALL_DIR=/opt/python UV_PYTHON_BIN_DIR=/usr/local/bin
+RUN uv python install --default
+
+# Application. The layout of /opt/bma is the same as the layout of this directory.
+WORKDIR /opt/bma
+ENV UV_COMPILE_BYTECODE=1 UV_NO_PROGRESS=1 \\
+    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} UV_INDEX=\${UV_INDEX}
+COPY pyproject.toml uv.lock* ./
+RUN uv sync --no-dev
+COPY lifecycle/ lifecycle/
+COPY otel/ otel/
+COPY plugins/ plugins/
+USER app
+
+EXPOSE 8080
+CMD ["uv", "run", "--no-sync", "opentelemetry-instrument", "python", "-u", "lifecycle/server.py"]
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/README.md should match snapshot 1`] = `
+"This is a Bedrock Managed Agents (BMA) environment generated by the AgentCore CLI.
+
+# Layout
+
+BMA runs the agent loop (Codex) in the Bedrock Managed Agents service. This AgentCore Runtime (ACR) is the customer
+environment where BMA runs commands. The ACR has no model code.
+
+| Path | Description |
+| --- | --- |
+| \`Dockerfile\` | The ACR image. It installs the Codex CLI with OpenAI's installer, the CloudWatch agent, Python with uv, and the dependencies in \`pyproject.toml\`. It copies \`lifecycle/\`, \`otel/\`, and \`plugins/\` to the same paths under \`/opt/bma\`, the working directory of the image. |
+| \`lifecycle/server.py\` | The environment lifecycle server, \`bma-acr-lifecycle\`. It handles the lifecycle calls from BMA and starts \`codex exec-server\`. |
+| \`otel/collector.yaml\` | The configuration of the CloudWatch agent. The agent gets the spans and logs of \`codex exec-server\`, puts the session ID on them, and sends them to X-Ray and CloudWatch Logs with the ACR role. To turn off observability, add \`DISABLE_ADOT_OBSERVABILITY\` with the value \`true\` to \`envVars\`. |
+| \`plugins/acr-report\` | A Codex plugin with the \`acr-report\` skill. The skill saves the Python version, the user ID, and the working directory in \`acr-report.txt\`. |
+| \`bma-acr-policy.json\` | Lets the ACR role call \`bedrock-mantle:RegisterEnvironment\` and \`bedrock-mantle:ConnectEnvironment\` on every Mantle project. To limit the role to your projects, change \`Resource\` to \`arn:aws:bedrock-mantle:<region>:<account-id>:project/<project-id>\`. |
+| \`pyproject.toml\` | The Python dependencies. \`aws-opentelemetry-distro\` sends a span for each call from BMA and a child span for each step of the call, for example the state load or the exec-server start. \`bedrock-agentcore\` is the AgentCore SDK. The \`dev\` group has the dependencies of \`client.py\`, and the image does not install it. Each image build installs the latest Python and the latest releases. To pin them, run \`uv lock\` and keep \`uv.lock\` next to this file. |
+| \`client.py\` | A sample OpenAI SDK client. It creates a session in BMA, and BMA sends the session's commands to this ACR. |
+
+Do not change \`lifecycle/server.py\`. It must match the lifecycle calls that BMA makes.
+
+The server always sends HTTP 200, because the Runtime changes any other status to 424 and drops the body. If a call
+fails, the body has the HTTP status code of the failure in \`status_code\` and the reason in \`error\`, for example
+\`{"error": "the exec-server did not start", "status_code": 503}\`.
+
+# Codex version
+
+The image build installs the latest Codex release. The server needs Codex 0.154.0 or newer because it runs
+\`codex exec-server\`. To pin a release, set \`CODEX_RELEASE\` next to \`CODEX_NON_INTERACTIVE\` in the \`Dockerfile\`. The
+image build downloads Codex and Python from the internet, so a build in VPC mode needs a route to the internet.
+
+# ACR settings
+
+\`agentcore create\` writes these settings to \`agentcore/agentcore.json\`:
+
+- An idle timeout of 1800 seconds (30 minutes) and a maximum lifetime of 28800
+  seconds (8 hours).
+- No session storage. Session storage is only for a microVM Runtime, so without it the same settings work on a
+  capacity provider.
+
+A value that you give to \`agentcore create\` replaces the value above.
+
+The server keeps the connection state in \`state.json\` in \`BMA_STATE_DIR\`. The default is \`/home/app/.bma\`. The client
+sets the workspace in \`workspace_directory\` when it creates the session. \`client.py\` uses \`/home/app/workspace\`. The
+server creates that directory and runs the agent commands in it. If the activate call has no workspace directory, the
+server returns status 400. If the server cannot create the directory, it returns status 503, logs
+\`workspace_unavailable\`, and does not start the exec-server.
+
+Files in the home directory do not stay after an idle stop. On a microVM Runtime, to keep the files and the connection
+state after an idle stop, put the home directory on session storage:
+
+1. Add session storage with \`--session-storage-mount-path /mnt/home\`.
+2. Set \`BMA_HOME_DIR\` to \`/mnt/home\` in \`envVars\`. Then \`state.json\` is in \`/mnt/home/.bma\`, and \`CODEX_HOME\` is
+   \`/mnt/home/.codex\`.
+3. Set \`WORKSPACE_DIRECTORY\` in \`client.py\` to \`/mnt/home/workspace\`.
+
+If you set \`WORKSPACE_DIRECTORY\` to a path on session storage, the Runtime must have session storage. If not, the
+server cannot create the workspace, and the session fails. If \`BMA_STATE_DIR\` is not on a mounted path, or the server
+cannot create it, the server keeps \`state.json\` in \`.bma\` in \`BMA_HOME_DIR\`.
+
+# Environment variables
+
+To change a setting of the server, add the variable to \`envVars\` of the agent in \`agentcore/agentcore.json\`. Then run
+\`agentcore deploy\`. For example:
+
+\`\`\`json
+"envVars": [
+  { "name": "BMA_MAX_TURN_LEASE", "value": "600" },
+  { "name": "BMA_CODEX_BINARY", "value": "/opt/bma/bin/codex" }
+]
+\`\`\`
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| \`DISABLE_ADOT_OBSERVABILITY\` | Not set | Set to \`true\` to turn off the traces and the exec-server logs. The server still writes its own logs. |
+| \`BMA_STATE_DIR\` | \`.bma\` in \`BMA_HOME_DIR\` | The directory of \`state.json\`. |
+| \`BMA_HOME_DIR\` | The home directory of the image user | \`HOME\` of the exec-server. |
+| \`BMA_CODEX_HOME\` | \`.codex\` in \`BMA_HOME_DIR\` | \`CODEX_HOME\` of the exec-server. |
+| \`BMA_CODEX_BINARY\` | \`/opt/bma/bin/codex\` | The Codex binary. |
+| \`BMA_MAX_TURN_LEASE\` | \`300\` | The longest turn lease, in seconds. The server changes a longer request to this value. |
+
+
+# Skills and plugins
+
+BMA finds skills and plugins in the directories that the client gives in \`capability_directories\`. A directory can be
+at any absolute path in the ACR. BMA does not need a copy in the workspace.
+
+- To add a skill to the image, put a plugin under \`plugins/\` and add its path under \`/opt/bma/plugins\` to
+  \`CAPABILITY_DIRECTORIES\` in \`client.py\`. A plugin has a \`.codex-plugin/plugin.json\` file and a \`skills/\` directory
+  with one directory for each skill. Each skill directory has a \`SKILL.md\` file.
+- To share skills from an S3 bucket, mount an S3 Files access point, for example at \`/mnt/skills\`, and add that
+  path to \`CAPABILITY_DIRECTORIES\`. Add the mount to \`filesystemConfigurations\` in \`agentcore/agentcore.json\` as an
+  \`s3FilesAccessPoint\` entry. An S3 Files mount needs VPC network mode.
+
+# Deploy
+
+\`\`\`bash
+agentcore deploy
+\`\`\`
+
+Give the ACR ARN to BMA when you create the BMA environment.
+
+# Run the client
+
+Run the client from this directory with the ACR ARN from \`agentcore status\`:
+
+\`\`\`bash
+uv run client.py --runtime <ACR ARN>
+\`\`\`
+
+\`uv run\` installs the dependencies and the \`dev\` group from \`pyproject.toml\` in \`.venv\`. The client creates a BMA
+session and prints the session ID, each command with its output, and the answer of the agent as it streams.
+
+To send another input to the same session, add the BMA session ID. If the session does not exist, the client creates a
+new session and prints its ID.
+
+\`\`\`bash
+uv run client.py --runtime <ACR ARN> --session-id <BMA session ID> --input "List the files in the workspace."
+\`\`\`
+
+If you add a Gateway, add \`--gateway <Gateway MCP URL>\` with the URL from the output of \`agentcore deploy\`. BMA adds
+the Gateway tools when it creates the session, so the flag has no effect on a session that exists.
+
+To delete the session after the turn, add \`--delete\`. To print each stream event as JSON, add \`--raw\`.
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/bma-acr-policy.json should match snapshot 1`] = `
+"{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "AttachToBmaEnvironment",
+      "Effect": "Allow",
+      "Action": ["bedrock-mantle:RegisterEnvironment", "bedrock-mantle:ConnectEnvironment"],
+      "Resource": "arn:*:bedrock-mantle:*:*:project/*"
+    }
+  ]
+}
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/client.py should match snapshot 1`] = `
+""""Send an input to a Bedrock Managed Agents session that uses this project's ACR."""
+
+import argparse
+import json
+from typing import Any
+
+from aws_bedrock_token_generator import provide_token
+from openai import NotFoundError, OpenAI
+
+BMA_MODEL_ID = "openai.gpt-5.6-luna"
+WORKSPACE_DIRECTORY = "/home/app/workspace"
+CAPABILITY_DIRECTORIES = ["/opt/bma/plugins"]
+TURN_END = ("completed", "failed", "cancelled")
+TOOL_CALLS = ("mcp_call", "function_call", "web_search_call")
+
+
+def show(data: dict[str, Any]) -> None:
+    """Prints the session ID, the commands, the tool calls, and the answer."""
+    kind = data["type"].removeprefix("agent.session.")
+    item = data.get("item") or {}
+    if kind == "created":
+        print(f"Session {data['session']['id']}")
+    elif kind == "turn.output_text.delta":
+        print(data["delta"], end="", flush=True)
+    elif kind == "turn.item.done" and item.get("type") == "command_execution":
+        print(f"\\n$ {item['command']}\\n{item.get('output') or ''}".rstrip())
+    elif kind == "turn.item.done" and item.get("type") in TOOL_CALLS:
+        print(f"\\nTool {item.get('name') or item['type']} {item.get('status')}")
+    elif kind == "error" or kind.split(".")[-1] in TURN_END:
+        source = data.get("turn") or data.get("environment") or data.get("session")
+        print(f"\\n{kind} {(source or data).get('error') or ''}".rstrip())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--runtime", required=True, help="The ACR ARN.")
+    parser.add_argument(
+        "--session-id",
+        help="The BMA session ID. If it does not exist, the client creates a session.",
+    )
+    parser.add_argument(
+        "--input",
+        default="Use the acr-report skill to save an ACR report in the workspace.",
+    )
+    parser.add_argument(
+        "--gateway",
+        help="The Gateway URL from the output of \`agentcore deploy\`.",
+    )
+    parser.add_argument("--delete", action="store_true", help="Delete the session.")
+    parser.add_argument("--raw", action="store_true", help="Print events as JSON.")
+    args = parser.parse_args()
+    # BMA must run in the Region of the ACR.
+    region = args.runtime.split(":")[3]
+
+    with OpenAI(
+        api_key=lambda: provide_token(region=region),
+        base_url=f"https://bedrock-mantle.{region}.api.aws/openai/v1",
+    ) as client:
+        sessions = client.beta.agents.sessions
+        session_id = args.session_id
+        if session_id:
+            try:
+                session = sessions.retrieve(session_id).model_dump(warnings=False)
+            except NotFoundError:
+                print(f"Session {session_id} does not exist.")
+                session_id = None
+            else:
+                if session["environment"].get("runtime_arn") != args.runtime:
+                    raise ValueError(f"Session {session_id} uses another ACR.")
+
+        if session_id:
+            # BMA opens the stream only with stream=true, and the SDK does not send it.
+            events = sessions.events.stream(session_id, extra_query={"stream": "true"})
+            message = {
+                "role": "user",
+                "content": [{"type": "input_text", "text": args.input}],
+            }
+            sessions.events.create(
+                session_id,
+                events=[{"type": "agent.session.input.message", "input": [message]}],
+            )
+        else:
+            agent: dict[str, Any] = {
+                "model": BMA_MODEL_ID,
+                "instructions": "Use the available tools to complete the task.",
+            }
+            if args.gateway:
+                # Bedrock Managed Agents calls Gateway with IAM from the service side.
+                agent["tools"] = [
+                    {
+                        "type": "mcp",
+                        "server_label": "team_tools",
+                        "required": True,
+                        "connection_origin": "service",
+                        "transport": {"type": "http", "server_url": args.gateway},
+                    }
+                ]
+                args.input += (
+                    " Then use the Gateway's documentation and runbook tools to explain"
+                    " how to investigate an MCP connection failure. Cite your sources."
+                )
+            events = sessions.create(
+                agent=agent,
+                environment={
+                    "type": "aws_bedrock_agentcore",
+                    "runtime_arn": args.runtime,
+                    "runtime_qualifier": "DEFAULT",
+                    "workspace_directory": WORKSPACE_DIRECTORY,
+                    "capability_directories": CAPABILITY_DIRECTORIES,
+                },
+                input=args.input,
+                stream=True,
+            )
+
+        with events:
+            for event in events:
+                data = event.model_dump(mode="json", warnings=False)
+                session_id = session_id or (data.get("session") or {}).get("id")
+                if args.raw:
+                    print(json.dumps(data), flush=True)
+                else:
+                    show(data)
+                if data["type"].removeprefix("agent.session.turn.") in TURN_END:
+                    break
+
+        if args.delete:
+            sessions.delete(session_id)
+            print(f"\\nDeleted session {session_id}")
+
+
+if __name__ == "__main__":
+    main()
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/lifecycle/server.py should match snapshot 1`] = `
+""""AgentCore Runtime (ACR) lifecycle server for a BMA exec-server.
+
+AgentCore calls \`\`GET /ping\`\` for health and \`\`POST /invocations\`\` for the BMA
+lifecycle calls \`\`activate\`\`, \`\`renew_turn_lease\`\`, \`\`release_turn_lease\`\`, and
+\`\`disconnect\`\`. An invocation with no action returns the status.
+
+The server runs one \`\`codex exec-server\`\` for the attachment of the last
+\`\`activate\`\` call and saves the attachment in \`\`state.json\`\` in \`\`BMA_STATE_DIR\`\`.
+The default is \`\`.bma\`\` in the home directory. If the server cannot create
+\`\`BMA_STATE_DIR\`\`, it keeps \`\`state.json\`\` in \`\`.bma\`\` in the home directory.
+AgentCore mounts session storage only when an invocation starts, so the server
+reads \`\`state.json\`\` on the first invocation. On replacement compute, that
+invocation starts the exec-server again.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shlex
+import signal
+import subprocess
+import threading
+import time
+from datetime import datetime, timezone
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+from opentelemetry import propagate, trace
+
+BMA_NAME = "bma-acr-lifecycle"
+BMA_VERSION = "0.1.0"
+TRACER = trace.get_tracer(BMA_NAME, BMA_VERSION)
+
+BMA_CODEX_BINARY = Path(os.environ.get("BMA_CODEX_BINARY", "/opt/bma/bin/codex"))
+BMA_HOME_DIR = Path(os.environ.get("BMA_HOME_DIR", str(Path.home())))
+BMA_STATE_DIR = Path(os.environ.get("BMA_STATE_DIR", str(BMA_HOME_DIR / ".bma")))
+BMA_CODEX_HOME = Path(os.environ.get("BMA_CODEX_HOME", str(BMA_HOME_DIR / ".codex")))
+BMA_MAX_TURN_LEASE = max(1, int(os.environ.get("BMA_MAX_TURN_LEASE", "300")))
+
+AWS_REGION = os.environ.get("AWS_REGION", "us-east-1")
+BMA_REMOTE_SERVICE = "bedrock-mantle"
+
+COLLECTOR_BINARY = Path("/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent")
+COLLECTOR_CONFIG = Path("/opt/bma/otel/collector.yaml")
+COLLECTOR_ENDPOINT = "http://127.0.0.1:4318"
+COLLECTOR_COMMAND = [
+    str(COLLECTOR_BINARY),
+    "-config",
+    os.devnull,
+    "-otelconfig",
+    str(COLLECTOR_CONFIG),
+]
+OBSERVABILITY_ENABLED = (
+    os.environ.get("AGENT_OBSERVABILITY_ENABLED", "").lower() == "true"
+)
+EXPORTER = '{otlp-http={endpoint="%s/v1/%s",protocol="binary"}}'
+TELEMETRY_OVERRIDES = [
+    "-c",
+    "otel.trace_exporter=" + EXPORTER % (COLLECTOR_ENDPOINT, "traces"),
+    "-c",
+    "otel.exporter=" + EXPORTER % (COLLECTOR_ENDPOINT, "logs"),
+]
+
+EXEC_SERVER_ENVIRONMENT = {
+    "RUST_LOG": "codex_exec_server=info,codex_cli=info",
+    "RUST_BACKTRACE": "1",
+    "HOME": str(BMA_HOME_DIR),
+    "CODEX_HOME": str(BMA_CODEX_HOME),
+    "OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED": "false",
+    "OTEL_PYTHON_LOG_CORRELATION": "false",
+}
+
+PROTOCOL_VERSION = 1
+RESTART_DELAY_SECONDS = 5
+STOP_GRACE_SECONDS = 3
+
+
+def usable_dir(preferred: Path, fallback: Path) -> Path:
+    """Creates and returns preferred, or fallback if the server cannot create preferred."""
+    try:
+        preferred.mkdir(parents=True, exist_ok=True)
+        return preferred
+    except OSError as error:
+        log("directory_fallback", directory=str(preferred), error=str(error))
+    fallback.mkdir(parents=True, exist_ok=True)
+    return fallback
+
+
+def state_dir() -> Path:
+    home = BMA_HOME_DIR / ".bma"
+    return usable_dir(BMA_STATE_DIR if BMA_STATE_DIR.parent.is_dir() else home, home)
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def log(message: str, **details: Any) -> None:
+    record = {"timestamp": now(), "runtimeSessionId": LIFECYCLE.runtime_session_id}
+    print(json.dumps({**record, "message": message, **details}), flush=True)
+
+
+def step_span(name: str, **attributes: Any) -> Any:
+    """Starts a child span of the current span. The span has the session ID for the console.
+
+    A step outside a BMA call, for example an exec-server restart by the monitor thread, gets no span, so it does not
+    start a new trace.
+    """
+    if not trace.get_current_span().get_span_context().is_valid:
+        return contextlib.nullcontext(trace.INVALID_SPAN)
+    if LIFECYCLE.runtime_session_id:
+        attributes["session.id"] = LIFECYCLE.runtime_session_id
+    return TRACER.start_as_current_span(name, attributes=attributes)
+
+
+def failed(
+    span: trace.Span, message: str, error: Exception | str, **details: Any
+) -> None:
+    """Logs a failed step and sets the error on its span."""
+    log(message, **details, error=str(error))
+    if isinstance(error, Exception):
+        span.record_exception(error)
+    span.set_status(trace.StatusCode.ERROR, str(error))
+
+
+def valid_generation(generation: Any) -> bool:
+    return type(generation) is int and generation >= 0
+
+
+def parse_attachment(request: dict[str, Any]) -> tuple[str, int] | None:
+    """Returns the environment ID and the attachment generation of a BMA call."""
+    version = request.get("protocol_version")
+    environment_id = request.get("environment_id")
+    generation = request.get("attachment_generation")
+    if type(version) is not int or version != PROTOCOL_VERSION:
+        return None
+    if not isinstance(environment_id, str) or not environment_id:
+        return None
+    if not valid_generation(generation):
+        return None
+    return environment_id, generation
+
+
+BAD_ATTACHMENT = {
+    "error": (
+        f"protocol_version must be {PROTOCOL_VERSION}, environment_id is required, and "
+        "attachment_generation must be a non-negative integer"
+    )
+}
+EXEC_SERVER_DOWN = {"error": "the exec-server did not start"}
+ATTACHMENT_TEXT_FIELDS = (
+    "environment_id",
+    "workspace_directory",
+    "endpoint",
+    "region",
+    "service",
+)
+
+
+def valid_attachment(attachment: Any) -> bool:
+    """Returns whether an attachment from activate or state.json can start the exec-server."""
+    if not isinstance(attachment, dict):
+        return False
+    if not valid_generation(attachment.get("attachment_generation")):
+        return False
+    return all(
+        isinstance(attachment.get(field), str)
+        and attachment[field]
+        and "\\0" not in attachment[field]
+        for field in ATTACHMENT_TEXT_FIELDS
+    )
+
+
+class Lifecycle:
+    """Keeps the attachment, the exec-server, the collector, and the turn leases."""
+
+    def __init__(self) -> None:
+        self.lock = threading.Lock()
+        self.runtime_session_id: str | None = None
+        self.state_loaded = False
+        self.attachment: dict[str, Any] | None = None
+        self.process: subprocess.Popen[str] | None = None
+        self.collector: subprocess.Popen[bytes] | None = None
+        self.leases: dict[str, float] = {}
+
+    def load_state(self, runtime_session_id: str | None) -> None:
+        """Starts the exec-server for the saved attachment on the first invocation."""
+        with self.lock:
+            if runtime_session_id:
+                self.runtime_session_id = runtime_session_id
+            if self.state_loaded:
+                return
+            self.state_loaded = True
+            with step_span("bma.state_load") as span:
+                try:
+                    saved = json.loads(
+                        (state_dir() / "state.json").read_text(encoding="utf-8")
+                    )
+                except FileNotFoundError:
+                    span.set_attribute("bma.state.found", False)
+                    return
+                except (OSError, ValueError) as error:
+                    failed(span, "state_load_failed", error)
+                    return
+                span.set_attribute("bma.state.found", True)
+                attachment = (
+                    saved.get("attachment") if isinstance(saved, dict) else None
+                )
+                if valid_attachment(attachment):
+                    self.attachment = attachment
+                    log("state_loaded", **attachment)
+                    self._ensure_running_locked("state_loaded")
+                elif attachment is not None:
+                    failed(
+                        span, "state_load_failed", "state.json has a wrong attachment"
+                    )
+
+    def _save_locked(self) -> None:
+        with step_span("bma.state_save") as span:
+            try:
+                directory = state_dir()
+                temporary = directory / "state.json.tmp"
+                temporary.write_text(
+                    json.dumps({"attachment": self.attachment}), encoding="utf-8"
+                )
+                temporary.replace(directory / "state.json")
+            except OSError as error:
+                failed(span, "state_save_failed", error)
+
+    def activate(self, request: dict[str, Any]) -> tuple[HTTPStatus, dict[str, Any]]:
+        parsed = parse_attachment(request)
+        if parsed is None:
+            return HTTPStatus.BAD_REQUEST, BAD_ATTACHMENT
+        workspace = request.get("workspace")
+        directory = workspace.get("directory") if isinstance(workspace, dict) else None
+        if not isinstance(directory, str) or not Path(directory).is_absolute():
+            return HTTPStatus.BAD_REQUEST, {
+                "error": "workspace.directory must be an absolute path"
+            }
+        with step_span(
+            "bma.workspace_check", **{"bma.workspace.directory": directory}
+        ) as span:
+            try:
+                Path(directory).mkdir(parents=True, exist_ok=True)
+            except OSError as error:
+                failed(span, "workspace_unavailable", error, directory=directory)
+                return HTTPStatus.SERVICE_UNAVAILABLE, {
+                    "error": f"cannot create workspace.directory: {error}"
+                }
+        environment_id, generation = parsed
+        region = request.get("region") or AWS_REGION
+        attachment = {
+            "environment_id": environment_id,
+            "attachment_generation": generation,
+            "workspace_directory": directory,
+            "endpoint": request.get("endpoint")
+            or f"https://{BMA_REMOTE_SERVICE}.{region}.api.aws",
+            "region": region,
+            "service": request.get("service") or BMA_REMOTE_SERVICE,
+        }
+        if not valid_attachment(attachment):
+            return HTTPStatus.BAD_REQUEST, {
+                "error": "workspace.directory, endpoint, region, and service must be strings"
+            }
+
+        with self.lock:
+            current_id, current_generation = self._key()
+            if current_id == environment_id and generation < current_generation:
+                return self._conflict("stale attachment generation")
+            same = (current_id, current_generation) == parsed
+            if not (same and self._running()):
+                self._stop_locked("activate")
+                if not same:
+                    self.leases.clear()
+                self.attachment = attachment
+                self._save_locked()
+            if not self._ensure_running_locked("activate"):
+                return HTTPStatus.SERVICE_UNAVAILABLE, EXEC_SERVER_DOWN
+
+        return HTTPStatus.OK, {
+            "protocol_version": PROTOCOL_VERSION,
+            "environment_id": environment_id,
+            "attachment_generation": generation,
+            "workspace": "ready",
+            "exec_server": "connecting",
+            "runtime_session_id": self.runtime_session_id,
+        }
+
+    def disconnect(self) -> tuple[HTTPStatus, dict[str, Any]]:
+        with self.lock:
+            self._stop_locked("disconnect")
+            self.attachment = None
+            self.leases.clear()
+            self._save_locked()
+        return HTTPStatus.OK, {
+            "protocol_version": PROTOCOL_VERSION,
+            "exec_server": "stopped",
+        }
+
+    def renew_turn_lease(
+        self, request: dict[str, Any]
+    ) -> tuple[HTTPStatus, dict[str, Any]]:
+        turn_id = request.get("turn_id")
+        duration = request.get("lease_duration_seconds")
+        if (
+            not isinstance(turn_id, str)
+            or not turn_id
+            or type(duration) is not int
+            or duration < 1
+        ):
+            return HTTPStatus.BAD_REQUEST, {
+                "error": "turn_id and a positive integer lease_duration_seconds are required"
+            }
+        accepted = min(duration, BMA_MAX_TURN_LEASE)
+        with self.lock:
+            if error := self._check_lease_locked(request):
+                return error
+            if not self._ensure_running_locked("renew_turn_lease"):
+                return HTTPStatus.SERVICE_UNAVAILABLE, EXEC_SERVER_DOWN
+            deadline = time.monotonic() + accepted
+            self.leases[turn_id] = max(self.leases.get(turn_id, deadline), deadline)
+            body = self._lease_body(turn_id, lease_duration_seconds=accepted)
+        log(
+            "turn_lease_renewed",
+            turnId=turn_id,
+            leaseDurationSeconds=accepted,
+            activeLeases=body["active_lease_count"],
+        )
+        return HTTPStatus.OK, body
+
+    def release_turn_lease(
+        self, request: dict[str, Any]
+    ) -> tuple[HTTPStatus, dict[str, Any]]:
+        turn_id = request.get("turn_id")
+        if not isinstance(turn_id, str) or not turn_id:
+            return HTTPStatus.BAD_REQUEST, {"error": "turn_id is required"}
+        with self.lock:
+            if error := self._check_lease_locked(request):
+                return error
+            released = self.leases.pop(turn_id, None) is not None
+            body = self._lease_body(turn_id, released=released)
+        log(
+            "turn_lease_released",
+            turnId=turn_id,
+            released=released,
+            activeLeases=body["active_lease_count"],
+        )
+        return HTTPStatus.OK, body
+
+    def _lease_body(self, turn_id: str, **fields: Any) -> dict[str, Any]:
+        environment_id, generation = self._key()
+        return {
+            "protocol_version": PROTOCOL_VERSION,
+            "environment_id": environment_id,
+            "attachment_generation": generation,
+            "turn_id": turn_id,
+            **fields,
+            "active_lease_count": len(self.leases),
+        }
+
+    def _check_lease_locked(
+        self, request: dict[str, Any]
+    ) -> tuple[HTTPStatus, dict[str, Any]] | None:
+        parsed = parse_attachment(request)
+        if parsed is None:
+            return HTTPStatus.BAD_REQUEST, BAD_ATTACHMENT
+        with step_span("bma.attachment_check") as span:
+            matched = self._key() == parsed
+            span.set_attribute("bma.attachment.matched", matched)
+            if not matched:
+                return self._conflict("turn lease does not match the active attachment")
+        self._prune_locked()
+        return None
+
+    def _conflict(self, message: str) -> tuple[HTTPStatus, dict[str, Any]]:
+        environment_id, generation = self._key()
+        return HTTPStatus.CONFLICT, {
+            "error": message,
+            "environment_id": environment_id,
+            "attachment_generation": generation,
+        }
+
+    def _key(self) -> tuple[str | None, int | None]:
+        """Returns the environment ID and the generation of the attachment."""
+        attachment = self.attachment or {}
+        return attachment.get("environment_id"), attachment.get("attachment_generation")
+
+    def _prune_locked(self) -> None:
+        cutoff = time.monotonic()
+        self.leases = {turn: end for turn, end in self.leases.items() if end > cutoff}
+
+    def health(self) -> str:
+        """Does not take the lock, so an exec-server stop does not delay /ping."""
+        cutoff = time.monotonic()
+        busy = any(end > cutoff for end in self.leases.copy().values())
+        return "HealthyBusy" if busy else "Healthy"
+
+    def status(self) -> dict[str, Any]:
+        with self.lock:
+            self._prune_locked()
+            return {
+                "service": f"{BMA_NAME}/{BMA_VERSION}",
+                "runtimeSessionId": self.runtime_session_id,
+                "attachment": self.attachment,
+                "execServerRunning": self._running(),
+                "activeLeaseCount": len(self.leases),
+            }
+
+    def _running(self) -> bool:
+        return self.process is not None and self.process.poll() is None
+
+    def _ensure_running_locked(self, reason: str) -> bool:
+        """Starts the exec-server for the attachment if it does not run. Returns whether it runs."""
+        attachment = self.attachment
+        if attachment is None:
+            return False
+        if self._running():
+            return True
+        with step_span("bma.exec_server_start", **{"bma.reason": reason}) as span:
+            command = [
+                str(BMA_CODEX_BINARY),
+                *(TELEMETRY_OVERRIDES if self._ensure_collector_locked() else []),
+                "exec-server",
+                "--remote",
+                f"{attachment['endpoint'].rstrip('/')}/v1",
+                "--environment-id",
+                attachment["environment_id"],
+                "--remote-transport",
+                "direct",
+                "--aws-sigv4",
+                "--aws-service",
+                attachment["service"],
+                "--aws-region",
+                attachment["region"],
+            ]
+            try:
+                workspace = Path(attachment["workspace_directory"])
+                workspace.mkdir(parents=True, exist_ok=True)
+                BMA_HOME_DIR.mkdir(parents=True, exist_ok=True)
+                BMA_CODEX_HOME.mkdir(parents=True, exist_ok=True)
+                log(
+                    "exec_server_start",
+                    reason=reason,
+                    command=shlex.join(command),
+                    cwd=str(workspace),
+                    **attachment,
+                )
+                self.process = subprocess.Popen(
+                    command,
+                    cwd=workspace,
+                    env={**os.environ, **EXEC_SERVER_ENVIRONMENT},
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    text=True,
+                    bufsize=1,
+                    start_new_session=True,
+                )
+            except (OSError, ValueError) as error:
+                self.process = None
+                failed(span, "exec_server_start_failed", error)
+                return False
+            span.set_attribute("process.pid", self.process.pid)
+        threading.Thread(target=self._drain, args=(self.process,), daemon=True).start()
+        return True
+
+    def _ensure_collector_locked(self) -> bool:
+        """Starts the collector if it does not run. Returns whether it gets the Codex spans and logs."""
+        if not OBSERVABILITY_ENABLED or not self.runtime_session_id:
+            return False
+        if self.collector is not None and self.collector.poll() is None:
+            return True
+        environment = {
+            **os.environ,
+            "AGENTCORE_RUNTIME_SID": self.runtime_session_id,
+        }
+        with step_span("bma.collector_start") as span:
+            try:
+                self.collector = subprocess.Popen(COLLECTOR_COMMAND, env=environment)
+            except OSError as error:
+                failed(span, "collector_start_failed", error)
+                return False
+            span.set_attribute("process.pid", self.collector.pid)
+        log("collector_start", pid=self.collector.pid)
+        return True
+
+    def _stop_locked(self, reason: str) -> None:
+        process, self.process = self.process, None
+        if process is None or process.poll() is not None:
+            return
+        log("exec_server_stop", reason=reason, pid=process.pid)
+        with step_span(
+            "bma.exec_server_stop", **{"bma.reason": reason, "process.pid": process.pid}
+        ) as span:
+            process.terminate()
+            try:
+                process.wait(timeout=STOP_GRACE_SECONDS)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+                span.set_attribute("bma.killed", True)
+
+    @staticmethod
+    def _drain(process: subprocess.Popen[str]) -> None:
+        for line in process.stdout or []:
+            log("exec_server_output", line=line.rstrip("\\n"))
+        log("exec_server_exited", returnCode=process.wait())
+
+    def monitor(self) -> None:
+        """Starts the exec-server again if it stops while an attachment is active."""
+        while True:
+            time.sleep(RESTART_DELAY_SECONDS)
+            with self.lock:
+                self._ensure_running_locked("monitor")
+
+    def shutdown(self) -> None:
+        with self.lock:
+            self._stop_locked("shutdown")
+            if self.collector is not None:
+                self.collector.terminate()
+
+    def dispatch(
+        self, action: str, request: dict[str, Any]
+    ) -> tuple[HTTPStatus, dict[str, Any]]:
+        handlers = {
+            "activate": self.activate,
+            "renew_turn_lease": self.renew_turn_lease,
+            "release_turn_lease": self.release_turn_lease,
+            "disconnect": lambda _: self.disconnect(),
+            "status": lambda _: (HTTPStatus.OK, self.status()),
+        }
+        if action not in handlers:
+            return HTTPStatus.BAD_REQUEST, {"error": f"unknown action: {action}"}
+        return handlers[action](request)
+
+
+LIFECYCLE = Lifecycle()
+
+
+class Handler(BaseHTTPRequestHandler):
+    server_version = f"{BMA_NAME}/{BMA_VERSION}"
+    protocol_version = "HTTP/1.1"
+
+    def send_json(self, status: HTTPStatus, body: dict[str, Any]) -> None:
+        """Sends HTTP 200, because the Runtime drops the body of any other status."""
+        if status != HTTPStatus.OK:
+            body = {**body, "status_code": int(status)}
+        encoded = json.dumps(body).encode("utf-8")
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def read_body(self) -> bytes:
+        """Reads the request body, with Content-Length or chunked transfer encoding."""
+        if "chunked" not in self.headers.get("Transfer-Encoding", "").lower():
+            length = int(self.headers.get("Content-Length") or 0)
+            return self.rfile.read(length) if length > 0 else b""
+        chunks = []
+        while size := int(self.rfile.readline().split(b";")[0], 16):
+            chunks.append(self.rfile.read(size))
+            self.rfile.readline()
+        # Read the trailer section to the empty line that ends the request.
+        while self.rfile.readline().strip():
+            pass
+        return b"".join(chunks)
+
+    def do_GET(self) -> None:
+        if self.path == "/ping":
+            self.send_json(HTTPStatus.OK, {"status": LIFECYCLE.health()})
+        else:
+            self.send_json(HTTPStatus.NOT_FOUND, {"error": "route not found"})
+
+    def do_POST(self) -> None:
+        if self.path != "/invocations":
+            self.close_connection = True
+            self.send_json(HTTPStatus.NOT_FOUND, {"error": "route not found"})
+            return
+        try:
+            body = self.read_body()
+            request = json.loads(body) if body else {}
+        except ValueError:
+            request = None
+        if not isinstance(request, dict):
+            self.close_connection = True
+            self.send_json(
+                HTTPStatus.BAD_REQUEST, {"error": "request body must be a JSON object"}
+            )
+            return
+        runtime_session_id = self.headers.get(
+            "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id"
+        )
+        action = str(request.get("action", "status"))
+        with TRACER.start_as_current_span(
+            "bma.invocation",
+            context=propagate.extract(self.headers),
+            kind=trace.SpanKind.SERVER,
+            attributes={"bma.action": action},
+        ) as span:
+            if runtime_session_id:
+                span.set_attribute("session.id", runtime_session_id)
+            try:
+                LIFECYCLE.load_state(runtime_session_id)
+                status, body = LIFECYCLE.dispatch(action, request)
+            except Exception as error:
+                log("dispatch_failed", action=action, error=str(error))
+                span.record_exception(error)
+                status, body = (
+                    HTTPStatus.INTERNAL_SERVER_ERROR,
+                    {"error": "internal error"},
+                )
+            span.set_attribute("http.response.status_code", int(status))
+            if status >= HTTPStatus.INTERNAL_SERVER_ERROR:
+                span.set_status(trace.StatusCode.ERROR)
+        self.send_json(status, body)
+
+    def log_message(self, message_format: str, *args: Any) -> None:
+        if getattr(self, "path", None) == "/ping":
+            return
+        log("http", client=self.client_address[0], request=message_format % args)
+
+
+def serve() -> None:
+    def handle(signal_number: int, _frame: Any) -> None:
+        log("signal", signal=signal_number)
+        LIFECYCLE.shutdown()
+        raise SystemExit(0)
+
+    signal.signal(signal.SIGTERM, handle)
+    signal.signal(signal.SIGINT, handle)
+    threading.Thread(target=LIFECYCLE.monitor, daemon=True).start()
+    log("server_ready", port=8080, stateDir=str(BMA_STATE_DIR))
+    ThreadingHTTPServer(("0.0.0.0", 8080), Handler).serve_forever()
+
+
+if __name__ == "__main__":
+    serve()
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/otel/collector.yaml should match snapshot 1`] = `
+"# The CloudWatch agent runs this OpenTelemetry Collector configuration. It receives OTLP from
+# the exec-server, puts the runtime session ID on each span and log, and signs each request
+# with the ACR role. The exec-server sends the log group headers that the Runtime sets in
+# OTEL_EXPORTER_OTLP_TRACES_HEADERS and OTEL_EXPORTER_OTLP_LOGS_HEADERS, and the collector
+# sends them on to X-Ray and CloudWatch Logs.
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 127.0.0.1:4318
+        include_metadata: true
+processors:
+  attributes:
+    actions:
+      - key: session.id
+        value: \${env:AGENTCORE_RUNTIME_SID}
+        action: upsert
+exporters:
+  otlphttp/traces:
+    traces_endpoint: https://xray.\${env:AWS_REGION}.amazonaws.com/v1/traces
+    auth:
+      authenticator: headers_setter/traces
+  otlphttp/logs:
+    logs_endpoint: https://logs.\${env:AWS_REGION}.amazonaws.com/v1/logs
+    auth:
+      authenticator: headers_setter/logs
+extensions:
+  sigv4auth/xray:
+    region: \${env:AWS_REGION}
+    service: xray
+  sigv4auth/logs:
+    region: \${env:AWS_REGION}
+    service: logs
+  headers_setter/traces:
+    additional_auth: sigv4auth/xray
+    headers:
+      - key: x-aws-log-group
+        from_context: x-aws-log-group
+        action: upsert
+      - key: x-aws-log-stream
+        from_context: x-aws-log-stream
+        action: upsert
+  headers_setter/logs:
+    additional_auth: sigv4auth/logs
+    headers:
+      - key: x-aws-log-group
+        from_context: x-aws-log-group
+        action: upsert
+      - key: x-aws-log-stream
+        from_context: x-aws-log-stream
+        action: upsert
+      - key: x-aws-metric-namespace
+        from_context: x-aws-metric-namespace
+        action: upsert
+service:
+  extensions:
+    - sigv4auth/xray
+    - sigv4auth/logs
+    - headers_setter/traces
+    - headers_setter/logs
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [attributes]
+      exporters: [otlphttp/traces]
+    logs:
+      receivers: [otlp]
+      processors: [attributes]
+      exporters: [otlphttp/logs]
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/plugins/acr-report/.codex-plugin/plugin.json should match snapshot 1`] = `
+"{
+  "name": "acr-report",
+  "version": "0.1.0",
+  "description": "Report the Python version, user, and working directory of the ACR.",
+  "skills": "./skills/"
+}
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/plugins/acr-report/skills/acr-report/SKILL.md should match snapshot 1`] = `
+"---
+name: acr-report
+description: Save a report of the Python version, user ID, and working directory of the ACR in the workspace.
+---
+
+Run these commands in the workspace directory:
+
+- \`python3 --version\`
+- \`id -u\`
+- \`pwd\`
+
+Save the output as \`acr-report.txt\` in the workspace. The first line of the
+file is \`# ACR report\`, and each command and its output follow it. Read the
+file back and report its path.
+
+If a command fails, put its error in the report. Do not change the commands.
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/bma/base/pyproject.toml should match snapshot 1`] = `
+"[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "AgentCore Runtime environment for Bedrock Managed Agents"
+readme = "README.md"
+dependencies = [
+    "aws-opentelemetry-distro",
+    "bedrock-agentcore",
+]
+
+# The dependencies of client.py. The image build runs \`uv sync --no-dev\`.
+[dependency-groups]
+dev = [
+    "aws-bedrock-token-generator>=1.1.0",
+    "openai>=3.16.2",
+]
+
+[tool.uv]
+package = false
+"
+`;
+
 exports[`Assets Directory Snapshots > Python framework assets > python/python/http/googleadk/base/README.md should match snapshot 1`] = `
 "This is a project generated by the agentcore create CLI tool!