@aws-blocks/bb-agent 0.3.5 → 0.4.1

package/src/agentcore-bundle.ts

@@ -0,0 +1,162 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Synth-time co-bundle for the AgentCore Runtime code asset.
+ *
+ * The AgentCore process must run BOTH the developer's backend (which constructs the real
+ * Agent and its tool closures) AND bb-agent's `serve()` — from a SINGLE module graph, so
+ * the Agent instance registry (a module singleton in agent.ts) is shared. If the backend
+ * and the entrypoint were bundled separately they'd each get their own bb-agent copy, the
+ * Agent would register in one registry and the lookup would read the other, and `serve()`
+ * would fail with "No Agent registered".
+ *
+ * We esbuild-bundle a tiny generated entry that imports both from the same graph. We call
+ * `esbuild.buildSync()` DIRECTLY (not CDK's `NodejsFunction`) — that avoids the
+ * `PathNotUnderRoot` failure `NodejsFunction` hits for npm-installed packages, since direct
+ * esbuild has no projectRoot/lockfile requirement. `buildSync` because CDK synth is sync.
+ *
+ * Packaging mirrors the official `@aws/agentcore` CLI's Node CodeZip packager
+ * (lib/packaging/node.js), because the AgentCore direct-deploy base image provides ONLY the
+ * Node runtime — every dependency (including the AWS SDK) must be in the asset. Two wrinkles
+ * the CLI solves and we copy verbatim:
+ *
+ *  1. The `bedrock-agentcore` harness does `createRequire(import.meta.url); require('@fastify/sse')`
+ *     at module load. esbuild can't statically bundle those dynamic requires. So we emit CJS
+ *     (`format: 'cjs'`), shim `import.meta.url` to a real value, and prepend a banner that
+ *     patches `Module._resolveFilename` to fall back to a sibling `_deps/` dir. The dynamic
+ *     packages are copied into `_deps/` so the fallback finds them at runtime.
+ *  2. The `@aws-sdk/*` packages are pure JS and NOT in the base image, so we bundle them
+ *     (no `external`).
+ */
+import { buildSync } from 'esbuild';
+import { cpSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** bb-agent package root (dist/.. == package dir), used as esbuild's module-resolution base. */
+const PKG_ROOT = join(__dirname, '..');
+
+/** Sibling dir (next to the bundle) holding packages that are loaded via dynamic require(). */
+const DEPS_DIR = '_deps';
+
+/**
+ * Packages the `bedrock-agentcore` harness (and its Fastify plugins) load via dynamic
+ * `require()` at runtime, which esbuild leaves unbundled. Copied into `_deps/` and resolved
+ * by the `_resolveFilename` banner below. This list is taken verbatim from the official
+ * `@aws/agentcore` CLI so it stays in sync with the harness's runtime require graph.
+ */
+const DYNAMIC_REQUIRE_PACKAGES = [
+	'@fastify/sse',
+	'@fastify/websocket',
+	'duplexify',
+	'end-of-stream',
+	'fastify-plugin',
+	'inherits',
+	'once',
+	'readable-stream',
+	'safe-buffer',
+	'stream-shift',
+	'string_decoder',
+	'util-deprecate',
+	'wrappy',
+	'ws',
+];
+
+/**
+ * Banner prepended to the CJS bundle. First line gives ESM-style `import.meta.url` a real
+ * value (the harness calls `createRequire(import.meta.url)`); the IIFE patches Node's module
+ * resolver so a failed `require('X')` retries against `__dirname/_deps/X` (reading that
+ * package's `main` from its package.json). Byte-for-byte the CLI's banner.
+ */
+const CJS_BANNER =
+	'const importMetaUrl = require("url").pathToFileURL(__filename).href;' +
+	'(function(){var M=require("module"),p=require("path"),f=require("fs"),d=p.join(__dirname,"_deps"),o=M._resolveFilename;' +
+	'M._resolveFilename=function(r,P,i,O){try{return o.call(this,r,P,i,O)}catch(e){' +
+	'var dp=p.join(d,r);if(f.existsSync(dp)){var pk=p.join(dp,"package.json");' +
+	'if(f.existsSync(pk)){var m=JSON.parse(f.readFileSync(pk,"utf8")).main||"index.js";return p.resolve(dp,m)}' +
+	'return p.resolve(dp,"index.js")}throw e}};})();';
+
+/** Copy each dynamic-require package into `<outDir>/_deps/<pkg>`, resolving via bb-agent's
+ * module graph so hoisted (monorepo) and nested installs both work. */
+function copyDynamicDeps(outDir: string): void {
+	const require = createRequire(join(PKG_ROOT, 'noop.js'));
+	for (const pkg of DYNAMIC_REQUIRE_PACKAGES) {
+		let pkgDir: string;
+		try {
+			// Resolve the package's own package.json, then take its directory.
+			pkgDir = dirname(require.resolve(`${pkg}/package.json`));
+		} catch {
+			// Not installed / not resolvable from here — skip; the runtime fallback only
+			// needs the packages actually reached by the harness's require graph.
+			continue;
+		}
+		if (existsSync(pkgDir)) {
+			cpSync(pkgDir, join(outDir, DEPS_DIR, pkg), { recursive: true });
+		}
+	}
+}
+
+/**
+ * Co-bundle the app backend + `serve()` into a self-contained AgentCore asset directory.
+ *
+ * @param backendModulePath - absolute path to the app's backend module (BlocksStack `backendCDKPath`)
+ * @param outDir - directory to write the bundle into (a stable, synth-scoped path under cdk.out)
+ * @returns `outDir` (contains `main.js`, `_deps/`, `package.json`), ready for `fromCodeAsset`.
+ *   The bundle is named `main.js` (not `agentcore-entry.js`) because AgentCore's entrypoint
+ *   validator rejects names it considers to have "multiple dots" / disallowed chars; `main.js`
+ *   matches the official @aws/agentcore CLI's convention and passes.
+ */
+export function bundleAgentCoreAsset(backendModulePath: string, outDir: string): string {
+	// Generated entry: load config, import the backend (constructs + registers the Agent),
+	// then serve. `resolveDir` = bb-agent package root so `@aws-blocks/*` and this package's
+	// own `serve` resolve via node_modules; the backend is imported by absolute PATH (esbuild
+	// resolves paths, not file:// URLs) so it's bundled into the SAME graph and its
+	// `@aws-blocks/*` deps dedupe to one instance.
+	// Wrapped in an async IIFE (not top-level await) because the bundle is emitted as CJS,
+	// which does not support top-level await.
+	const entrySource = [
+		"import { loadConfigToProcessEnv } from '@aws-blocks/core';",
+		"import { serve } from '@aws-blocks/bb-agent/agentcore';",
+		'(async () => {',
+		'  await loadConfigToProcessEnv();',
+		`  await import(${JSON.stringify(backendModulePath)});`,
+		'  serve();',
+		'})();',
+	].join('\n');
+
+	mkdirSync(outDir, { recursive: true });
+
+	buildSync({
+		stdin: {
+			contents: entrySource,
+			resolveDir: PKG_ROOT,
+			sourcefile: '__agentcore_entry.mjs',
+			loader: 'js',
+		},
+		outfile: join(outDir, 'main.js'),
+		bundle: true,
+		platform: 'node',
+		target: 'node22',
+		// CJS (not ESM) so the harness's createRequire + our _resolveFilename patch work.
+		format: 'cjs',
+		minify: true,
+		// Resolve @aws-blocks/* (and the backend's BB constructions) to their AWS-runtime
+		// variants, exactly as core bundles the Lambda handler.
+		conditions: ['aws-runtime', 'node'],
+		banner: { js: CJS_BANNER },
+		// Give ESM `import.meta.url` (used by the harness) a real value under CJS output.
+		define: { 'import.meta.url': 'importMetaUrl' },
+	});
+
+	// `{"type":"commonjs"}` so Node treats the .js bundle as CJS regardless of any ambient
+	// "type":"module" in a parent package.json.
+	writeFileSync(join(outDir, 'package.json'), '{"type":"commonjs"}');
+
+	// Ship the harness's dynamic-require closure alongside the bundle.
+	copyDynamicDeps(outDir);
+
+	return outDir;
+}

package/src/agentcore-entry.ts

@@ -0,0 +1,134 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * AgentCore Runtime entrypoint for the Agent BB.
+ *
+ * Hosts the developer's real Agent — the same instance the Lambda handler would build — on
+ * the `BedrockAgentCoreApp` harness (implements the `/invocations` + `/ping` contract on port
+ * 8080), and runs the agent loop as a **background async task** that streams chunks to the
+ * browser over the Realtime BB (exactly as the loop does on Lambda today).
+ *
+ * Why background + Realtime (not the harness's SSE response): the browser never holds a
+ * connection to AgentCore — it subscribes to a Realtime channel by `channelId`. So the
+ * invocation must return immediately while the loop keeps running server-side. The harness
+ * keeps the microVM alive (up to the 8h session lifetime) while an async task is in flight —
+ * `/ping` reports `HealthyBusy` — via `addAsyncTask()`/`completeAsyncTask()`. `runAgent()`
+ * publishes every chunk to Realtime under the runtime's execution role.
+ *
+ * How the developer's agent definition reaches this process:
+ *   The `tools` callback in AgentConfig is a JS closure and can't be serialized across a
+ *   process boundary. So instead of shipping data, we ship code: this entrypoint imports
+ *   the SAME developer backend module the Lambda handler imports (co-bundled with
+ *   `--conditions=aws-runtime`, so `new Agent()` resolves to the AWS runtime class). That
+ *   construction registers the live Agent in the instance registry (see agent.ts); we look
+ *   it up by the `BB_AGENT_ID` the CDK Runtime construct set, and drive its loop.
+ *
+ * Launched by the CodeZip artifact as: ['main.js'] (the co-bundle from agentcore-bundle.ts).
+ */
+
+import { loadConfigToProcessEnv } from '@aws-blocks/core';
+import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
+import { z } from 'zod';
+import { getAgentInstance } from './agent.js';
+
+/** Request contract — mirrors the Lambda jobPayloadSchema, minus transport-only fields. */
+const requestSchema = z.object({
+	/** User prompt. Empty on resume (interruptResponses drive the turn instead). */
+	prompt: z.string().default(''),
+	/** Realtime channel the client subscribes to for this turn's chunks. */
+	channelId: z.string(),
+	/** Conversation to persist to / restore the session from. Falls back to the AgentCore session id. */
+	conversationId: z.string().optional(),
+	/** Owner of the conversation. Required when persistence is enabled (not inferenceOnly). */
+	userId: z.string().optional(),
+	/** HITL resume: approval responses to apply instead of a new prompt. */
+	interruptResponses: z.array(z.object({ interruptId: z.string(), response: z.string() })).optional(),
+	/** Per-call tool context, threaded through to tool handlers. Must be JSON-serializable. */
+	context: z.unknown().optional(),
+});
+
+/**
+ * Serve a registered Agent on the AgentCore harness.
+ *
+ * The developer's backend must already have been imported in THIS process (so the Agent
+ * registered itself in the shared registry) — either by `main()` below (standalone launch
+ * via `BB_AGENT_BACKEND_MODULE`) or by the co-bundle (agentcore-bundle.ts) that imports the
+ * backend and this `serve` from the same bb-agent module instance. Co-bundling is required
+ * because the registry is a module singleton — a split would put the Agent in one map and
+ * the lookup in another.
+ *
+ * @param agentId - fullId of the target Agent (defaults to process.env.BB_AGENT_ID)
+ */
+export function serve(agentId = process.env.BB_AGENT_ID): void {
+	if (!agentId) throw new Error('BB_AGENT_ID is required (fullId of the target Agent).');
+	const agent = getAgentInstance(agentId);
+	if (!agent) {
+		throw new Error(
+			`No Agent registered with id '${agentId}'. Ensure the backend module constructs it at import time.`,
+		);
+	}
+
+	const app = new BedrockAgentCoreApp({
+		invocationHandler: {
+			requestSchema,
+			process: (request, context) => {
+				// AgentCore routes every invocation for a session to the same warm microVM.
+				// runtimeSessionId maps to the Agent BB's conversationId (session state key).
+				const conversationId = request.conversationId ?? context.sessionId;
+
+				// Run the turn as a background async task so this invocation returns immediately.
+				// The harness reports `/ping` = HealthyBusy while the task is in flight, keeping
+				// the microVM alive (up to the 8h session lifetime) until the loop completes.
+				// Chunks are delivered out-of-band via Realtime — this HTTP response is just an ack.
+				const taskId = app.addAsyncTask('agent-turn');
+				void agent
+					.invokeTurn({
+						message: request.prompt,
+						conversationId,
+						channelId: request.channelId,
+						userId: request.userId ?? 'anonymous',
+						interruptResponses: request.interruptResponses,
+						context: request.context,
+					})
+					.finally(() => app.completeAsyncTask(taskId));
+
+				// The client already has channelId (from the RPC that invoked us) and subscribes
+				// to Realtime; it does not consume this response body.
+				return { channelId: request.channelId, status: 'accepted' };
+			},
+		},
+	});
+
+	app.run();
+}
+
+/**
+ * Standalone launch: load config, import the developer backend by path, then serve.
+ * Used when the artifact runs this file directly with BB_AGENT_BACKEND_MODULE pointing at the
+ * backend. When an app co-bundles the backend with `serve` (agentcore-bundle.ts), it calls
+ * `serve()` directly instead and this `main()` is not the entry.
+ */
+export async function main(): Promise<void> {
+	// Same cold-start contract as the Lambda handler: pull BB resource identifiers
+	// (table names, bucket names, Realtime callback URL) into process.env before importing
+	// the backend, so BB constructors can resolve them.
+	await loadConfigToProcessEnv();
+
+	const backendModule = process.env.BB_AGENT_BACKEND_MODULE;
+	if (!backendModule)
+		throw new Error('BB_AGENT_BACKEND_MODULE env var is required (path to the developer backend module).');
+
+	// Import the developer backend — constructing the real Agent, which registers itself.
+	await import(backendModule);
+
+	serve();
+}
+
+// Auto-run the standalone launch path ONLY when a backend module path is provided.
+// The co-bundle path (agentcore-bundle.ts) imports `serve` and invokes it directly after
+// importing the backend inline, and does NOT set BB_AGENT_BACKEND_MODULE — so `main()` must
+// not fire there (it would double-serve and throw on the missing env var).
+if (process.env.BB_AGENT_BACKEND_MODULE) {
+	void main();
+}

package/src/agentcore-runtime.cdk.ts

@@ -0,0 +1,203 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Self-contained CDK provisioning for the Agent BB's AgentCore Runtime.
+ *
+ * This class owns EVERYTHING AgentCore-specific: the synth-time co-bundle of the app backend,
+ * the `Runtime` construct (via `fromCodeAsset` — Node 22 CodeZip, no Docker), the shared role's
+ * AgentCore trust + grants, the container env injection, and the grant that lets the app's RPC
+ * handler invoke the runtime. It is deliberately kept in one place, with no AgentCore details
+ * leaking into the `Agent` CDK constructor or into core, so it can later fold into a per-BB
+ * compute abstraction (should one land) without touching call sites — the Agent just constructs
+ * it and hands over references to the BBs the loop uses.
+ *
+ * The loop runs INSIDE this runtime AS the shared Blocks execution role (the same role the Lambda
+ * handler runs as), so it inherits every Building Block's grants — including the Realtime publish
+ * permissions already granted to the handler, so it streams chunks to the browser via the Realtime
+ * BB with no extra grant. The container loads the full app config (via the injected config-bucket
+ * location) exactly as the handler does, so it discovers the Realtime callback URL and every other
+ * registerConfig() value a tool's BB may need. This class adds to that shared role only what's
+ * AgentCore-specific: the `bedrock-agentcore` assume-role trust, Bedrock model access, and the
+ * handler's `InvokeAgentRuntime` permission. Inbound auth is IAM (SigV4): the RPC handler
+ * invokes with its own credentials; the browser never talks to the runtime directly.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import * as cdk from 'aws-cdk-lib';
+import { AgentCoreRuntime as AgentCoreRuntimeVersion, AgentRuntimeArtifact, Runtime } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { Effect, PolicyStatement, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+import { getConfigLocation, registerConfig, Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import { bundleAgentCoreAsset } from './agentcore-bundle.js';
+
+/** References the agent loop needs, handed in by the Agent CDK constructor. */
+export interface AgentCoreRuntimeProps {
+	/** fullId of the owning Agent — the container looks the Agent up by this (`BB_AGENT_ID`). */
+	agentFullId: string;
+	/**
+	 * Pre-built asset dir to use instead of co-bundling at synth. Set by unit tests and apps
+	 * that pre-bundle; when omitted, the backend module is co-bundled from the BlocksStack.
+	 */
+	agentcoreAssetPath?: string;
+}
+
+export class AgentCoreRuntime extends Scope {
+	/** The provisioned runtime, or undefined when no backend asset could be resolved (isolated tests). */
+	readonly runtime?: Runtime;
+	/** The runtime ARN (empty string when not provisioned). */
+	readonly runtimeArn: string;
+
+	constructor(scope: ScopeParent, id: string, props: AgentCoreRuntimeProps) {
+		super(id, { parent: scope });
+
+		const assetPath = props.agentcoreAssetPath ?? this.buildAsset();
+		if (!assetPath) {
+			// No backend module discoverable (e.g. an isolated unit test that constructs the
+			// Agent without a BlocksStack) — skip provisioning rather than failing synth.
+			this.runtimeArn = '';
+			return;
+		}
+
+		const stack = cdk.Stack.of(this);
+
+		// Run the loop AS the shared Blocks execution role (`role: this.executionRole`) — the same
+		// role the Lambda handler runs as. Because every Building Block grants its runtime permissions
+		// to this role (a tool that uses KVStore/tables/etc. grants there too), the AgentCore
+		// container inherits them all automatically — no bespoke, under-granted role, and no need to
+		// mirror each BB's grants. One shared role that any compute can assume keeps this a drop-in
+		// for a future per-BB compute abstraction.
+		const role = this.executionRole;
+
+		// Add the agent's shared-role trust + grants ONCE per stack. Every agent instance would
+		// otherwise add the SAME trust / Bedrock / InvokeAgentRuntime statements to the ONE shared
+		// role; with several agents in an app that piles up duplicates and overflows the IAM inline-
+		// policy size limit (CDK then spills into `OverflowPolicy` managed policies and the role
+		// misbehaves). These are identical for every agent — Bedrock models and the runtime-ARN
+		// wildcard are stack-scoped — so doing it once covers every agent's container. (Realtime
+		// publish, the session bucket, and the conversation/message tables are already granted to the
+		// shared role by the Realtime BB's handler wiring and the Agent's FileBucket/DistributedTable
+		// children, so they're not repeated here — the loop inherits them by running as the role.)
+		const SHARED_GRANTS_KEY = Symbol.for('BLOCKS_AGENT_RUNTIME_SHARED_ROLE_GRANTS');
+		const stackAny = stack as unknown as Record<symbol, boolean | undefined>;
+		if (!stackAny[SHARED_GRANTS_KEY]) {
+			// The container publishes to Realtime AS this shared role, which already holds the publish
+			// grants (the Realtime BB grants postToConnection + the connections table to the handler on
+			// the same role) — so no Realtime IAM grant is needed here; it's inherited by running as the role.
+
+			// Trust: let the AgentCore Runtime assume this shared role (it runs AS the role). Added here
+			// rather than in core, so the role only trusts `bedrock-agentcore` when an Agent exists.
+			// Scope it to this account/region with aws:SourceAccount + aws:SourceArn — AWS's recommended
+			// AgentCore Runtime trust policy — so only AgentCore runtimes in THIS account can assume the
+			// role (tightens the confused-deputy surface) without breaking assumption. `assumeRolePolicy`
+			// exists only on the concrete `Role`; core always creates BlocksRole concretely, so narrow
+			// and fail loud if that ever changes.
+			if (!(role instanceof Role)) {
+				throw new Error(
+					'AgentCore Runtime requires the shared Blocks execution role to be a concrete iam.Role to add its assume-role trust',
+				);
+			}
+			role.assumeRolePolicy?.addStatements(
+				new PolicyStatement({
+					effect: Effect.ALLOW,
+					principals: [new ServicePrincipal('bedrock-agentcore.amazonaws.com')],
+					actions: ['sts:AssumeRole'],
+					conditions: {
+						StringEquals: { 'aws:SourceAccount': stack.account },
+						ArnLike: { 'aws:SourceArn': `arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:*` },
+					},
+				}),
+			);
+			// Bedrock model access for the loop (no Building Block grants this, and the loop no longer
+			// runs on the handler).
+			role.addToPrincipalPolicy(
+				new PolicyStatement({
+					actions: [
+						'bedrock:InvokeModel',
+						'bedrock:InvokeModelWithResponseStream',
+						'bedrock:GetFoundationModel',
+						'bedrock:ListFoundationModels',
+						'bedrock:GetInferenceProfile',
+					],
+					resources: [`arn:${stack.partition}:bedrock:*::foundation-model/*`, `arn:${stack.partition}:bedrock:*:*:inference-profile/*`],
+				}),
+			);
+			// Let the app's RPC handler (also the shared role) invoke the runtimes — stream()/resume()
+			// call InvokeAgentRuntime. Scope to a wildcard runtime ARN rather than a specific runtime's
+			// ARN: the runtime uses this same shared role as its executionRole, so referencing its ARN
+			// here would create a Role→Runtime→Role dependency cycle. (Same wildcard style as Bedrock.)
+			role.addToPrincipalPolicy(
+				new PolicyStatement({
+					actions: ['bedrock-agentcore:InvokeAgentRuntime'],
+					resources: [
+						`arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:runtime/*`,
+						`arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:runtime/*/*`,
+					],
+				}),
+			);
+			stackAny[SHARED_GRANTS_KEY] = true;
+		}
+
+		// Inject the config location so the container loads the FULL app config via
+		// loadConfigToProcessEnv() — the same config the Lambda handler loads. That's how it gets
+		// BLOCKS_RT_CALLBACK_URL (registered by the Realtime BB) plus any other config-backed BB value
+		// an agent's tools touch; without it the container runs with empty config and those BBs fail.
+		// Idempotent (one config bucket per stack); IAM to read it is inherited via the shared role.
+		const { bucketName: configBucketName, key: configKey } = getConfigLocation(this);
+
+		const runtime = new Runtime(this, 'AgentRuntime', {
+			agentRuntimeArtifact: AgentRuntimeArtifact.fromCodeAsset({
+				path: assetPath,
+				runtime: AgentCoreRuntimeVersion.NODE_22,
+				// Launch command, NOT a Lambda file.export handler. Single element = the .js file;
+				// the NODE_22 runtime invokes `node` itself. (A leading 'node' element is rejected.)
+				entrypoint: ['main.js'],
+			}),
+			executionRole: role,
+			// Inbound auth defaults to IAM (SigV4): the RPC handler invokes with its own creds.
+			// The browser never invokes the runtime directly (it subscribes to Realtime).
+			environmentVariables: {
+				// The Agent's fullId so the container's getAgentInstance(BB_AGENT_ID) matches the
+				// Agent the co-bundled backend registers at import.
+				BB_AGENT_ID: props.agentFullId,
+				// The namespace the container rebuilds fullId (and every derived resource name) from.
+				// MUST be the owning stack/backend's canonical root id — the SAME value the Lambda
+				// handler and the Lambda compute use (`backendStackName`) — not the raw CFN stack name.
+				// They coincide for a top-level BlocksStack, but for a BlocksBackend embedded in a
+				// customer stack the handler uses the backend fullId while cdk.Stack.of(this).stackName
+				// is the customer stack name; using the latter would make the container derive names from
+				// the wrong namespace and miss its own tables/bucket/config.
+				BLOCKS_STACK_NAME: this.backendStackName,
+				// Config location so the container's loadConfigToProcessEnv() loads the full app config
+				// (same as the handler) — this delivers BLOCKS_RT_CALLBACK_URL and every other
+				// registerConfig() value a tool's BB may read. IAM to read it is inherited (shared role).
+				BLOCKS_CONFIG_BUCKET: configBucketName,
+				BLOCKS_CONFIG_KEY: configKey,
+			},
+		});
+		this.runtime = runtime;
+		this.runtimeArn = runtime.agentRuntimeArn;
+
+		// Expose THIS agent's runtime ARN to the Lambda runtime path so stream() can resolve it at
+		// call time. Per-agent (each agent has its own runtime), so it stays outside the shared guard.
+		registerConfig(this, `BB_AGENT_${props.agentFullId}_RUNTIME_ARN`, runtime.agentRuntimeArn);
+	}
+
+	/**
+	 * Co-bundle the app backend + `serve()` into an AgentCore code-asset dir. Returns undefined
+	 * when the backend module path can't be discovered (isolated unit tests) — the caller then
+	 * skips provisioning rather than failing synth.
+	 */
+	private buildAsset(): string | undefined {
+		const stack = (globalThis as any).CURRENT_BLOCKS_STACK as { backendModulePath?: string } | undefined;
+		const backendModulePath = stack?.backendModulePath;
+		if (!backendModulePath) return undefined;
+		const outDir = join(
+			cdk.App.of(this)?.outdir ?? cdk.Stack.of(this).node.tryGetContext('cdk.out') ?? '.cdk-agentcore',
+			`agentcore-${this.fullId}`,
+		);
+		mkdirSync(outDir, { recursive: true });
+		return bundleAgentCoreAsset(backendModulePath, outDir);
+	}
+}

package/src/index.aws.ts

@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export { Agent } from './agent.aws.js';
+// Exported so api-extractor can resolve the (protected, @internal) dispatchTurn signature; the type
+// itself is @internal — not part of the public API (customers use stream()/resume()).
+export type { AgentTurnPayload } from './agent.js';
 export { AgentErrors, InterruptError } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
 export type { AgentConfig, AgentResult, AgentStreamChunk, AgentStreamResult, ToolDefinition, AgentTool, ToolFactory, ToolsConfig, ToolHandlerArgs, DefaultToolContext, InterruptResponse, ToolCallRecord, ModelConfig, StreamOptions, Message, Conversation, JSONValue, TokenUsage } from './types.js';