@aws/nx-plugin 1.0.0-rc.8 → 1.0.0-rc.80

package/src/ts/agent/__snapshots__/generator.spec.ts.snap

@@ -1,13 +1,670 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`ts#agent generator > chat scripts for a2a protocol > should match snapshot for chat scripts with cognito auth > agentcore.ts (a2a, cognito) 1`] = `
+"// Resolves the deployed TestProjectAgent agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set, otherwise \`undefined\` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, { arn: string }> };
+  const arn = config?.agentRuntimes?.['TestProjectAgent']?.arn;
+  if (!arn) {
+    throw new Error(
+      \`No deployed agent named 'TestProjectAgent' found in runtime configuration (application \${application}).\`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+/** The Cognito access token used to authenticate with the deployed agent. */
+export const getAccessToken = (): string => {
+  const accessToken = process.env.AGENT_ACCESS_TOKEN;
+  if (!accessToken) {
+    throw new Error(
+      'AGENT_ACCESS_TOKEN is not set. Provide a Cognito access token to chat with the deployed agent.',
+    );
+  }
+  return accessToken;
+};
+
+// A \`fetch\` that authenticates requests to the deployed agent and forwards the session id.
+export const createAgentCoreFetch = (): typeof fetch => {
+  const accessToken = getAccessToken();
+  return (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    headers.set('Authorization', \`Bearer \${accessToken}\`);
+    return fetch(input, { ...init, headers });
+  };
+};
+"
+`;
+
+exports[`ts#agent generator > chat scripts for a2a protocol > should match snapshot for chat scripts with cognito auth > chat.ts (a2a, cognito) 1`] = `
+"// Chat CLI for TestProjectAgent (A2A protocol). Connects to the local
+// \`dev\` server, or the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set.
+import {
+  ClientFactory,
+  ClientFactoryOptions,
+  DefaultAgentCardResolver,
+  JsonRpcTransportFactory,
+} from '@a2a-js/sdk/client';
+import { A2AChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? \`https://bedrock-agentcore.\${remote.region}.amazonaws.com/runtimes/\${encodeURIComponent(remote.arn)}/invocations/\`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default client talks plain HTTP.
+const clientFactory = remote
+  ? new ClientFactory({
+      ...ClientFactoryOptions.default,
+      transports: [
+        new JsonRpcTransportFactory({
+          fetchImpl: createAgentCoreFetch(),
+        }),
+      ],
+      cardResolver: new DefaultAgentCardResolver({
+        fetchImpl: createAgentCoreFetch(),
+      }),
+    })
+  : undefined;
+
+await chatLoop(new A2AChatAdapter({ clientFactory }), url);
+"
+`;
+
+exports[`ts#agent generator > chat scripts for a2a protocol > should match snapshot for chat scripts with iam auth > agentcore.ts (a2a, iam) 1`] = `
+"// Resolves the deployed TestProjectAgent agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AwsClient } from 'aws4fetch';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set, otherwise \`undefined\` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, { arn: string }> };
+  const arn = config?.agentRuntimes?.['TestProjectAgent']?.arn;
+  if (!arn) {
+    throw new Error(
+      \`No deployed agent named 'TestProjectAgent' found in runtime configuration (application \${application}).\`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+// A \`fetch\` that authenticates requests to the deployed agent and forwards the session id.
+export const createAgentCoreFetch = (region: string): typeof fetch => {
+  const credentialProvider = fromNodeProviderChain();
+  return async (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    const client = new AwsClient({
+      ...(await credentialProvider()),
+      service: 'bedrock-agentcore',
+      region,
+    });
+    return client.fetch(input, { ...init, headers });
+  };
+};
+"
+`;
+
+exports[`ts#agent generator > chat scripts for a2a protocol > should match snapshot for chat scripts with iam auth > chat.ts (a2a, iam) 1`] = `
+"// Chat CLI for TestProjectAgent (A2A protocol). Connects to the local
+// \`dev\` server, or the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set.
+import {
+  ClientFactory,
+  ClientFactoryOptions,
+  DefaultAgentCardResolver,
+  JsonRpcTransportFactory,
+} from '@a2a-js/sdk/client';
+import { A2AChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? \`https://bedrock-agentcore.\${remote.region}.amazonaws.com/runtimes/\${encodeURIComponent(remote.arn)}/invocations/\`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default client talks plain HTTP.
+const clientFactory = remote
+  ? new ClientFactory({
+      ...ClientFactoryOptions.default,
+      transports: [
+        new JsonRpcTransportFactory({
+          fetchImpl: createAgentCoreFetch(remote.region),
+        }),
+      ],
+      cardResolver: new DefaultAgentCardResolver({
+        fetchImpl: createAgentCoreFetch(remote.region),
+      }),
+    })
+  : undefined;
+
+await chatLoop(new A2AChatAdapter({ clientFactory }), url);
+"
+`;
+
+exports[`ts#agent generator > chat scripts for ag-ui protocol > should match snapshot for chat scripts with cognito auth > agentcore.ts (ag-ui, cognito) 1`] = `
+"// Resolves the deployed TestProjectAgent agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set, otherwise \`undefined\` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, { arn: string }> };
+  const arn = config?.agentRuntimes?.['TestProjectAgent']?.arn;
+  if (!arn) {
+    throw new Error(
+      \`No deployed agent named 'TestProjectAgent' found in runtime configuration (application \${application}).\`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+/** The Cognito access token used to authenticate with the deployed agent. */
+export const getAccessToken = (): string => {
+  const accessToken = process.env.AGENT_ACCESS_TOKEN;
+  if (!accessToken) {
+    throw new Error(
+      'AGENT_ACCESS_TOKEN is not set. Provide a Cognito access token to chat with the deployed agent.',
+    );
+  }
+  return accessToken;
+};
+
+// A \`fetch\` that authenticates requests to the deployed agent and forwards the session id.
+export const createAgentCoreFetch = (): typeof fetch => {
+  const accessToken = getAccessToken();
+  return (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    headers.set('Authorization', \`Bearer \${accessToken}\`);
+    return fetch(input, { ...init, headers });
+  };
+};
+"
+`;
+
+exports[`ts#agent generator > chat scripts for ag-ui protocol > should match snapshot for chat scripts with cognito auth > chat.ts (ag-ui, cognito) 1`] = `
+"// Chat CLI for TestProjectAgent (AG-UI protocol). Connects to the local
+// \`dev\` server, or the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set.
+import { AGUIChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? \`https://bedrock-agentcore.\${remote.region}.amazonaws.com/runtimes/\${encodeURIComponent(remote.arn)}/invocations?qualifier=DEFAULT\`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default agent talks plain HTTP.
+const fetchImpl = remote ? createAgentCoreFetch() : undefined;
+
+await chatLoop(new AGUIChatAdapter({ fetch: fetchImpl }), url);
+"
+`;
+
+exports[`ts#agent generator > chat scripts for ag-ui protocol > should match snapshot for chat scripts with iam auth > agentcore.ts (ag-ui, iam) 1`] = `
+"// Resolves the deployed TestProjectAgent agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AwsClient } from 'aws4fetch';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set, otherwise \`undefined\` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, { arn: string }> };
+  const arn = config?.agentRuntimes?.['TestProjectAgent']?.arn;
+  if (!arn) {
+    throw new Error(
+      \`No deployed agent named 'TestProjectAgent' found in runtime configuration (application \${application}).\`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+// A \`fetch\` that authenticates requests to the deployed agent and forwards the session id.
+export const createAgentCoreFetch = (region: string): typeof fetch => {
+  const credentialProvider = fromNodeProviderChain();
+  return async (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    const client = new AwsClient({
+      ...(await credentialProvider()),
+      service: 'bedrock-agentcore',
+      region,
+    });
+    return client.fetch(input, { ...init, headers });
+  };
+};
+"
+`;
+
+exports[`ts#agent generator > chat scripts for ag-ui protocol > should match snapshot for chat scripts with iam auth > chat.ts (ag-ui, iam) 1`] = `
+"// Chat CLI for TestProjectAgent (AG-UI protocol). Connects to the local
+// \`dev\` server, or the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set.
+import { AGUIChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? \`https://bedrock-agentcore.\${remote.region}.amazonaws.com/runtimes/\${encodeURIComponent(remote.arn)}/invocations?qualifier=DEFAULT\`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default agent talks plain HTTP.
+const fetchImpl = remote ? createAgentCoreFetch(remote.region) : undefined;
+
+await chatLoop(new AGUIChatAdapter({ fetch: fetchImpl }), url);
+"
+`;
+
+exports[`ts#agent generator > chat scripts for http protocol > should match snapshot for chat scripts with cognito auth > agentcore.ts (http, cognito) 1`] = `
+"// Resolves the deployed TestProjectAgent agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set, otherwise \`undefined\` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, { arn: string }> };
+  const arn = config?.agentRuntimes?.['TestProjectAgent']?.arn;
+  if (!arn) {
+    throw new Error(
+      \`No deployed agent named 'TestProjectAgent' found in runtime configuration (application \${application}).\`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+/** The Cognito access token used to authenticate with the deployed agent. */
+export const getAccessToken = (): string => {
+  const accessToken = process.env.AGENT_ACCESS_TOKEN;
+  if (!accessToken) {
+    throw new Error(
+      'AGENT_ACCESS_TOKEN is not set. Provide a Cognito access token to chat with the deployed agent.',
+    );
+  }
+  return accessToken;
+};
+
+// A \`fetch\` that authenticates requests to the deployed agent and forwards the session id.
+export const createAgentCoreFetch = (): typeof fetch => {
+  const accessToken = getAccessToken();
+  return (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    headers.set('Authorization', \`Bearer \${accessToken}\`);
+    return fetch(input, { ...init, headers });
+  };
+};
+"
+`;
+
+exports[`ts#agent generator > chat scripts for http protocol > should match snapshot for chat scripts with cognito auth > chat.ts (http, cognito) 1`] = `
+"// Chat CLI for TestProjectAgent (HTTP / tRPC WebSocket). Connects to the local
+// \`dev\` server, or the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set.
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+import { TestProjectAgentClient } from '../../src/agent/client.js';
+import { resolveRemoteAgent, SESSION_ID, getAccessToken } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+class TrpcWebSocketAdapter implements ChatAdapter {
+  private client!: ReturnType<typeof TestProjectAgentClient.local>;
+
+  async connect(url: string) {
+    this.client = remote
+      ? TestProjectAgentClient.withJwtAuth({
+          agentRuntimeArn: remote.arn,
+          sessionId: SESSION_ID,
+          accessTokenProvider: async () => getAccessToken(),
+        })
+      : TestProjectAgentClient.local({ url, sessionId: SESSION_ID });
+    return { agentName: 'TestProjectAgent' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        this.client.invoke.subscribe(
+          { prompt: text },
+          {
+            onData: (chunk: string) => controller.enqueue(chunk),
+            onComplete: () => controller.close(),
+            onError: (err: unknown) => controller.error(err),
+          },
+        );
+      },
+    });
+
+    yield* stream as unknown as AsyncIterable<string>;
+  }
+}
+
+await chatLoop(new TrpcWebSocketAdapter(), process.env.URL ?? '');
+"
+`;
+
+exports[`ts#agent generator > chat scripts for http protocol > should match snapshot for chat scripts with iam auth > agentcore.ts (http, iam) 1`] = `
+"// Resolves the deployed TestProjectAgent agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AwsClient } from 'aws4fetch';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set, otherwise \`undefined\` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, { arn: string }> };
+  const arn = config?.agentRuntimes?.['TestProjectAgent']?.arn;
+  if (!arn) {
+    throw new Error(
+      \`No deployed agent named 'TestProjectAgent' found in runtime configuration (application \${application}).\`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+// A \`fetch\` that authenticates requests to the deployed agent and forwards the session id.
+export const createAgentCoreFetch = (region: string): typeof fetch => {
+  const credentialProvider = fromNodeProviderChain();
+  return async (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    const client = new AwsClient({
+      ...(await credentialProvider()),
+      service: 'bedrock-agentcore',
+      region,
+    });
+    return client.fetch(input, { ...init, headers });
+  };
+};
+"
+`;
+
+exports[`ts#agent generator > chat scripts for http protocol > should match snapshot for chat scripts with iam auth > chat.ts (http, iam) 1`] = `
+"// Chat CLI for TestProjectAgent (HTTP / tRPC WebSocket). Connects to the local
+// \`dev\` server, or the deployed agent when \`RUNTIME_CONFIG_APP_ID\` is set.
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+import { TestProjectAgentClient } from '../../src/agent/client.js';
+import { resolveRemoteAgent, SESSION_ID } from './agentcore.js';
+
+const remote = await resolveRemoteAgent();
+
+class TrpcWebSocketAdapter implements ChatAdapter {
+  private client!: ReturnType<typeof TestProjectAgentClient.local>;
+
+  async connect(url: string) {
+    this.client = remote
+      ? TestProjectAgentClient.withIamAuth({
+          agentRuntimeArn: remote.arn,
+          sessionId: SESSION_ID,
+        })
+      : TestProjectAgentClient.local({ url, sessionId: SESSION_ID });
+    return { agentName: 'TestProjectAgent' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        this.client.invoke.subscribe(
+          { prompt: text },
+          {
+            onData: (chunk: string) => controller.enqueue(chunk),
+            onComplete: () => controller.close(),
+            onError: (err: unknown) => controller.error(err),
+          },
+        );
+      },
+    });
+
+    yield* stream as unknown as AsyncIterable<string>;
+  }
+}
+
+await chatLoop(new TrpcWebSocketAdapter(), process.env.URL ?? '');
+"
+`;
+
+exports[`ts#agent generator > should generate session.ts using S3 storage by default > session.ts (s3) 1`] = `
+"import { SessionManager } from '@strands-agents/sdk';
+import { LocalFileStorage, S3Storage } from '@strands-agents/sdk/storage';
+import {
+  getCurrentSessionId,
+  getAgentCoreRuntimeConfig,
+} from '@proj/agent-connection';
+
+/**
+ * Returns a SessionManager for persisting conversation state across
+ * invocations. Local development always uses local file storage for
+ * convenience, regardless of the configured session option. Without a
+ * configured session option, conversation state is kept in memory only and
+ * does not survive process restarts.
+ */
+export const getSessionManager = async (): Promise<SessionManager> => {
+  const sessionId = getCurrentSessionId();
+  if (!sessionId) {
+    throw new Error(
+      'No current session id — cannot resolve a SessionManager outside of a request scope.',
+    );
+  }
+  if (process.env.LOCAL_DEV === 'true') {
+    return new SessionManager({
+      sessionId,
+      storage: new LocalFileStorage(
+        '../../tmp/agents/strands/test-project-agent',
+      ),
+    });
+  }
+  const config = await getAgentCoreRuntimeConfig();
+  const bucketName =
+    config.agentRuntimes?.['TestProjectAgent']?.session?.bucketName;
+  if (!bucketName) {
+    throw new Error(
+      "No S3 bucket configured for this agent's session in runtime configuration.",
+    );
+  }
+  return new SessionManager({ sessionId, storage: new S3Storage(bucketName) });
+};
+"
+`;
+
+exports[`ts#agent generator > should generate session.ts using in-memory storage when session is in-memory > session.ts (in-memory) 1`] = `
+"import { SessionManager } from '@strands-agents/sdk';
+import { LocalFileStorage, InMemoryStorage } from '@strands-agents/sdk/storage';
+import { getCurrentSessionId } from '@proj/agent-connection';
+
+/**
+ * Returns a SessionManager for persisting conversation state across
+ * invocations. Local development always uses local file storage for
+ * convenience, regardless of the configured session option. Without a
+ * configured session option, conversation state is kept in memory only and
+ * does not survive process restarts.
+ */
+export const getSessionManager = async (): Promise<SessionManager> => {
+  const sessionId = getCurrentSessionId();
+  if (!sessionId) {
+    throw new Error(
+      'No current session id — cannot resolve a SessionManager outside of a request scope.',
+    );
+  }
+  if (process.env.LOCAL_DEV === 'true') {
+    return new SessionManager({
+      sessionId,
+      storage: new LocalFileStorage(
+        '../../tmp/agents/strands/test-project-agent',
+      ),
+    });
+  }
+  return new SessionManager({ sessionId, storage: new InMemoryStorage() });
+};
+"
+`;
+
 exports[`ts#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > agent-Dockerfile 1`] = `
-"FROM public.ecr.aws/docker/library/node:lts-jod
+"FROM public.ecr.aws/docker/library/node:lts-slim
+
+# Apply the distribution's security updates: base image tags lag behind the
+# security suite, so its OS packages carry fixed HIGH/CRITICAL vulnerabilities
+# flagged by the image scan.
+RUN apt-get update && \\
+    apt-get upgrade -y --no-install-recommends && \\
+    rm -rf /var/lib/apt/lists/*
+
+# Upgrade npm to a version free of known HIGH/CRITICAL vulnerabilities
+RUN npm install -g npm@12.0.2
 
 WORKDIR /app
 
 # Add AWS Distro for OpenTelemetry for observability
 # https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html
-RUN npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation@0.11.0
+# The overrides pin transitive dependencies with known HIGH/CRITICAL
+# vulnerabilities to fixed versions. npm is removed once the install is done —
+# the runtime only needs node, and npm's own bundled dependencies would
+# otherwise carry vulnerabilities into the image.
+RUN npm init -y \\
+  && npm pkg set "overrides.@opentelemetry/propagator-jaeger=2.10.0" \\
+  && npm pkg set "overrides.minimatch=10.2.6" \\
+  && npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation@0.12.0 \\
+  && npm uninstall -g npm
 
 # Copy bundled agent
 COPY index.js /app
@@ -21,9 +678,22 @@ CMD [ "node", "--require", "@aws/aws-distro-opentelemetry-node-autoinstrumentati
 `;
 
 exports[`ts#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > agent-construct.ts 1`] = `
-"import { Lazy, Names } from 'aws-cdk-lib';
+"import { Fn, Lazy, Names, RemovalPolicy, Stack } from 'aws-cdk-lib';
 import { Platform } from 'aws-cdk-lib/aws-ecr-assets';
 import { Connections, IConnectable } from 'aws-cdk-lib/aws-ec2';
+import {
+  BlockPublicAccess,
+  Bucket,
+  BucketEncryption,
+} from 'aws-cdk-lib/aws-s3';
+import { Key } from 'aws-cdk-lib/aws-kms';
+import {
+  CfnDelivery,
+  CfnDeliveryDestination,
+  CfnDeliverySource,
+  LogGroup,
+  RetentionDays,
+} from 'aws-cdk-lib/aws-logs';
 import { Construct } from 'constructs';
 import * as path from 'path';
 import * as url from 'url';
@@ -35,10 +705,13 @@ import {
 } from 'aws-cdk-lib/aws-bedrockagentcore';
 import {
   PolicyStatement,
+  Effect,
+  ServicePrincipal,
   IGrantable,
   IPrincipal,
   Grant,
 } from 'aws-cdk-lib/aws-iam';
+import { suppressRules } from '../../../core/checkov.js';
 import { RuntimeConfig } from '../../../core/runtime-config.js';
 import { findWorkspaceRoot } from '../../../core/workspace.js';
 
@@ -48,7 +721,16 @@ export type SnapshotBedrockAgentProps = Omit<
   | 'protocolConfiguration'
   | 'agentRuntimeArtifact'
   | 'authorizerConfiguration'
->;
+> & {
+  /**
+   * Removal policy for the session bucket holding the agent's conversation
+   * history. Defaults to retaining it so a stack \`destroy\` doesn't silently
+   * delete session data — set to \`RemovalPolicy.DESTROY\` for sandbox/CI teardown.
+   *
+   * @default RemovalPolicy.RETAIN
+   */
+  readonly sessionBucketRemovalPolicy?: RemovalPolicy;
+};
 
 export class SnapshotBedrockAgent
   extends Construct
@@ -56,6 +738,10 @@ export class SnapshotBedrockAgent
 {
   public readonly dockerImage: AgentRuntimeArtifact;
   public readonly agentCoreRuntime: Runtime;
+  /** Default Gateway target name for this agent. */
+  public readonly agentName = 'snapshot-bedrock-agent';
+  /** Inbound auth — a fronting Gateway uses this to pick its outbound credential. */
+  public readonly auth = 'iam';
 
   constructor(scope: Construct, id: string, props?: SnapshotBedrockAgentProps) {
     super(scope, id);
@@ -72,6 +758,114 @@ export class SnapshotBedrockAgent
       platform: Platform.LINUX_ARM64,
     });
 
+    const { sessionBucketRemovalPolicy = RemovalPolicy.RETAIN, ...restProps } =
+      props ?? {};
+
+    const sessionKey = new Key(this, 'SessionKey', {
+      enableKeyRotation: true,
+    });
+
+    // Allow CloudWatch Logs to use the session key for server access log delivery.
+    const stack = Stack.of(this);
+    sessionKey.addToResourcePolicy(
+      new PolicyStatement({
+        effect: Effect.ALLOW,
+        principals: [
+          new ServicePrincipal(\`logs.\${stack.region}.amazonaws.com\`),
+        ],
+        actions: [
+          'kms:Encrypt',
+          'kms:Decrypt',
+          'kms:ReEncrypt*',
+          'kms:GenerateDataKey*',
+          'kms:DescribeKey',
+        ],
+        resources: ['*'],
+        conditions: {
+          ArnLike: {
+            'kms:EncryptionContext:aws:logs:arn': \`arn:aws:logs:\${stack.region}:\${stack.account}:log-group:*\`,
+          },
+        },
+      }),
+    );
+
+    const sessionAccessLogs = new LogGroup(this, 'SessionAccessLogs', {
+      retention: RetentionDays.ONE_YEAR,
+      encryptionKey: sessionKey,
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+
+    const sessionBucket = new Bucket(this, 'SessionBucket', {
+      enforceSSL: true,
+      removalPolicy: sessionBucketRemovalPolicy,
+      encryption: BucketEncryption.KMS,
+      encryptionKey: sessionKey,
+      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
+    });
+    suppressRules(
+      sessionBucket,
+      ['CKV_AWS_21'],
+      'Session data does not need versioning enabled',
+    );
+    suppressRules(
+      sessionBucket,
+      ['CKV2_AWS_61'],
+      'Lifecycle configuration not required for session data',
+    );
+    suppressRules(
+      sessionBucket,
+      ['CKV_AWS_144'],
+      'Cross-region replication not required for session data',
+    );
+    suppressRules(
+      sessionBucket,
+      ['CKV2_AWS_62'],
+      'Event notifications not required for session data',
+    );
+    suppressRules(
+      sessionBucket,
+      ['CKV_AWS_18'],
+      'Server access logs are delivered to CloudWatch Logs',
+    );
+
+    const sessionAccessLogsSource: CfnDeliverySource = new CfnDeliverySource(
+      this,
+      'SessionAccessLogsSource',
+      {
+        name: Lazy.string({
+          produce: () =>
+            Names.uniqueResourceName(sessionAccessLogsSource, {
+              maxLength: 60,
+            }),
+        }),
+        logType: 'S3_SERVER_ACCESS_LOGS',
+        resourceArn: sessionBucket.bucketArn,
+      },
+    );
+    const sessionBucketPolicy = sessionBucket.policy;
+    if (sessionBucketPolicy) {
+      sessionAccessLogsSource.node.addDependency(sessionBucketPolicy);
+    }
+    const sessionAccessLogsDestination: CfnDeliveryDestination =
+      new CfnDeliveryDestination(this, 'SessionAccessLogsDestination', {
+        name: Lazy.string({
+          produce: () =>
+            Names.uniqueResourceName(sessionAccessLogsDestination, {
+              maxLength: 60,
+            }),
+        }),
+        destinationResourceArn: sessionAccessLogs.logGroupArn,
+      });
+    const sessionAccessLogsDelivery = new CfnDelivery(
+      this,
+      'SessionAccessLogsDelivery',
+      {
+        deliverySourceName: sessionAccessLogsSource.name,
+        deliveryDestinationArn: sessionAccessLogsDestination.attrArn,
+      },
+    );
+    sessionAccessLogsDelivery.addDependency(sessionAccessLogsSource);
+
     this.agentCoreRuntime = new Runtime(this, 'SnapshotBedrockAgent', {
       runtimeName: Lazy.string({
         produce: () =>
@@ -79,10 +873,10 @@ export class SnapshotBedrockAgent
       }),
       protocolConfiguration: ProtocolType.HTTP,
       agentRuntimeArtifact: this.dockerImage,
-      ...props,
+      ...restProps,
       environmentVariables: {
         RUNTIME_CONFIG_APP_ID: rc.appConfigApplicationId,
-        ...props?.environmentVariables,
+        ...restProps?.environmentVariables,
       },
     });
 
@@ -100,11 +894,18 @@ export class SnapshotBedrockAgent
       }),
     );
 
+    sessionBucket.grantReadWrite(this.agentCoreRuntime);
+
     rc.grantReadAppConfig(this.agentCoreRuntime);
 
     rc.set('agentcore', 'agentRuntimes', {
       ...rc.get('agentcore').agentRuntimes,
-      SnapshotBedrockAgent: this.agentCoreRuntime.agentRuntimeArn,
+      SnapshotBedrockAgent: {
+        arn: this.agentCoreRuntime.agentRuntimeArn,
+        session: {
+          bucketName: sessionBucket.bucketName,
+        },
+      },
     });
   }
 
@@ -122,6 +923,22 @@ export class SnapshotBedrockAgent
     return this.agentCoreRuntime.connections;
   }
 
+  /**
+   * The HTTPS invocation URL of the runtime.
+   */
+  public get invocationUrl(): string {
+    // The URL must URL-encode the runtime ARN (':' -> '%3A', '/' -> '%2F').
+    // The ARN is a CDK token, so encode at deploy time via Fn.join/Fn.split.
+    const encodedArn = Fn.join(
+      '%2F',
+      Fn.split(
+        '/',
+        Fn.join('%3A', Fn.split(':', this.agentCoreRuntime.agentRuntimeArn)),
+      ),
+    );
+    return \`https://bedrock-agentcore.\${Stack.of(this).region}.amazonaws.com/runtimes/\${encodedArn}/invocations?qualifier=DEFAULT\`;
+  }
+
   /**
    * Grants IAM permissions to invoke this agent runtime.
    *
@@ -156,13 +973,23 @@ exports[`ts#agent generator > should match snapshot for BedrockAgentCoreRuntime
 exports[`ts#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > core-index.ts 1`] = `
 "export * from './app.js';
 export * from './checkov.js';
+export * from './cloudfront.js';
 export * from './runtime-config.js';
 export * from './workspace.js';
 "
 `;
 
 exports[`ts#agent generator > should match snapshot for Terraform generated files > terraform-agent.tf 1`] = `
-"variable "env" {
+"terraform {
+  required_providers {
+    random = {
+      source  = "hashicorp/random"
+      version = "3.9.0"
+    }
+  }
+}
+
+variable "env" {
   description = "Environment variables to pass to the agent core runtime"
   type        = map(string)
   default     = {}
@@ -184,21 +1011,189 @@ variable "tags" {
   default     = {}
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "appconfig_application_id" {
   description = "ID of the shared runtime-config AppConfig application (from \`core/runtime-config/appconfig.application_id\`). The agent reads its runtime configuration from this application."
   type        = string
 }
 
+variable "session_force_destroy" {
+  description = "Whether to allow the session bucket to be destroyed even if it still contains objects."
+  type        = bool
+  default     = false
+}
+
 variable "appconfig_application_arn" {
   description = "ARN of the shared runtime-config AppConfig application (from \`core/runtime-config/appconfig.application_arn\`). Used to scope the IAM read permission granted to the agent runtime."
   type        = string
 }
 
+data "aws_region" "current" {}
+data "aws_caller_identity" "current" {}
+
+locals {
+  # Delivery source/destination names have a 60 character maximum. Truncate
+  # the agent name so these stay within the limit.
+  session_access_logs_name_prefix = substr("terraform-snapshot-agent", 0, 30)
+}
+
+# Uniquifies resource names below so this construct can be deployed more than
+# once (e.g. across stages) within the same account/region.
+resource "random_id" "session_unique_suffix" {
+  byte_length = 4
+}
+
+# KMS key encrypting the session bucket and its server access logs.
+resource "aws_kms_key" "session" {
+  description             = "KMS key for terraform-snapshot-agent agent session data"
+  enable_key_rotation     = true
+  deletion_window_in_days = 7
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid       = "EnableIAMUserPermissions"
+        Effect    = "Allow"
+        Principal = { AWS = "arn:aws:iam::\${data.aws_caller_identity.current.account_id}:root" }
+        Action    = "kms:*"
+        Resource  = "*"
+      },
+      {
+        Sid       = "AllowCloudWatchLogs"
+        Effect    = "Allow"
+        Principal = { Service = "logs.\${data.aws_region.current.region}.amazonaws.com" }
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey"
+        ]
+        Resource = "*"
+        Condition = {
+          ArnLike = {
+            "kms:EncryptionContext:aws:logs:arn" = "arn:aws:logs:\${data.aws_region.current.region}:\${data.aws_caller_identity.current.account_id}:log-group:*"
+          }
+        }
+      }
+    ]
+  })
+
+  tags = var.tags
+}
+
+# CloudWatch log group receiving the session bucket's server access logs.
+resource "aws_cloudwatch_log_group" "session_access_logs" {
+  name              = "/aws/s3/terraform-snapshot-agent-session-access-logs-\${random_id.session_unique_suffix.hex}"
+  retention_in_days = 365
+  kms_key_id        = aws_kms_key.session.arn
+
+  tags = var.tags
+}
+
+# Bucket storing the agent's session data
+resource "aws_s3_bucket" "session" {
+  bucket = "terraform-snapshot-agent-sessions-\${random_id.session_unique_suffix.hex}"
+  #checkov:skip=CKV2_AWS_61:Lifecycle configuration not required for session data
+  #checkov:skip=CKV_AWS_144:Cross-region replication not required for session data
+  #checkov:skip=CKV2_AWS_62:Event notifications not required for session data
+  #checkov:skip=CKV_AWS_18:Server access logs are delivered to CloudWatch Logs (see aws_cloudwatch_log_delivery.session)
+  #checkov:skip=CKV_AWS_21:Session data does not need versioning enabled
+  force_destroy = var.session_force_destroy
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "session" {
+  bucket = aws_s3_bucket.session.id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      kms_master_key_id = aws_kms_key.session.arn
+      sse_algorithm     = "aws:kms"
+    }
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "session" {
+  bucket = aws_s3_bucket.session.id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_policy" "session" {
+  bucket = aws_s3_bucket.session.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid       = "DenyInsecureConnections"
+        Effect    = "Deny"
+        Principal = "*"
+        Action    = "s3:*"
+        Resource = [
+          aws_s3_bucket.session.arn,
+          "\${aws_s3_bucket.session.arn}/*"
+        ]
+        Condition = {
+          Bool = {
+            "aws:SecureTransport" = "false"
+          }
+        }
+      }
+    ]
+  })
+}
+
+# Deliver the session bucket's server access logs to CloudWatch Logs.
+resource "aws_cloudwatch_log_delivery_source" "session" {
+  name         = "\${local.session_access_logs_name_prefix}-access-logs-source-\${random_id.session_unique_suffix.hex}"
+  log_type     = "S3_SERVER_ACCESS_LOGS"
+  resource_arn = aws_s3_bucket.session.arn
+}
+
+resource "aws_cloudwatch_log_delivery_destination" "session" {
+  name = "\${local.session_access_logs_name_prefix}-access-logs-dest-\${random_id.session_unique_suffix.hex}"
+
+  delivery_destination_configuration {
+    destination_resource_arn = aws_cloudwatch_log_group.session_access_logs.arn
+  }
+}
+
+resource "aws_cloudwatch_log_delivery" "session" {
+  delivery_source_name     = aws_cloudwatch_log_delivery_source.session.name
+  delivery_destination_arn = aws_cloudwatch_log_delivery_destination.session.arn
+}
+
 module "agent_core_runtime" {
   source = "../../../core/agent-core"
   agent_runtime_name = "TerraformSnapshotAgent"
   docker_image_tag = "proj-terraform-snapshot-agent:latest"
   server_protocol = "HTTP"
+  enable_vpc = var.enable_vpc
+  vpc_id = var.vpc_id
+  subnet_ids = var.subnet_ids
 
   env = merge({
     RUNTIME_CONFIG_APP_ID = var.appconfig_application_id
@@ -223,6 +1218,29 @@ module "agent_core_runtime" {
         "arn:aws:bedrock:*:*:foundation-model/*",
         "arn:aws:bedrock:*:*:inference-profile/*"
       ]
+    },
+    # Grant access for the agent to read/write its session data
+    {
+      Effect = "Allow"
+      Action = [
+        "s3:GetObject",
+        "s3:PutObject",
+        "s3:DeleteObject",
+        "s3:ListBucket"
+      ]
+      Resource = [
+        aws_s3_bucket.session.arn,
+        "\${aws_s3_bucket.session.arn}/*"
+      ]
+    },
+    # Grant access for the agent to use the session bucket's KMS key
+    {
+      Effect = "Allow"
+      Action = [
+        "kms:Decrypt",
+        "kms:GenerateDataKey*"
+      ]
+      Resource = [aws_kms_key.session.arn]
     }
   ], var.additional_iam_policy_statements)
   tags = var.tags
@@ -234,7 +1252,7 @@ module "add_agent_runtime_to_runtime_config" {
 
   namespace = "agentcore"
   key       = "agentRuntimes"
-  value     = { "TerraformSnapshotAgent" = module.agent_core_runtime.agent_core_runtime_arn }
+  value     = { "TerraformSnapshotAgent" = { arn = module.agent_core_runtime.agent_core_runtime_arn, session = { bucketName = aws_s3_bucket.session.bucket } } }
 
   depends_on = [module.agent_core_runtime]
 }
@@ -249,10 +1267,20 @@ output "agent_core_runtime_arn" {
   value       = module.agent_core_runtime.agent_core_runtime_arn
 }
 
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime"
+  value       = module.agent_core_runtime.invocation_url
+}
+
 output "appconfig_application_id" {
   description = "AppConfig Application ID for runtime config (passthrough of the shared \`appconfig_application_id\` input)."
   value       = var.appconfig_application_id
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = module.agent_core_runtime.security_group_id
+}
 "
 `;
 
