feat(templates): support Container builds in the strands-http-python template

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,

src/assets/templates/strands-http-python/Dockerfile.template

@@ -0,0 +1,39 @@
+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
+
+# opentelemetry-instrument (from aws-opentelemetry-distro) starts a real
+# TracerProvider; plain `python -m main` would export nothing.
+CMD ["opentelemetry-instrument", "python", "-m", "main"]

src/assets/templates/strands-http-python/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/core/project/manager.test.ts

@@ -6,12 +6,12 @@ import { DeserializationError, ProjectStateError } from "../../errors/errors";
 import type { AwsDeploymentTarget } from "../../projectSchemas/aws-targets";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { FsProjectManager } from "./manager";
-import {
- RUNTIME_TEMPLATE_SHORTCUTS,
-type CreateProjectInput,
-type DeployResult,
-type Project,
-type ProjectEvent,
+import { RUNTIME_TEMPLATE_SHORTCUTS } from "../../handlers/project/shortcuts";
+import type {
+ CreateProjectInput,
+ DeployResult,
+ Project,
+ ProjectEvent,
 } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 import type { DeployBackendInput, ProjectBackend } from "./backends/types";

src/core/project/templates/fsTree.test.ts

@@ -72,7 +72,11 @@ describe("FsTreeNode.fromAssetSource", () => {
  },
  };
 
- const tree = await FsTreeNode.fromAssetSource(source, "template", "root");
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { rootDirName: "root" },
+ );
 
  expect(tree.name).toBe("root");
  expect(tree.children.map((node) => node.name)).toEqual(["README.md", "src", ".gitignore"]);
@@ -83,4 +87,60 @@ describe("FsTreeNode.fromAssetSource", () => {
  ]);
  expect(await tree.children[2]?.bytes?.()).toBe("contents:template/gitignore.template");
  });
+
+ test("renames Dockerfile.template to Dockerfile", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/Dockerfile.template"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["Dockerfile"]);
+ });
+
+ test("filters on the rendered name and omits rejected subtrees", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts", "template/Dockerfile.template", "template/skip/ignored.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { filter: (name) => name !== "Dockerfile" && name !== "skip" },
+ );
+
+ expect(tree.children.map((node) => node.name)).toEqual(["main.ts"]);
+ });
+
+ test("applies transformContent lazily to file contents", async () => {
+ const source: AssetSource = {
+ async list() {
+ return ["template/main.ts"];
+ },
+ async read(assetPath) {
+ return `contents:${assetPath}`;
+ },
+ };
+
+ const tree = await FsTreeNode.fromAssetSource(
+ { assetSource: source },
+ { assetDir: "template" },
+ { transformContent: (raw) => raw.toUpperCase() },
+ );
+
+ expect(await tree.children[0]?.bytes?.()).toBe("CONTENTS:TEMPLATE/MAIN.TS");
+ });
 });

src/core/project/templates/fsTree.ts

