feat(dev): CodeZip dev runner and process lifecycle core

AGENTS.md

@@ -103,3 +103,7 @@ bun --hot ./index.ts
 ```
 
 For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
+
+## Error Handling
+
+If a validation error is needed (user-correctable input problem), use `ValidationError` directly. Do not create subclasses like `MissingCodeDirectoryError extends ValidationError` — just throw `new ValidationError("code directory not found: ...")` with a descriptive message.

src/assets/templates/hello-world-python-container/Dockerfile

@@ -0,0 +1,37 @@
+FROM public.ecr.aws/docker/library/python:3.12-slim-trixie
+
+RUN pip install --no-cache-dir uv
+
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+
+WORKDIR /app
+
+ENV UV_SYSTEM_PYTHON=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_NO_PROGRESS=1 \
+    PYTHONUNBUFFERED=1 \
+    DOCKER_CONTAINER=1 \
+    UV_DEFAULT_INDEX=${UV_DEFAULT_INDEX} \
+    UV_INDEX=${UV_INDEX} \
+    PATH="/app/.venv/bin:$PATH"
+
+RUN useradd -m -u 1000 bedrock_agentcore
+
+# Install dependencies first so code changes don't invalidate the layer.
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY --chown=bedrock_agentcore:bedrock_agentcore . .
+RUN uv sync --frozen --no-dev
+
+USER bedrock_agentcore
+
+# AgentCore Runtime service contract ports
+# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
+# 8080: HTTP Mode
+# 8000: MCP Mode
+# 9000: A2A Mode
+EXPOSE 8080 8000 9000
+
+CMD ["python", "-m", "main"]

src/assets/templates/hello-world-python-container/README.md

@@ -0,0 +1,27 @@
+# hello-world
+
+An AgentCore Runtime agent built with the [Strands](https://strandsagents.com)
+SDK. Scaffolded by `agentcore project create`.
+
+## Layout
+
+- `main.py` — the agent: a `BedrockAgentCoreApp` entrypoint that streams
+  responses from a Strands `Agent`.
+- `pyproject.toml` — dependencies, installed with [uv](https://docs.astral.sh/uv/).
+
+## Develop
+
+Run the agent locally from the project root:
+
+```bash
+agentcore project dev
+```
+
+Environment variables for local development go in `agentcore/.env.local`
+(gitignored).
+
+## Deploy
+
+```bash
+agentcore project deploy
+```

src/assets/templates/hello-world-python-container/dockerignore.template

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# IDE
+.vscode/
+.idea/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Secrets and environment files
+.env
+.env.*
+
+# Version control
+.git/
+
+# AgentCore build artifacts
+.agentcore/artifacts/
+*.zip

src/assets/templates/hello-world-python-container/main.py

@@ -0,0 +1,17 @@
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from strands import Agent
+
+app = BedrockAgentCoreApp()
+agent = Agent(system_prompt="You are a helpful assistant.")
+
+
+@app.entrypoint
+async def invoke(payload, context):
+    """Stream the agent's response to the caller's prompt."""
+    prompt = payload.get("prompt", "Hello!")
+    async for event in agent.stream_async(prompt):
+        yield event
+
+
+if __name__ == "__main__":
+    app.run()

src/assets/templates/hello-world-python-container/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hello-world"
+version = "0.1.0"
+description = "AgentCore Runtime application using the Strands SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "aws-opentelemetry-distro",
+    "bedrock-agentcore >= 1.9.1",
+    "botocore[crt] >= 1.35.0",
+    "strands-agents >= 1.15.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

src/assets/templates/hello-world-python/README.md

@@ -1,34 +1,24 @@
 # hello-world
 
-A minimal AgentCore Runtime agent built with the
-[Strands Agents SDK](https://strandsagents.com) — our recommended framework
-for building agents on AWS Bedrock AgentCore.
+An AgentCore Runtime agent built with the [Strands](https://strandsagents.com)
+SDK. Scaffolded by `agentcore project create`.
 
-## What's here
+## Layout
 
-- `main.py` — the agent. A `BedrockAgentCoreApp` wraps a Strands `Agent`;
-  the `@app.entrypoint` function receives each invocation payload and streams
-  the agent's response back to the caller.
-- `pyproject.toml` — Python dependencies, managed with
-  [uv](https://docs.astral.sh/uv/). `agentcore project create` has already run
-  `uv sync` for you (unless you passed `--skip-install`), so `.venv/` is ready.
+- `main.py` — the agent: a `BedrockAgentCoreApp` entrypoint that streams
+  responses from a Strands `Agent`.
+- `pyproject.toml` — dependencies, installed with [uv](https://docs.astral.sh/uv/).
 
-## Run it locally
+## Develop
 
-```bash
-uv run main.py
-```
-
-The app listens on http://localhost:8080. Invoke it:
+Run the agent locally from the project root:
 
 ```bash
-curl -X POST http://localhost:8080/invocations \
-  -H "Content-Type: application/json" \
-  -d '{"prompt": "Hello!"}'
+agentcore project dev
 ```
 
-<!-- TODO: replace the uv run + curl instructions with `agentcore dev` and
-     `agentcore invoke` once those commands are available. -->
+Environment variables for local development go in `agentcore/.env.local`
+(gitignored).
 
 ## Build your agent
 
@@ -56,5 +46,6 @@ for multi-agent patterns, MCP tools, and model configuration.
 
 ## Deploy
 
-Deploy from the project root with the AgentCore CLI; the CDK app under
-`agentcore/cdk` provisions the Runtime that hosts this agent.
+```bash
+agentcore project deploy
+```

src/assets/templates/shared/env.local.template

@@ -0,0 +1,7 @@
+# Environment variables for local development.
+# `agentcore dev` loads this file into your agent's process. Values here
+# override anything the CLI injects. This file is gitignored — keep secrets
+# out of version control, but they are safe here.
+#
+# Example:
+# MY_API_KEY=...

src/assets/templates/shared/gitignore.template

@@ -0,0 +1,17 @@
+# Local environment (loaded by `agentcore dev`; never commit secrets)
+.env.local
+.env*.local
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+
+# Node
+node_modules/
+
+# AgentCore CLI state
+agentcore/.cli/
+
+# CDK
+agentcore/cdk/cdk.out/