@@ -263,15 +1291,15 @@ exports[`ts#agent generator > should match snapshot for Terraform generated file
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = ">= 6.23"
+      version = "6.60.0"
     }
     null = {
       source  = "hashicorp/null"
-      version = ">= 3.0"
+      version = "3.3.1"
     }
     random = {
       source  = "hashicorp/random"
-      version = ">= 3.0"
+      version = "3.9.0"
     }
   }
 }
@@ -329,6 +1357,30 @@ variable "additional_iam_policy_statements" {
   default = []
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "tags" {
   description = "Tags to apply to resources"
   type        = map(string)
@@ -354,8 +1406,7 @@ resource "aws_ecr_repository" "agent_core_repository" {
   #checkov:skip=CKV_AWS_136:AES256 encryption is sufficient for ECR repositories
   name = "\${lower(var.agent_runtime_name)}_repository_\${random_id.unique_suffix.hex}"
 
-  #checkov:skip=CKV_AWS_51:Image tag is reused for latest deployments
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 
   image_scanning_configuration {
@@ -529,28 +1580,62 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\\"digest\\":\\"'$(docker inspect \${var.docker_image_tag} --format '{{.Id}}')'\\"}' "]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 # Null resource for container image publish
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest    = data.external.docker_digest.result.digest
     repository_url   = aws_ecr_repository.agent_core_repository.repository_url
     docker_image_tag = var.docker_image_tag
+    image_tag        = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       # Get ECR login token
-      aws ecr get-login-password --region \${local.aws_region} | docker login --username AWS --password-stdin \${self.triggers.repository_url}
+      aws ecr get-login-password --region "$AWS_REGION" | docker login --username AWS --password-stdin "$REPOSITORY_URL"
 
-      # Tag the image
-      docker tag \${self.triggers.docker_image_tag} \${self.triggers.repository_url}:latest
+      # Tag the image with the immutable content-based tag
+      docker tag "$DOCKER_IMAGE_TAG" "$REPOSITORY_URL:$IMAGE_TAG"
 
       # Push the image
-      docker push \${self.triggers.repository_url}:latest
+      docker push "$REPOSITORY_URL:$IMAGE_TAG"
     EOT
+    environment = {
+      AWS_REGION       = local.aws_region
+      REPOSITORY_URL   = self.triggers.repository_url
+      DOCKER_IMAGE_TAG = self.triggers.docker_image_tag
+      IMAGE_TAG        = self.triggers.image_tag
+    }
   }
 
-  depends_on = [aws_ecr_repository_policy.agent_core_ecr_policy]
+  depends_on = [aws_ecr_repository_policy.agent_core_ecr_policy]
+}
+
+# Security group for the agent core runtime, used when running inside a VPC
+resource "aws_security_group" "agent_core_runtime" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to the runtime via network_configuration; Checkov cannot resolve this reference
+  name_prefix = "\${var.agent_runtime_name}-runtime-"
+  description = "Security group for the \${var.agent_runtime_name} agent core runtime"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "agent_core_runtime_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.agent_core_runtime[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
 }
 
 # Bedrock AgentCore Agent Runtime
@@ -561,7 +1646,7 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
 
   agent_runtime_artifact {
     container_configuration {
-      container_uri = "\${aws_ecr_repository.agent_core_repository.repository_url}:latest"
+      container_uri = "\${aws_ecr_repository.agent_core_repository.repository_url}:\${local.image_tag}"
     }
   }
 
@@ -578,8 +1663,24 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
     }
   }
 
+  # Receive the caller's Authorization header (validated by the JWT authorizer).
+  dynamic "request_header_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []
+    content {
+      request_header_allowlist = ["Authorization"]
+    }
+  }
+
   network_configuration {
-    network_mode = "PUBLIC"
+    network_mode = var.enable_vpc ? "VPC" : "PUBLIC"
+
+    dynamic "network_mode_config" {
+      for_each = var.enable_vpc ? [1] : []
+      content {
+        security_groups = [aws_security_group.agent_core_runtime[0].id]
+        subnets         = var.subnet_ids
+      }
+    }
   }
 
   protocol_configuration {
@@ -594,7 +1695,70 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   ]
 }
 
+# MCP consumers (e.g. gateway targets, which fetch tools at creation) can race
+# the runtime's first cold start, so probe it until it serves MCP. The ARN
+# output is routed through this resource so consumers wait for readiness.
+resource "null_resource" "runtime_ready" {
+  count = var.server_protocol == "MCP" ? 1 : 0
+
+  triggers = {
+    runtime_arn = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      uv run --with boto3==1.43.72 python -c "
+import boto3
+import json
+import os
+import time
+import uuid
+
+runtime_arn = os.environ['RUNTIME_ARN']
+client = boto3.client('bedrock-agentcore')
+initialize_request = json.dumps({
+    'jsonrpc': '2.0',
+    'id': 1,
+    'method': 'initialize',
+    'params': {
+        'protocolVersion': '2025-03-26',
+        'capabilities': {},
+        'clientInfo': {'name': 'readiness-probe', 'version': '1.0'},
+    },
+})
+
+deadline = time.time() + 5 * 60
+while True:
+    try:
+        client.invoke_agent_runtime(
+            agentRuntimeArn=runtime_arn,
+            runtimeSessionId=f'readiness-probe-{uuid.uuid4()}',
+            contentType='application/json',
+            accept='application/json, text/event-stream',
+            payload=initialize_request,
+        )
+        break
+    except Exception:
+        if time.time() >= deadline:
+            raise
+        time.sleep(5)
+
+print(f'Runtime {runtime_arn} is serving MCP')
+"
+    EOT
+    environment = {
+      RUNTIME_ARN = self.triggers.runtime_arn
+    }
+  }
+}
+
 # Outputs
+locals {
+  # For MCP runtimes the ARN flows through the readiness probe, so consumers
+  # wait until the runtime serves MCP.
+  ready_runtime_arn = var.server_protocol == "MCP" ? null_resource.runtime_ready[0].triggers.runtime_arn : aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+}
+
 output "agent_core_runtime_role_arn" {
   description = "ARN of the Agent Core Runtime IAM role"
   value       = aws_iam_role.agent_core_runtime_role.arn
@@ -611,8 +1775,13 @@ output "agent_runtime_name" {
 }
 
 output "agent_core_runtime_arn" {
-  description = "ARN of the Bedrock Agent Core runtime"
-  value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  description = "ARN of the Bedrock Agent Core runtime. For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = local.ready_runtime_arn
+}
+
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime. MCP runtimes get the MCP endpoint (e.g. for use as a Gateway target endpoint), A2A runtimes the A2A endpoint (trailing slash required). For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = "https://bedrock-agentcore.\${local.aws_region}.amazonaws.com/runtimes/\${urlencode(local.ready_runtime_arn)}/invocations\${var.server_protocol == "A2A" ? "/" : "?qualifier=DEFAULT"}"
 }
 
 output "agent_runtime_id" {
@@ -624,11 +1793,21 @@ output "agent_runtime_version" {
   description = "Version of the Bedrock Agent Core runtime"
   value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_version
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.agent_core_runtime[0].id : null
+}
 "
 `;
 
 exports[`ts#agent generator > should match snapshot for generated files > agent-agent.ts 1`] = `
 "import { Agent, tool } from '@strands-agents/sdk';
+import {
+  ModelErrorLoggingPlugin,
+  ToolErrorLoggingPlugin,
+} from '@proj/agent-connection';
+import { getSessionManager } from './session.js';
 import { z } from 'zod';
 
 const multiply = tool({
@@ -641,13 +1820,17 @@ const multiply = tool({
   callback: ({ a, b }) => a * b,
 });
 
-export const getAgent = async () =>
-  new Agent({
+export const getAgent = async () => {
+  const agent = new Agent({
     systemPrompt: \`You are a mathematical wizard.
   Use your tools for mathematical tasks.
   Refer to tools as your 'spellbook'.\`,
     tools: [multiply],
+    sessionManager: await getSessionManager(),
+    plugins: [new ModelErrorLoggingPlugin(), new ToolErrorLoggingPlugin()],
   });
+  return agent;
+};
 "
 `;
 
@@ -930,7 +2113,7 @@ exports[`ts#agent generator > should match snapshot for generated files > agent-
 "import { publicProcedure, t } from './init.js';
 import { z } from 'zod';
 import { zAsyncIterable } from './schema/z-async-iterable.js';
-import { enterSessionContext, withSessionId } from ':proj/agent-connection';
+import { enterSessionContext, withSessionId } from '@proj/agent-connection';
 import { getAgent } from './agent.js';
 
 export const router = t.router;
@@ -939,7 +2122,7 @@ const agent = withSessionId(getAgent);
 
 export const appRouter = router({
   invoke: publicProcedure
-    .input(z.object({ message: z.string() }))
+    .input(z.object({ prompt: z.string().max(100000) }))
     .output(
       zAsyncIterable({
         yield: z.string(),
@@ -949,7 +2132,7 @@ export const appRouter = router({
     .subscription(async function* (opts) {
       // Bind the session ID for this subscription so downstream MCP / A2A clients forward it on outbound calls.
       enterSessionContext(opts.ctx.sessionId);
-      for await (const event of agent.stream(opts.input.message)) {
+      for await (const event of agent.stream(opts.input.prompt)) {
         if (
           event.type === 'modelStreamUpdateEvent' &&
           event.event.type === 'modelContentBlockDeltaEvent' &&
@@ -1048,3 +2231,275 @@ export function zAsyncIterable<
 }
 "
 `;
+
+exports[`ts#agent generator > should not create session bucket infrastructure when session is in-memory (Terraform) > terraform-agent.tf (in-memory) 1`] = `
+"variable "env" {
+  description = "Environment variables to pass to the agent core runtime"
+  type        = map(string)
+  default     = {}
+}
+
+variable "additional_iam_policy_statements" {
+  description = "Additional IAM policy statements to attach to the agent core runtime role"
+  type = list(object({
+    Effect   = string
+    Action   = list(string)
+    Resource = list(string)
+  }))
+  default = []
+}
+
+variable "tags" {
+  description = "Tags to apply to resources"
+  type        = map(string)
+  default     = {}
+}
+
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
+variable "appconfig_application_id" {
+  description = "ID of the shared runtime-config AppConfig application (from \`core/runtime-config/appconfig.application_id\`). The agent reads its runtime configuration from this application."
+  type        = string
+}
+
+variable "appconfig_application_arn" {
+  description = "ARN of the shared runtime-config AppConfig application (from \`core/runtime-config/appconfig.application_arn\`). Used to scope the IAM read permission granted to the agent runtime."
+  type        = string
+}
+
+module "agent_core_runtime" {
+  source = "../../../core/agent-core"
+  agent_runtime_name = "InMemoryTerraformAgent"
+  docker_image_tag = "proj-in-memory-terraform-agent:latest"
+  server_protocol = "HTTP"
+  enable_vpc = var.enable_vpc
+  vpc_id = var.vpc_id
+  subnet_ids = var.subnet_ids
+
+  env = merge({
+    RUNTIME_CONFIG_APP_ID = var.appconfig_application_id
+  }, var.env)
+  additional_iam_policy_statements = concat([
+    {
+      Effect   = "Allow"
+      Action   = [
+        "appconfig:StartConfigurationSession",
+        "appconfig:GetLatestConfiguration"
+      ]
+      Resource = ["\${var.appconfig_application_arn}/*"]
+    },
+    # Grant access for the agent to invoke bedrock models
+    {
+      Effect = "Allow"
+      Action = [
+        "bedrock:InvokeModel",
+        "bedrock:InvokeModelWithResponseStream"
+      ]
+      Resource = [
+        "arn:aws:bedrock:*:*:foundation-model/*",
+        "arn:aws:bedrock:*:*:inference-profile/*"
+      ]
+    }
+  ], var.additional_iam_policy_statements)
+  tags = var.tags
+}
+
+# Add agent runtime ARN to runtime config
+module "add_agent_runtime_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "agentcore"
+  key       = "agentRuntimes"
+  value     = { "InMemoryTerraformAgent" = { arn = module.agent_core_runtime.agent_core_runtime_arn } }
+
+  depends_on = [module.agent_core_runtime]
+}
+
+output "agent_core_runtime_role_arn" {
+  description = "ARN of the agent core runtime role"
+  value       = module.agent_core_runtime.agent_core_runtime_role_arn
+}
+
+output "agent_core_runtime_arn" {
+  description = "ARN of the Bedrock Agent Core runtime"
+  value       = module.agent_core_runtime.agent_core_runtime_arn
+}
+
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime"
+  value       = module.agent_core_runtime.invocation_url
+}
+
+output "appconfig_application_id" {
+  description = "AppConfig Application ID for runtime config (passthrough of the shared \`appconfig_application_id\` input)."
+  value       = var.appconfig_application_id
+}
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = module.agent_core_runtime.security_group_id
+}
+"
+`;
+
+exports[`ts#agent generator > should not create session bucket infrastructure when session is in-memory > agent-construct.ts (in-memory) 1`] = `
+"import { Fn, Lazy, Names, Stack } from 'aws-cdk-lib';
+import { Platform } from 'aws-cdk-lib/aws-ecr-assets';
+import { Connections, IConnectable } from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+import * as path from 'path';
+import * as url from 'url';
+import {
+  AgentRuntimeArtifact,
+  ProtocolType,
+  Runtime,
+  RuntimeProps,
+} from 'aws-cdk-lib/aws-bedrockagentcore';
+import {
+  PolicyStatement,
+  IGrantable,
+  IPrincipal,
+  Grant,
+} from 'aws-cdk-lib/aws-iam';
+import { RuntimeConfig } from '../../../core/runtime-config.js';
+import { findWorkspaceRoot } from '../../../core/workspace.js';
+
+export type InMemoryAgentProps = Omit<
+  RuntimeProps,
+  | 'runtimeName'
+  | 'protocolConfiguration'
+  | 'agentRuntimeArtifact'
+  | 'authorizerConfiguration'
+>;
+
+export class InMemoryAgent
+  extends Construct
+  implements IGrantable, IConnectable
+{
+  public readonly dockerImage: AgentRuntimeArtifact;
+  public readonly agentCoreRuntime: Runtime;
+  /** Default Gateway target name for this agent. */
+  public readonly agentName = 'in-memory-agent';
+  /** Inbound auth — a fronting Gateway uses this to pick its outbound credential. */
+  public readonly auth = 'iam';
+
+  constructor(scope: Construct, id: string, props?: InMemoryAgentProps) {
+    super(scope, id);
+
+    const rc = RuntimeConfig.ensure(this);
+
+    // Resolve the bundle output directory containing the Dockerfile and built artifacts
+    const bundleDir = path.join(
+      findWorkspaceRoot(url.fileURLToPath(new URL(import.meta.url))),
+      'dist/apps/test-project/bundle/agent/in-memory-agent',
+    );
+
+    this.dockerImage = AgentRuntimeArtifact.fromAsset(bundleDir, {
+      platform: Platform.LINUX_ARM64,
+    });
+
+    this.agentCoreRuntime = new Runtime(this, 'InMemoryAgent', {
+      runtimeName: Lazy.string({
+        produce: () =>
+          Names.uniqueResourceName(this.agentCoreRuntime, { maxLength: 40 }),
+      }),
+      protocolConfiguration: ProtocolType.HTTP,
+      agentRuntimeArtifact: this.dockerImage,
+      ...props,
+      environmentVariables: {
+        RUNTIME_CONFIG_APP_ID: rc.appConfigApplicationId,
+        ...props?.environmentVariables,
+      },
+    });
+
+    // Grant access for the agent to invoke bedrock models
+    this.agentCoreRuntime.addToRolePolicy(
+      new PolicyStatement({
+        actions: [
+          'bedrock:InvokeModel',
+          'bedrock:InvokeModelWithResponseStream',
+        ],
+        resources: [
+          'arn:aws:bedrock:*:*:foundation-model/*',
+          'arn:aws:bedrock:*:*:inference-profile/*',
+        ],
+      }),
+    );
+
+    rc.grantReadAppConfig(this.agentCoreRuntime);
+
+    rc.set('agentcore', 'agentRuntimes', {
+      ...rc.get('agentcore').agentRuntimes,
+      InMemoryAgent: {
+        arn: this.agentCoreRuntime.agentRuntimeArn,
+      },
+    });
+  }
+
+  /**
+   * The principal to grant permissions to.
+   */
+  public get grantPrincipal(): IPrincipal {
+    return this.agentCoreRuntime.grantPrincipal;
+  }
+
+  /**
+   * Network connections for this agent runtime.
+   */
+  public get connections(): Connections {
+    return this.agentCoreRuntime.connections;
+  }
+
+  /**
+   * The HTTPS invocation URL of the runtime.
+   */
+  public get invocationUrl(): string {
+    // The URL must URL-encode the runtime ARN (':' -> '%3A', '/' -> '%2F').
+    // The ARN is a CDK token, so encode at deploy time via Fn.join/Fn.split.
+    const encodedArn = Fn.join(
+      '%2F',
+      Fn.split(
+        '/',
+        Fn.join('%3A', Fn.split(':', this.agentCoreRuntime.agentRuntimeArn)),
+      ),
+    );
+    return \`https://bedrock-agentcore.\${Stack.of(this).region}.amazonaws.com/runtimes/\${encodedArn}/invocations?qualifier=DEFAULT\`;
+  }
+
+  /**
+   * Grants IAM permissions to invoke this agent runtime.
+   *
+   * @param grantee - The IAM principal to grant permissions to
+   */
+  public grantInvokeAccess(grantee: IGrantable) {
+    this.agentCoreRuntime.grantInvoke(grantee);
+
+    Grant.addToPrincipal({
+      grantee,
+      actions: ['bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream'],
+      resourceArns: [
+        this.agentCoreRuntime.agentRuntimeArn,
+        \`\${this.agentCoreRuntime.agentRuntimeArn}/*\`,
+      ],
+    });
+  }
+}
+"
+`;