@@ -71,18 +71,30 @@ export class FsTreeNode {
  }
 
  /**
- * Expands the flat asset listing under assetDir into a nested tree of nodes.
+ * Builds a file tree from assets under `input.assetDir`.
+ *
+ * @param config - Asset source configuration.
+ * @param input - Asset directory to load.
+ * @param options - Optional root name, lazy content transform, and descendant filter. Rejecting a directory omits its subtree.
  */
  static async fromAssetSource(
- src: AssetSource,
- assetDir: string,
- rootDirName?: string,
- transform?: (content: string) => string,
+ config: { assetSource: AssetSource },
+ input: { assetDir: string },
+ options?: {
+ rootDirName?: string;
+ transformContent?: (content: string) => string;
+ filter?: (name: string, isDir: boolean) => boolean;
+ },
  ): Promise<FsTreeNode> {
- const paths = await src.list(assetDir);
+ const { assetSource } = config;
+ const { assetDir } = input;
+ const rootDirName = options?.rootDirName;
+ const transformContent = options?.transformContent;
+ const filter = options?.filter;
+ const paths = await assetSource.list(assetDir);
  const root = FsTreeNode.createDirectory(rootDirName ?? assetDir, []);
 
- for (const assetPath of paths) {
+assetPaths: for (const assetPath of paths) {
  const relative = assetPath.slice(assetDir.length + 1);
  const segments = relative.split("/");
  if (segments.some((s) => s === "" || s === "." || s === "..")) {
@@ -92,35 +104,45 @@ export class FsTreeNode {
  }
 
  let parent = root;
- segments.forEach((segment, index) => {
- if (index === segments.length - 1) {
+ for (const [index, segment] of segments.entries()) {
+ const isDir = index < segments.length - 1;
+ const name = isDir ? segment : renderName(segment);
+ // if the segment of a path rejects, reject the rest of the path so we jump to top-loop via assetPaths label.
+ if (filter && !filter(name, isDir)) continue assetPaths;
+
+ if (!isDir) {
  parent.children.push(
- FsTreeNode.createFile(renderName(segment), async () => {
- const raw = await src.read(assetPath);
- return transform ? transform(raw) : raw;
+ FsTreeNode.createFile(name, async () => {
+ const raw = await assetSource.read(assetPath);
+ return transformContent ? transformContent(raw) : raw;
  }),
  );
-return;
+continue;
  }
 
- let child = parent.children.find((n): n is FsTreeNode => n.isDir && n.name === segment);
+ let child = parent.children.find(
+ (node): node is FsTreeNode => node.isDir && node.name === name,
+ );
  if (!child) {
- child = FsTreeNode.createDirectory(segment, []);
+ child = FsTreeNode.createDirectory(name, []);
  parent.children.push(child);
  }
-
  parent = child;
- });
+ }
  }
 
  return root;
  }
 }
 
 /**
- * Ignore templates are renamed to dotfiles because npm strips real dotfiles when publishing.
+ * Template assets carry a `.template` suffix so their real names survive publishing:
+ * npm strips leading dotfiles, and `bun build` appends a trailing dot to extensionless
+ * embedded assets (a bare `Dockerfile` embeds as `Dockerfile.`). The suffix is stripped here.
  */
 function renderName(filename: string): string {
  const ignore = filename.match(/^(git|npm|docker)ignore\.template$/);
- return ignore ? `.${ignore[1]}ignore` : filename;
+ if (ignore) return `.${ignore[1]}ignore`;
+ if (filename === "Dockerfile.template") return "Dockerfile";
+ return filename;
 }

src/core/project/templates/project.ts

@@ -35,7 +35,7 @@ export async function createProjectTree(
  config.assetSource.read("templates/shared/gitignore.template"),
  ),
  FsTreeNode.createDirectory("agentcore", [
- await FsTreeNode.fromAssetSource(config.assetSource, "cdk"),
+ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
  FsTreeNode.createFile("agentcore.json", async () =>
  json({
  name: input.projectName,

src/core/project/templates/runtime.ts

@@ -61,11 +61,14 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  if (input.protocol !== undefined && input.protocol !== "HTTP")
  throw new InputValidationError(`hello-world-python only supports HTTP protocol`);
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- input.scaffoldRuntimeInput.build === "Container"
- ? "templates/hello-world-python-container"
- : "templates/hello-world-python",
- input.name,
+ { assetSource },
+ {
+ assetDir:
+ input.scaffoldRuntimeInput.build === "Container"
+ ? "templates/hello-world-python-container"
+ : "templates/hello-world-python",
+ },
+ { rootDirName: input.name },
  );
  return { tree, spec: { runtimes: [buildRuntimeSpec(input)] } };
  },
@@ -104,11 +107,15 @@ const getTemplateResolvers = (assetSource: AssetSource, templateRenderer: Templa
  needsOs: filesystemConfigurations.length > 0,
  hasConfigBundle: false,
  };
+ const isContainer = input.scaffoldRuntimeInput.build === "Container";
  const tree = await FsTreeNode.fromAssetSource(
- assetSource,
- "templates/strands-http-python",
- input.name,
- (raw) => templateRenderer.render(raw, context),
+ { assetSource },
+ { assetDir: "templates/strands-http-python" },
+ {
+ rootDirName: input.name,
+ transformContent: (raw) => templateRenderer.render(raw, context),
+ filter: (name) => isContainer || (name !== "Dockerfile" && name !== ".dockerignore"),
+ },
  );
  return {
  tree,