@go-to-k/cdkd 0.190.0 → 0.191.0

package/dist/cli.js

@@ -62,8 +62,8 @@ import { CreateVectorBucketCommand, DeleteIndexCommand, DeleteVectorBucketComman
 import { CreateNamespaceCommand, CreateTableBucketCommand, CreateTableCommand as CreateTableCommand$2, DeleteNamespaceCommand as DeleteNamespaceCommand$1, DeleteTableBucketCommand, DeleteTableCommand as DeleteTableCommand$2, GetTableBucketCommand, GetTableCommand as GetTableCommand$1, ListNamespacesCommand as ListNamespacesCommand$1, ListTableBucketsCommand, ListTablesCommand as ListTablesCommand$1, ListTagsForResourceCommand as ListTagsForResourceCommand$19, NotFoundException as NotFoundException$5, S3TablesClient } from "@aws-sdk/client-s3tables";
 import { AttachLoadBalancerTargetGroupsCommand, AttachLoadBalancersCommand, AttachTrafficSourcesCommand, AutoScalingClient, CreateAutoScalingGroupCommand, CreateOrUpdateTagsCommand, DeleteAutoScalingGroupCommand, DeleteLifecycleHookCommand, DeleteNotificationConfigurationCommand, DeleteTagsCommand as DeleteTagsCommand$1, DescribeAutoScalingGroupsCommand, DescribeLifecycleHooksCommand, DescribeNotificationConfigurationsCommand, DescribeTrafficSourcesCommand, DetachLoadBalancerTargetGroupsCommand, DetachLoadBalancersCommand, DetachTrafficSourcesCommand, DisableMetricsCollectionCommand, EnableMetricsCollectionCommand, PutLifecycleHookCommand, PutNotificationConfigurationCommand, UpdateAutoScalingGroupCommand } from "@aws-sdk/client-auto-scaling";
 import { Document, Pair, Scalar, YAMLMap, YAMLSeq, parse as parse$1, stringify } from "yaml";
-import { createLocalStateProvider, isCfnFlagPresent, rejectExplicitCfnStackWithMultipleStacks, setEmbedConfig, substituteAgainstState, substituteAgainstStateAsync, substituteEnvVarsFromState, substituteEnvVarsFromStateAsync } from "cdk-local";
-import { CloudMapRegistry, ConnectionRegistry, EcsTaskResolutionError, HOST_GATEWAY_MIN_VERSION, LocalInvokeBuildError, architectureToPlatform, attachAuthorizers, attachStageContext, availableApiIdentifiers, bufferToBody, buildCloudMapIndex, buildCognitoJwksUrl, buildConnectEvent, buildContainerImage, buildCorsConfigByApiId, buildCorsConfigFromCloudFrontChain, buildDisconnectEvent, buildJwksUrlFromIssuer, buildMessageEvent, buildMgmtEndpointEnvUrl, buildStageMap, createAuthorizerCache, createFileWatcher, createJwksCache, createWatchPredicates, defaultCredentialsLoader, derivePseudoParametersFromRegion, discoverRoutes, discoverWebSocketApis, filterRoutesByApiIdentifier, getContainerNetworkIp, groupRoutesByServer, handleConnectionsRequest, materializeLayerFromArn, parseConnectionsPath, parseSelectionExpressionPath, probeHostGatewaySupport, readMtlsMaterialsFromDisk, resolveEnvVars, resolveRuntimeCodeMountPath, resolveRuntimeFileExtension, resolveRuntimeImage, resolveWatchConfig, startApiServer, substituteImagePlaceholders, tryResolveImageFnJoin } from "cdk-local/internal";
+import { createLocalStateProvider, getEmbedConfig, isCfnFlagPresent, listTargets, rejectExplicitCfnStackWithMultipleStacks, resolveCfnFallbackRegion, setEmbedConfig, substituteAgainstState, substituteAgainstStateAsync, substituteEnvVarsFromState, substituteEnvVarsFromStateAsync } from "cdk-local";
+import { A2A_CONTAINER_PORT, A2A_PATH, AGENTCORE_A2A_PROTOCOL, AGENTCORE_AGUI_PROTOCOL, AGENTCORE_MCP_PROTOCOL, CloudMapRegistry, ConnectionRegistry, EcsTaskResolutionError, HOST_GATEWAY_MIN_VERSION, LocalInvokeBuildError, MCP_CONTAINER_PORT, MCP_PATH, a2aInvokeOnce, architectureToPlatform, attachAuthorizers, attachStageContext, availableApiIdentifiers, bufferToBody, buildAgentCoreCodeImage, buildCloudMapIndex, buildCognitoJwksUrl, buildConnectEvent, buildContainerImage, buildCorsConfigByApiId, buildCorsConfigFromCloudFrontChain, buildDisconnectEvent, buildJwksUrlFromIssuer, buildMessageEvent, buildMgmtEndpointEnvUrl, buildStageMap, createAuthorizerCache, createFileWatcher, createJwksCache, createWatchPredicates, defaultCredentialsLoader, derivePseudoParametersFromRegion, discoverRoutes, discoverWebSocketApis, downloadAndExtractS3Bundle, filterRoutesByApiIdentifier, getContainerNetworkIp, groupRoutesByServer, handleConnectionsRequest, invokeAgentCore, invokeAgentCoreWs, materializeLayerFromArn, mcpInvokeOnce, parseConnectionsPath, parseSelectionExpressionPath, pickAgentCoreCandidateStack, probeHostGatewaySupport, readMtlsMaterialsFromDisk, resolveAgentCoreTarget, resolveEnvVars, resolveRuntimeCodeMountPath, resolveRuntimeFileExtension, resolveRuntimeImage, resolveSingleTarget, resolveWatchConfig, signAgentCoreInvocation, startApiServer, substituteImagePlaceholders, tryResolveImageFnJoin, verifyJwtViaDiscovery, waitForAgentCorePing } from "cdk-local/internal";
 import { createServer } from "node:net";
 import { promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -44392,7 +44392,7 @@ async function runDetached(opts) {
 	if (opts.platform) args.push("--platform", opts.platform);
 	if (opts.extraHosts) for (const entry of opts.extraHosts) args.push("--add-host", `${entry.host}:${entry.ip}`);
 	const host = opts.host ?? "127.0.0.1";
-	args.push("-p", `${host}:${opts.hostPort}:8080`);
+	args.push("-p", `${host}:${opts.hostPort}:${opts.containerPort ?? 8080}`);
 	if (opts.debugPort !== void 0) args.push("-p", `${host}:${opts.debugPort}:${opts.debugPort}`);
 	for (const mount of opts.mounts) {
 		const ro = mount.readOnly ? ":ro" : "";
@@ -44402,7 +44402,12 @@ async function runDetached(opts) {
 		const ro = mount.readOnly ? ":ro" : "";
 		args.push("-v", `${mount.hostPath}:${mount.containerPath}${ro}`);
 	}
-	for (const [k, v] of Object.entries(opts.env)) args.push("-e", `${k}=${v}`);
+	const sensitiveKeys = opts.sensitiveEnvKeys && opts.sensitiveEnvKeys.size > 0 ? new Set([...SENSITIVE_ENV_KEYS, ...opts.sensitiveEnvKeys]) : SENSITIVE_ENV_KEYS;
+	const passthroughEnv = {};
+	for (const [k, v] of Object.entries(opts.env)) if (sensitiveKeys.has(k)) {
+		args.push("-e", k);
+		passthroughEnv[k] = v;
+	} else args.push("-e", `${k}=${v}`);
 	if (opts.tmpfs) args.push("--tmpfs", `${opts.tmpfs.target}:rw,size=${opts.tmpfs.sizeMb}m`);
 	if (opts.workingDir) args.push("--workdir", opts.workingDir);
 	let entryPointTail = [];
@@ -44413,7 +44418,13 @@ async function runDetached(opts) {
 	args.push(opts.image, ...entryPointTail, ...opts.cmd);
 	getLogger().child("docker").debug(`${getDockerCmd()} ${redactAwsCredentialsInArgs(args).join(" ")}`);
 	try {
-		const { stdout } = await execFileAsync$3(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$3(getDockerCmd(), args, {
+			maxBuffer: 10 * 1024 * 1024,
+			env: {
+				...process.env,
+				...passthroughEnv
+			}
+		});
 		return stdout.trim();
 	} catch (error) {
 		const err = error;
@@ -44521,6 +44532,22 @@ const REDACTED_ENV_KEYS = new Set([
 	"AWS_SESSION_TOKEN"
 ]);
 /**
+* Built-in sensitive env keys whose VALUES are always routed through
+* docker's value-from-process-env form (`-e KEY` rather than
+* `-e KEY=value`) by {@link runDetached}. Mirrors the redaction-only
+* {@link REDACTED_ENV_KEYS} set above, but stronger: the value is kept
+* off the docker `run` argv (and therefore off `ps` / `/proc/<pid>/cmdline`
+* / verbose debug logs) instead of just being masked at log time. A caller
+* may extend this set via the `sensitiveEnvKeys` option (used by the
+* AgentCore local-invoke path to keep decrypted `--from-cfn-stack`
+* SecureString SSM values off the argv).
+*/
+const SENSITIVE_ENV_KEYS = new Set([
+	"AWS_ACCESS_KEY_ID",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_SESSION_TOKEN"
+]);
+/**
 * Returns a copy of `args` with any `-e <KEY>=<value>` pair whose KEY is
 * in {@link REDACTED_ENV_KEYS} replaced with `-e <KEY>=***`. The actual
 * `args` passed to `spawn` are never mutated — this is for log output
@@ -46070,7 +46097,7 @@ async function localStartApiCommand(target, options) {
 	await ensureDockerAvailable();
 	const appCmd = resolveApp(options.app);
 	if (!appCmd) throw new Error("No CDK app specified. Pass --app, set CDKD_APP, or add \"app\" to cdk.json.");
-	const overrides = readEnvOverridesFile$3(options.envVars);
+	const overrides = readEnvOverridesFile$4(options.envVars);
 	const debugPortBase = options.debugPortBase ? parseDebugPort(options.debugPortBase) : void 0;
 	const perLambdaConcurrency = parsePerLambdaConcurrency(options.perLambdaConcurrency);
 	const inlineTmpDirs = /* @__PURE__ */ new Set();
@@ -46689,7 +46716,7 @@ async function buildContainerSpec(args) {
 		dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
 		if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
 	} else {
-		forwardAwsEnv$1(dockerEnv);
+		forwardAwsEnv$2(dockerEnv);
 		if (profileCredentials) {
 			dockerEnv["AWS_ACCESS_KEY_ID"] = profileCredentials.accessKeyId;
 			dockerEnv["AWS_SECRET_ACCESS_KEY"] = profileCredentials.secretAccessKey;
@@ -47036,7 +47063,7 @@ function getTemplateEnv$1(resource) {
 	return vars;
 }
 /** Read the SAM-shape `--env-vars` JSON file. */
-function readEnvOverridesFile$3(filePath) {
+function readEnvOverridesFile$4(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -47058,7 +47085,7 @@ function readEnvOverridesFile$3(filePath) {
 * handler's AWS SDK calls can authenticate. Used when --assume-role is
 * NOT set for that Lambda — SAM-compatible default.
 */
-function forwardAwsEnv$1(env) {
+function forwardAwsEnv$2(env) {
 	for (const key of [
 		"AWS_ACCESS_KEY_ID",
 		"AWS_SECRET_ACCESS_KEY",
@@ -48429,7 +48456,7 @@ async function localRunTaskCommand(target, options) {
 		}
 		const sidecarCredentials = await resolveSidecarCredentials(options, assumedCredentials);
 		if (options.profile && sidecarCredentials && !assumedCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, sidecarCredentials);
-		const envOverrides = readEnvOverridesFile$2(options.envVars);
+		const envOverrides = readEnvOverridesFile$3(options.envVars);
 		const runOpts = {
 			cluster: options.cluster,
 			containerHost: options.containerHost,
@@ -48529,7 +48556,7 @@ async function buildEcsImageResolutionContext$1(candidate, stateProvider, option
 		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
 		let accountId;
 		try {
-			accountId = await resolveCallerAccountId$1(region);
+			accountId = await resolveCallerAccountId$2(region);
 		} catch (err) {
 			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
 		}
@@ -48559,7 +48586,7 @@ function pickCandidateStack$1(stackPattern, stacks) {
 	const matched = matchStacks(stacks, [stackPattern]);
 	if (matched.length === 1) return matched[0];
 }
-async function resolveCallerAccountId$1(region) {
+async function resolveCallerAccountId$2(region) {
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
 	try {
@@ -48573,7 +48600,7 @@ async function resolveCallerAccountId$1(region) {
 * `cdkd local invoke --env-vars`: top-level keys are container names, with
 * `Parameters` reserved for global entries.
 */
-function readEnvOverridesFile$2(filePath) {
+function readEnvOverridesFile$3(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -49488,7 +49515,7 @@ async function runOneTarget(target, runState, stacks, options, discovery, skipPu
 		resolvedRoleArn = options.assumeTaskRole;
 		assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
 	}
-	const envOverrides = readEnvOverridesFile$1(options.envVars);
+	const envOverrides = readEnvOverridesFile$2(options.envVars);
 	const taskOpts = {
 		cluster: options.cluster,
 		containerHost: options.containerHost,
@@ -49564,7 +49591,7 @@ async function buildEcsImageResolutionContext(target, stacks, options, stateProv
 		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
 		let accountId;
 		try {
-			accountId = await resolveCallerAccountId(region);
+			accountId = await resolveCallerAccountId$1(region);
 		} catch (err) {
 			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
 		}
@@ -49594,7 +49621,7 @@ function pickCandidateStack(stackPattern, stacks) {
 	const matched = matchStacks(stacks, [stackPattern]);
 	if (matched.length === 1) return matched[0];
 }
-async function resolveCallerAccountId(region) {
+async function resolveCallerAccountId$1(region) {
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
 	try {
@@ -49603,7 +49630,7 @@ async function resolveCallerAccountId(region) {
 		sts.destroy();
 	}
 }
-function readEnvOverridesFile$1(filePath) {
+function readEnvOverridesFile$2(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -49693,6 +49720,812 @@ function createLocalStartServiceCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/local-invoke-agentcore.ts
+/**
+* Parser for `--timeout <ms>`. Accepts a positive integer; rejects 0,
+* negatives, fractions, and non-numeric input.
+*/
+function parseTimeoutMs(raw) {
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new CdkdError(`--timeout must be a positive integer number of milliseconds (got '${raw}').`, "LOCAL_INVOKE_AGENTCORE_TIMEOUT_INVALID");
+	return parsed;
+}
+/**
+* `cdkd local invoke-agentcore <target>` — run a Bedrock AgentCore Runtime container
+* locally and invoke it once over the AgentCore HTTP contract. Resolves
+* the `AWS::BedrockAgentCore::Runtime`, pulls / builds its container,
+* starts it on port 8080, waits for `GET /ping`, POSTs the event to
+* `POST /invocations`, prints the response, and tears down. Covers the
+* container artifact and the CodeConfiguration managed-runtime artifact
+* (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent's
+* calls to real AWS go to real AWS (credentials injected like `cdkd local invoke`).
+*/
+async function localInvokeAgentCoreCommand(target, options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	let containerId;
+	let stopLogs;
+	let sigintHandler;
+	let profileCredsFile;
+	let stateProvider;
+	const cleanup = singleFlight(async () => {
+		if (stateProvider) try {
+			stateProvider.dispose();
+		} catch (err) {
+			getLogger().debug(`state provider dispose failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (stopLogs) try {
+			stopLogs();
+		} catch (err) {
+			getLogger().debug(`streamLogs stop failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (containerId) try {
+			await removeContainer(containerId);
+		} catch (err) {
+			getLogger().debug(`removeContainer(${containerId}) failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (profileCredsFile) try {
+			await profileCredsFile.dispose();
+		} catch (err) {
+			getLogger().debug(`Failed to remove profile credentials tmpdir ${profileCredsFile.hostPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}, (err) => {
+		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+	});
+	try {
+		await applyRoleArnIfSet({
+			roleArn: options.roleArn,
+			region: options.region
+		});
+		await ensureDockerAvailable();
+		const profileCredentials = options.profile ? await resolveProfileCredentials(options.profile) : void 0;
+		if (options.profile && profileCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, profileCredentials);
+		const appCmd = resolveApp(options.app);
+		if (!appCmd) throw new CdkdError(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`, "LOCAL_INVOKE_AGENTCORE_NO_APP");
+		logger.info("Synthesizing CDK app...");
+		const synthesizer = new Synthesizer();
+		const context = parseContextOptions(options.context);
+		const synthOpts = {
+			app: appCmd,
+			output: options.output,
+			...options.region && { region: options.region },
+			...options.profile && { profile: options.profile },
+			...Object.keys(context).length > 0 && { context }
+		};
+		const { stacks } = await synthesizer.synthesize(synthOpts);
+		const resolvedTarget = await resolveSingleTarget(target, {
+			entries: listTargets(stacks).agentCoreRuntimes,
+			message: "Select an AgentCore Runtime to invoke",
+			noun: "AgentCore Runtimes",
+			onMissing: () => new CdkdError(`${getEmbedConfig().cliName} invoke-agentcore requires a <target> (an AgentCore Runtime display path or logical ID). Run \`${getEmbedConfig().cliName} list\` to see them, or run it in a TTY to pick interactively.`, "LOCAL_INVOKE_AGENTCORE_TARGET_REQUIRED")
+		});
+		const candidate = pickAgentCoreCandidateStack(resolvedTarget, stacks);
+		stateProvider = createLocalStateProvider$1(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region));
+		const { context: imageContext, loaded: loadedState } = stateProvider && candidate ? await buildAgentCoreImageContext(candidate, stateProvider, options) : {
+			context: void 0,
+			loaded: void 0
+		};
+		const resolved = resolveAgentCoreTarget(resolvedTarget, stacks, imageContext);
+		logger.info(`Target: ${resolved.stack.stackName}/${resolved.logicalId} (${resolved.protocol})`);
+		const isMcp = resolved.protocol === AGENTCORE_MCP_PROTOCOL;
+		const isA2a = resolved.protocol === AGENTCORE_A2A_PROTOCOL;
+		if (resolved.protocol === AGENTCORE_AGUI_PROTOCOL) logger.info("AGUI runtime: routing through the HTTP /invocations + /ws path (AG-UI wire is SSE / WebSocket on port 8080).");
+		if ((isMcp || isA2a) && options.ws) logger.warn(`--ws applies only to the HTTP / AGUI protocols; ignoring it for this ${resolved.protocol} runtime.`);
+		if (options.wsInteractive && !options.ws) logger.warn("--ws-interactive is meaningful only with --ws; ignoring.");
+		if (options.sigv4 && (isMcp || isA2a || options.ws)) logger.warn("--sigv4 signs the HTTP /invocations request only; ignoring it for the " + (isMcp ? "MCP" : isA2a ? "A2A" : "/ws WebSocket") + " path.");
+		const sessionId = options.sessionId ?? randomUUID();
+		const event = await readEvent$1(options);
+		const mcpRequest = isMcp ? buildMcpRequest(event) : void 0;
+		const a2aRequest = isA2a ? buildA2aRequest(event) : void 0;
+		let authorization;
+		if (isMcp || isA2a) {
+			if (resolved.jwtAuthorizer || options.bearerToken) {
+				const pathLabel = isMcp ? MCP_PATH : A2A_PATH;
+				logger.info(`${resolved.protocol} runtime: invoking the local container's ${pathLabel} directly (vanilla ${resolved.protocol}). An inbound JWT / --bearer-token is an AgentCore managed-plane concern and is not applied locally.`);
+			}
+		} else authorization = await resolveInboundAuthorization(resolved, options);
+		await resolveFromS3BucketIntrinsic(resolved, stateProvider, loadedState, imageContext);
+		const image = await resolveAgentCoreImage(resolved, options, loadedState);
+		const { env: dockerEnv, sensitiveEnvKeys } = await buildContainerEnv(resolved, options, profileCredentials, profileCredsFile, stateProvider, loadedState, imageContext);
+		const hostPort = await pickFreePort();
+		const containerHost = options.containerHost;
+		const containerName = `${getEmbedConfig().resourceNamePrefix}-agentcore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+		const containerPort = isMcp ? MCP_CONTAINER_PORT : isA2a ? A2A_CONTAINER_PORT : void 0;
+		const containerPortLabel = isMcp ? `${MCP_CONTAINER_PORT}${MCP_PATH}` : isA2a ? `${A2A_CONTAINER_PORT}${A2A_PATH}` : "8080";
+		logger.info(`Starting agent container (image=${image}, port=${hostPort} -> ${containerPortLabel})...`);
+		containerId = await runDetached({
+			image,
+			mounts: [],
+			env: dockerEnv,
+			cmd: [],
+			hostPort,
+			host: containerHost,
+			platform: options.platform,
+			name: containerName,
+			...containerPort !== void 0 && { containerPort },
+			...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
+		});
+		stopLogs = streamLogs(containerId);
+		sigintHandler = () => {
+			cleanup().then(() => process.exit(130));
+		};
+		process.on("SIGINT", sigintHandler);
+		if (isMcp && mcpRequest) {
+			logger.info(`MCP request: ${mcpRequest.method}`);
+			const mcp = await mcpInvokeOnce(containerHost, hostPort, mcpRequest, { requestTimeoutMs: options.timeout });
+			await new Promise((r) => setTimeout(r, 250));
+			emitMcpResult(mcp);
+		} else if (isA2a && a2aRequest) {
+			logger.info(`A2A request: ${a2aRequest.method}`);
+			const a2a = await a2aInvokeOnce(containerHost, hostPort, a2aRequest, { requestTimeoutMs: options.timeout });
+			await new Promise((r) => setTimeout(r, 250));
+			emitA2aResult(a2a);
+		} else if (options.ws) {
+			await waitForAgentCorePing(containerHost, hostPort);
+			const frameSource = options.wsInteractive ? readStdinLines() : void 0;
+			logger.info(options.wsInteractive ? "Opening the agent /ws WebSocket (interactive — stdin lines = follow-up frames; Ctrl-D to end)..." : "Opening the agent /ws WebSocket and streaming frames...");
+			const wsResult = await invokeAgentCoreWs(containerHost, hostPort, event, {
+				sessionId,
+				timeoutMs: options.timeout,
+				onMessage: (text) => process.stdout.write(text),
+				...authorization && { authorization },
+				...frameSource && { frameSource }
+			});
+			await new Promise((r) => setTimeout(r, 250));
+			emitWsResult(wsResult);
+		} else {
+			await waitForAgentCorePing(containerHost, hostPort);
+			const additionalHeaders = await buildSigV4HeadersIfRequested(options, resolved, loadedState, containerHost, hostPort, event, sessionId);
+			const result = await invokeAgentCore(containerHost, hostPort, event, {
+				sessionId,
+				timeoutMs: options.timeout,
+				onChunk: (text) => process.stdout.write(text),
+				...authorization && { authorization },
+				...additionalHeaders && { additionalHeaders }
+			});
+			await new Promise((r) => setTimeout(r, 250));
+			emitResult(result);
+		}
+	} finally {
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		await cleanup();
+	}
+}
+/**
+* Enforce the runtime's inbound JWT authorizer (when declared) and return
+* the `Authorization` header to forward to `/invocations`.
+*
+* - No authorizer → forward the token verbatim if one was given (no-op
+*   otherwise).
+* - `--no-verify-auth` → warn + forward without verifying (local-dev escape).
+* - Authorizer + no token → reject (AgentCore returns 401).
+* - Authorizer + token → verify against the OIDC discovery URL; reject on
+*   failure (AgentCore returns 403); forward on success. An unreachable
+*   discovery URL falls back to pass-through accept (offline-dev fallback in
+*   {@link verifyJwtViaDiscovery}).
+*
+* Exported so a unit test can drive the gate without the full Docker pipeline.
+*/
+async function resolveInboundAuthorization(resolved, options) {
+	const logger = getLogger();
+	const authorizer = resolved.jwtAuthorizer;
+	const header = options.bearerToken ? `Bearer ${options.bearerToken}` : void 0;
+	if (!authorizer) return header;
+	if (options.verifyAuth === false) {
+		logger.warn(`Runtime '${resolved.logicalId}' declares a customJwtAuthorizer, but --no-verify-auth was set — skipping inbound JWT verification (local-dev escape hatch).`);
+		return header;
+	}
+	if (!header) throw new CdkdError(`Runtime '${resolved.logicalId}' requires an inbound JWT (customJwtAuthorizer). Pass --bearer-token <jwt>, or --no-verify-auth to skip verification for local dev.`, "LOCAL_INVOKE_AGENTCORE_AUTH_REQUIRED");
+	if (!(await verifyJwtViaDiscovery({
+		discoveryUrl: authorizer.discoveryUrl,
+		...authorizer.allowedAudience && { allowedAudience: authorizer.allowedAudience },
+		...authorizer.allowedClients && { allowedClients: authorizer.allowedClients },
+		...authorizer.allowedScopes && { allowedScopes: authorizer.allowedScopes },
+		...authorizer.customClaims && { customClaims: authorizer.customClaims }
+	}, header, createJwksCache(), { warned: /* @__PURE__ */ new Set() })).allow) throw new CdkdError(`Inbound JWT rejected by the runtime's customJwtAuthorizer (signature / issuer / expiry / audience check failed against ${authorizer.discoveryUrl}).`, "LOCAL_INVOKE_AGENTCORE_AUTH_DENIED");
+	logger.info(`Inbound JWT verified against ${authorizer.discoveryUrl}.`);
+	return header;
+}
+/**
+* Compute the SigV4 headers for the `/invocations` POST when `--sigv4` is
+* requested. Returns `undefined` (no header overlay) when:
+*
+* - `--sigv4` is not set,
+* - the runtime declares a `customJwtAuthorizer` (the JWT path wins; warns),
+*
+* Throws a {@link CdkdError} when `--sigv4` conflicts with
+* `--bearer-token`, or when no AWS credentials are resolvable for signing.
+*
+* Exported so a unit test can drive the gate without the full Docker pipeline.
+*/
+async function buildSigV4HeadersIfRequested(options, resolved, loaded, host, port, event, sessionId) {
+	if (!options.sigv4) return void 0;
+	if (options.bearerToken) throw new CdkdError(`--sigv4 and --bearer-token are mutually exclusive: pick one inbound auth.`, "LOCAL_INVOKE_AGENTCORE_AUTH_CONFLICT");
+	if (resolved.jwtAuthorizer) {
+		getLogger().warn(`Runtime '${resolved.logicalId}' declares a customJwtAuthorizer; --sigv4 ignored (JWT path takes precedence).`);
+		return;
+	}
+	const region = options.region ?? options.stackRegion ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? resolved.stack.region;
+	if (!region) throw new CdkdError("--sigv4: no region resolved for the AgentCore signing scope. Pass --region <region>, set AWS_REGION, or use --from-cfn-stack with a region-bound stack.", "LOCAL_INVOKE_AGENTCORE_SIGV4_NO_REGION");
+	const signed = await signAgentCoreInvocation({
+		credentials: await resolveHostCredentialsForSigV4(options, resolved, loaded, region),
+		region,
+		host,
+		port,
+		path: "/invocations",
+		body: JSON.stringify(event ?? {}),
+		sessionId
+	});
+	const headers = {
+		Authorization: signed.authorization,
+		"X-Amz-Date": signed.amzDate,
+		"X-Amz-Content-Sha256": signed.amzContentSha256
+	};
+	if (signed.amzSecurityToken) headers["X-Amz-Security-Token"] = signed.amzSecurityToken;
+	getLogger().info(`Signed /invocations with SigV4 (region=${region}).`);
+	return headers;
+}
+/**
+* Resolve credentials for host-side SigV4 signing. Precedence:
+*   1. `--assume-role` → STS temp creds (warn + fall through on STS failure);
+*   2. `--profile` → profile creds (sessionToken when the profile carries one);
+*   3. shell env (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / optional
+*      `AWS_SESSION_TOKEN`).
+*
+* Throws a {@link CdkdError} when none are available — `--sigv4` cannot
+* proceed without credentials, unlike the unsigned path.
+*/
+async function resolveHostCredentialsForSigV4(options, resolved, loaded, region) {
+	const logger = getLogger();
+	const assumeRoleArn = resolveAssumeRoleArn(options, resolved, loaded);
+	if (assumeRoleArn) try {
+		return await assumeAgentCoreExecutionRole(assumeRoleArn, region);
+	} catch (err) {
+		logger.warn(`--assume-role: STS AssumeRole(${assumeRoleArn}) failed for --sigv4 signing: ${err instanceof Error ? err.message : String(err)}. Falling back to ${options.profile ? `--profile ${options.profile}` : "shell credentials"}.`);
+	}
+	if (options.profile) {
+		const creds = await resolveProfileCredentials(options.profile);
+		if (creds?.accessKeyId && creds.secretAccessKey) return {
+			accessKeyId: creds.accessKeyId,
+			secretAccessKey: creds.secretAccessKey,
+			...creds.sessionToken && { sessionToken: creds.sessionToken }
+		};
+	}
+	const accessKeyId = process.env["AWS_ACCESS_KEY_ID"];
+	const secretAccessKey = process.env["AWS_SECRET_ACCESS_KEY"];
+	if (accessKeyId && secretAccessKey) {
+		const sessionToken = process.env["AWS_SESSION_TOKEN"];
+		return {
+			accessKeyId,
+			secretAccessKey,
+			...sessionToken && { sessionToken }
+		};
+	}
+	throw new CdkdError("--sigv4: no AWS credentials available to sign the request. Set AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, pass --profile <name>, or pass --assume-role <arn>.", "LOCAL_INVOKE_AGENTCORE_SIGV4_NO_CREDENTIALS");
+}
+/**
+* Acquire the agent image. A CODE artifact (managed runtime) is built from
+* source — a fromCodeAsset bundle from its cdk.out asset, a fromS3 bundle
+* downloaded + extracted from S3. A CONTAINER artifact mirrors the
+* container-Lambda path: build from a local cdk.out asset when the URI matches
+* one, else pull from ECR, else pull a plain registry image.
+*
+* `loaded` is the `--from-cfn-stack` state record (when available) — threaded
+* through so a bare `--assume-role` can resolve the execution-role ARN from
+* state for the fromS3 download.
+*/
+async function resolveAgentCoreImage(resolved, options, loaded) {
+	const logger = getLogger();
+	const architecture = platformToArchitecture(options.platform);
+	if (resolved.codeArtifact) return resolveAgentCoreCodeImage(resolved, resolved.codeArtifact, options, architecture, loaded);
+	const containerUri = resolved.containerUri;
+	if (containerUri === void 0) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' has neither a container image nor a code artifact to run.`, "LOCAL_INVOKE_AGENTCORE_NO_ARTIFACT");
+	const manifestPath = resolved.stack.assetManifestPath;
+	if (manifestPath) {
+		const cdkOutDir = dirname(manifestPath);
+		const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, resolved.stack.stackName);
+		if (manifest) {
+			const entry = getDockerImageBySourceHash(manifest, containerUri);
+			if (entry) return buildContainerImage$1(entry.asset, cdkOutDir, {
+				architecture,
+				noBuild: options.build === false
+			});
+		}
+	}
+	if (parseEcrUri(containerUri)) {
+		logger.info(`Pulling agent image from ECR: ${containerUri}`);
+		return pullEcrImage(containerUri, {
+			skipPull: options.pull === false,
+			...options.region !== void 0 && { region: options.region },
+			...options.ecrRoleArn !== void 0 && { ecrRoleArn: options.ecrRoleArn },
+			...options.profile !== void 0 && { profile: options.profile }
+		});
+	}
+	await pullImage(containerUri, options.pull === false);
+	return containerUri;
+}
+/**
+* Build a local image from a `CodeConfiguration` (managed-runtime) bundle.
+*
+* - fromS3 (`code.s3Source` set, a literal S3 object): download + extract the
+*   bundle, then run the from-source build over the extracted dir.
+* - fromCodeAsset: locate the source dir in cdk.out via its asset hash, then
+*   run the same from-source build (generated Dockerfile → install deps → run
+*   EntryPoint).
+*/
+async function resolveAgentCoreCodeImage(resolved, code, options, architecture, loaded) {
+	if (code.s3Source) return resolveAgentCoreCodeImageFromS3(resolved, code, code.s3Source, options, architecture, loaded);
+	const manifestPath = resolved.stack.assetManifestPath;
+	if (!manifestPath) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' uses a code artifact, but its stack has no asset manifest in cdk.out to read the bundle source from.`, "LOCAL_INVOKE_AGENTCORE_CODE_NO_MANIFEST");
+	const cdkOutDir = dirname(manifestPath);
+	const loader = new AssetManifestLoader();
+	const manifest = await loader.loadManifest(cdkOutDir, resolved.stack.stackName);
+	const fileAssets = manifest ? loader.getFileAssets(manifest) : void 0;
+	const asset = fileAssets ? fileAssets.get(code.codeAssetHash) ?? findFileAssetByObjectKey(fileAssets, code.codeAssetHash) : void 0;
+	if (!asset) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' code bundle (asset ${code.codeAssetHash}) was not found in the cdk.out asset manifest. ${getEmbedConfig().cliName} invoke-agentcore runs a local from-source build of a fromCodeAsset bundle — re-synthesize the app so the asset is staged in cdk.out and retry. (A fromS3 bundle is downloaded from S3 instead; this runtime has no literal Code.S3.Bucket.)`, "LOCAL_INVOKE_AGENTCORE_CODE_ASSET_NOT_FOUND");
+	const sourceDir = loader.getAssetSourcePath(cdkOutDir, asset);
+	if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' code bundle source '${sourceDir}' does not exist or is not a directory. Re-synthesize the app and retry.`, "LOCAL_INVOKE_AGENTCORE_CODE_SOURCE_MISSING");
+	return buildAgentCoreCodeImage({
+		sourceDir,
+		runtime: code.runtime,
+		entryPoint: code.entryPoint,
+		architecture,
+		noBuild: options.build === false
+	});
+}
+/**
+* Build a local image from a fromS3 CodeConfiguration bundle: download +
+* extract the S3 object, run the from-source build over the extracted dir, then
+* clean up the temp dir.
+*
+* Credentials mirror the rest of the command: an `--assume-role` ARN (explicit,
+* or resolved from `--from-cfn-stack` state for the bare form) yields STS temp
+* creds for the download; otherwise `--profile` / the default chain is used.
+* The region is `--region` / `--stack-region` / env / the stack's region.
+*/
+async function resolveAgentCoreCodeImageFromS3(resolved, code, s3Source, options, architecture, loaded) {
+	const logger = getLogger();
+	if (typeof s3Source.bucket !== "string" || s3Source.bucket.length === 0) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' fromS3 bundle reached the image step with no literal bucket. This is a cdkd bug — please report it.`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_UNRESOLVED");
+	const location = {
+		bucket: s3Source.bucket,
+		key: s3Source.key,
+		...s3Source.versionId !== void 0 && { versionId: s3Source.versionId }
+	};
+	const region = options.region ?? options.stackRegion ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? resolved.stack.region;
+	const assumeRoleArn = resolveAssumeRoleArn(options, resolved, loaded);
+	let credentials;
+	if (assumeRoleArn) try {
+		credentials = await assumeAgentCoreExecutionRole(assumeRoleArn, region);
+	} catch (err) {
+		logger.warn(`--assume-role: STS AssumeRole(${assumeRoleArn}) failed for the fromS3 bundle download: ${err instanceof Error ? err.message : String(err)}. Falling back to ${options.profile ? `--profile ${options.profile}` : "the default credentials"}.`);
+	}
+	const bundle = await downloadAndExtractS3Bundle(location, {
+		...region !== void 0 && { region },
+		...options.profile !== void 0 && { profile: options.profile },
+		...credentials !== void 0 && { credentials }
+	});
+	try {
+		return await buildAgentCoreCodeImage({
+			sourceDir: bundle.dir,
+			runtime: code.runtime,
+			entryPoint: code.entryPoint,
+			architecture,
+			noBuild: options.build === false
+		});
+	} finally {
+		await bundle.cleanup();
+	}
+}
+/**
+* Find the file asset whose destination objectKey is `<hash>.zip` (matching the
+* `Code.S3.Prefix`'s hash) when the source-hash-keyed lookup misses — covers a
+* synthesizer whose source hash differs from the destination objectKey.
+*/
+function findFileAssetByObjectKey(fileAssets, hash) {
+	const zip = `${hash}.zip`;
+	for (const asset of fileAssets.values()) if (Object.values(asset.destinations).some((d) => d.objectKey === zip || d.objectKey.endsWith(`/${zip}`))) return asset;
+}
+/**
+* Build the container env + the set of env keys to keep off the `docker run`
+* argv. Substitutes `--from-cfn-stack` state into the template env (reusing the
+* shared state load + image-resolution context — Ref / Fn::Sub / Fn::Join +
+* SSM parameters, with decrypted SecureString values flagged sensitive),
+* applies `--env-vars` overrides, then injects AWS credentials (`--assume-role`
+* STS temp creds — resolving an intrinsic RoleArn from state for bare
+* `--assume-role` — else `--profile` / dev creds).
+*
+* The state provider + loaded record + image context are built once by the
+* caller and shared here, so this does not re-load state.
+*/
+async function buildContainerEnv(resolved, options, profileCredentials, profileCredsFile, stateProvider, loaded, imageContext) {
+	const logger = getLogger();
+	let templateEnv = resolved.environmentVariables;
+	const sensitiveEnvKeys = /* @__PURE__ */ new Set();
+	if (stateProvider && loaded) {
+		const subContext = {
+			resources: imageContext?.stateResources ?? loaded.resources,
+			consumerRegion: loaded.region
+		};
+		const pseudo = imageContext?.pseudoParameters ?? derivePseudoParametersFromRegion(loaded.region);
+		if (pseudo) subContext.pseudoParameters = pseudo;
+		if (imageContext?.stateParameters) subContext.parameters = imageContext.stateParameters;
+		if (imageContext?.stateSensitiveParameters?.length) subContext.sensitiveParameters = new Set(imageContext.stateSensitiveParameters);
+		const resolver = await stateProvider.buildCrossStackResolver(loaded.region);
+		if (resolver) subContext.crossStackResolver = resolver;
+		const { env, audit } = await substituteEnvVarsFromStateAsync(templateEnv, subContext);
+		templateEnv = env;
+		for (const key of audit.resolvedKeys) logger.debug(`${stateProvider.label}: substituted env var ${key}`);
+		for (const key of audit.sensitiveKeys) sensitiveEnvKeys.add(key);
+		for (const { key, reason } of audit.unresolved) logger.warn(`${stateProvider.label}: could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
+	}
+	const overrides = readEnvOverridesFile$1(options.envVars);
+	const cdkPath = readCdkPathOrUndefined(resolved.resource);
+	const envResult = resolveEnvVars(resolved.logicalId, cdkPath, templateEnv, overrides);
+	for (const key of envResult.unresolved) {
+		const overrideKeyExample = cdkPath?.replace(/\/Resource$/, "") ?? resolved.logicalId;
+		logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}), or pass a state-source flag (e.g. --from-cfn-stack) to recover deployed values.`);
+	}
+	const dockerEnv = { ...envResult.resolved };
+	const assumeRoleArn = resolveAssumeRoleArn(options, resolved, loaded);
+	await applyAgentCoreCredentialEnv(dockerEnv, {
+		...assumeRoleArn !== void 0 && { assumeRoleArn },
+		...options.region !== void 0 && { region: options.region },
+		...profileCredentials !== void 0 && { profileCredentials },
+		...profileCredsFile !== void 0 && { profileCredsFile: {
+			containerPath: profileCredsFile.containerPath,
+			profileName: profileCredsFile.profileName
+		} }
+	});
+	return {
+		env: dockerEnv,
+		sensitiveEnvKeys
+	};
+}
+/**
+* Resolve a fromS3 bundle's intrinsic `Code.S3.Bucket` to a literal bucket
+* name in place on `resolved.codeArtifact.s3Source.bucket`. Uses the SAME
+* state-substitution machinery env vars use under `--from-cfn-stack`, so
+* every cross-stack intrinsic that path supports (`Ref` / `Fn::ImportValue` /
+* `Fn::GetStackOutput`) is supported transparently here.
+*
+* No-op when there is no intrinsic to resolve. Errors when no state is
+* available, or when the substitution returns a non-string / unresolved value.
+*
+* Exported so a unit test can drive the gate without the full Docker pipeline.
+*/
+async function resolveFromS3BucketIntrinsic(resolved, stateProvider, loaded, imageContext) {
+	const s3Source = resolved.codeArtifact?.s3Source;
+	if (!s3Source || s3Source.bucketIntrinsic === void 0) return;
+	if (s3Source.bucket !== void 0) return;
+	if (!stateProvider || !loaded) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' fromS3 bundle's Code.S3.Bucket is an unresolved intrinsic (${describeIntrinsic(s3Source.bucketIntrinsic)}). Pass --from-cfn-stack so its physical bucket name can be resolved against the deployed stack state.`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_INTRINSIC_NO_STATE");
+	const subContext = {
+		resources: imageContext?.stateResources ?? loaded.resources,
+		consumerRegion: loaded.region
+	};
+	const pseudo = imageContext?.pseudoParameters ?? derivePseudoParametersFromRegion(loaded.region);
+	if (pseudo) subContext.pseudoParameters = pseudo;
+	const crossStackResolver = await stateProvider.buildCrossStackResolver(loaded.region);
+	if (crossStackResolver) subContext.crossStackResolver = crossStackResolver;
+	const result = await substituteAgainstStateAsync(s3Source.bucketIntrinsic, subContext);
+	if (result.kind !== "literal") throw new CdkdError(`Could not resolve AgentCore Runtime '${resolved.logicalId}' fromS3 Code.S3.Bucket intrinsic (${describeIntrinsic(s3Source.bucketIntrinsic)}) against the --from-cfn-stack state: ${result.reason}. Confirm the referenced resource / export exists in the deployed stack.`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_INTRINSIC_UNRESOLVED");
+	if (typeof result.value !== "string" || result.value.length === 0) throw new CdkdError(`AgentCore Runtime '${resolved.logicalId}' fromS3 Code.S3.Bucket intrinsic resolved to a ${typeof result.value} value, not a bucket name string. (${describeIntrinsic(s3Source.bucketIntrinsic)})`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_INTRINSIC_NOT_STRING");
+	s3Source.bucket = result.value;
+	getLogger().info(`Resolved fromS3 Code.S3.Bucket from state: ${describeIntrinsic(s3Source.bucketIntrinsic)} -> ${result.value}`);
+}
+/** Render the intrinsic key for an error / log message (e.g. `Ref:Bucket1`). */
+function describeIntrinsic(value) {
+	if (!value || typeof value !== "object") return String(value);
+	const obj = value;
+	const key = Object.keys(obj)[0] ?? "?";
+	const arg = obj[key];
+	if (typeof arg === "string") return `${key}:${arg}`;
+	return key;
+}
+/**
+* Build the `--from-cfn-stack` image-resolution context + return the loaded
+* state record (loaded once, reused by env substitution + role resolution).
+* Mirrors `run-task`'s `buildEcsImageResolutionContext`: pseudo parameters
+* (region + STS account id), the deployed resources, and SSM template
+* parameters (decrypted SecureString logical ids flagged sensitive).
+*/
+async function buildAgentCoreImageContext(candidate, stateProvider, options) {
+	const logger = getLogger();
+	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
+	let accountId;
+	try {
+		accountId = await resolveCallerAccountId(region, options.profile);
+	} catch (err) {
+		logger.warn(`--from-cfn-stack: STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. A same-stack ECR image URI referencing \${AWS::AccountId} may not resolve.`);
+	}
+	const context = {};
+	const pseudo = derivePseudoParametersFromRegion(region, accountId);
+	if (pseudo) context.pseudoParameters = pseudo;
+	const loaded = await stateProvider.load(candidate.stackName, candidate.region);
+	if (loaded) {
+		context.stateResources = loaded.resources;
+		if (stateProvider.resolveTemplateSsmParameters) {
+			const ssm = await stateProvider.resolveTemplateSsmParameters(candidate.template);
+			if (Object.keys(ssm.values).length > 0) context.stateParameters = ssm.values;
+			if (ssm.secureStringLogicalIds.length > 0) context.stateSensitiveParameters = ssm.secureStringLogicalIds;
+		}
+	}
+	return {
+		context,
+		loaded: loaded ?? void 0
+	};
+}
+/** STS `GetCallerIdentity` for the `${AWS::AccountId}` pseudo parameter (threads `--profile`). */
+async function resolveCallerAccountId(region, profile) {
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({
+		...region && { region },
+		...profile && { profile }
+	});
+	try {
+		return (await sts.send(new GetCallerIdentityCommand({}))).Account;
+	} finally {
+		sts.destroy();
+	}
+}
+/**
+* Inject AWS credentials into the container env. Precedence:
+*   1. `--assume-role` → STS-issued temp creds for the resolved ARN (on
+*      STS failure, warn + fall through to dev creds).
+*   2. dev shell creds (`forwardAwsEnv`) + `--profile` overlay
+*      ({@link applyProfileCredentialsOverlay}) + the bind-mounted
+*      credentials-file env so handler `fromIni({ profile })` resolves.
+*
+* Exported so a unit test can lock the binding (mock STS) without driving
+* the full synth + docker pipeline.
+*/
+async function applyAgentCoreCredentialEnv(dockerEnv, args) {
+	const logger = getLogger();
+	let assumeSucceeded = false;
+	if (args.assumeRoleArn) {
+		const stsRegion = args.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"];
+		try {
+			const creds = await assumeAgentCoreExecutionRole(args.assumeRoleArn, stsRegion);
+			dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
+			dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
+			dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
+			if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
+			assumeSucceeded = true;
+		} catch (err) {
+			logger.warn(`--assume-role: STS AssumeRole(${args.assumeRoleArn}) failed: ${err instanceof Error ? err.message : String(err)}. Falling back to the developer's shell credentials.`);
+		}
+	}
+	if (!assumeSucceeded) {
+		forwardAwsEnv$1(dockerEnv);
+		applyProfileCredentialsOverlay(dockerEnv, args.profileCredentials, false);
+		if (args.profileCredsFile) {
+			dockerEnv["AWS_SHARED_CREDENTIALS_FILE"] = args.profileCredsFile.containerPath;
+			dockerEnv["AWS_PROFILE"] = args.profileCredsFile.profileName;
+		}
+	}
+}
+/**
+* Resolve the role ARN to assume, honoring the three `--assume-role` forms.
+* Bare `--assume-role` uses the runtime's literal `RoleArn`; when that is an
+* intrinsic (the common L2 case — `Fn::GetAtt` to an auto-created role) it
+* resolves the execution-role ARN from `--from-cfn-stack` state, and only
+* warns + falls back to dev creds when neither is available.
+*/
+function resolveAssumeRoleArn(options, resolved, loaded) {
+	if (typeof options.assumeRole === "string") return options.assumeRole;
+	if (options.assumeRole === true) {
+		if (resolved.roleArn) return resolved.roleArn;
+		if (loaded) {
+			const fromState = resolveExecutionRoleArnFromState(loaded, resolved.logicalId, "RoleArn");
+			if (fromState) {
+				getLogger().debug(`--assume-role: resolved RoleArn from state: ${fromState}`);
+				return fromState;
+			}
+		}
+		getLogger().warn("--assume-role passed without an ARN, but the runtime's RoleArn is not a literal ARN in the template " + (loaded ? "and could not be resolved from the deployed stack state. " : "and no --from-cfn-stack state is available to resolve it. ") + "Pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.");
+	}
+}
+function emitResult(result) {
+	const logger = getLogger();
+	if (result.status >= 400) {
+		logger.warn(`Agent /invocations returned HTTP ${result.status}.`);
+		process.exitCode = 1;
+	}
+	if (result.streamed) {
+		process.stdout.write("\n");
+		return;
+	}
+	process.stdout.write(`${result.raw}\n`);
+}
+/**
+* Finish a `/ws` exchange: the frames were already streamed to stdout via the
+* onMessage sink, so just terminate with a newline (so the shell prompt resumes
+* cleanly) and note the frame count at debug level.
+*/
+function emitWsResult(result) {
+	process.stdout.write("\n");
+	getLogger().debug(`Agent /ws closed after ${result.frames} frame(s).`);
+}
+/**
+* Build the JSON-RPC request to send to an MCP runtime from `--event`:
+*   - no `--event` (empty object) → `tools/list` (discover the server's tools),
+*   - an object with a string `method` → that method + its `params`,
+*   - anything else → a fail-fast error.
+*
+* Exported for unit testing.
+*/
+function buildMcpRequest(event) {
+	if (event === void 0 || event === null) return {
+		method: "tools/list",
+		params: {}
+	};
+	if (typeof event !== "object" || Array.isArray(event)) throw new CdkdError("MCP --event must be a JSON object describing a JSON-RPC request (e.g. {\"method\":\"tools/call\",\"params\":{\"name\":\"...\",\"arguments\":{...}}}).", "LOCAL_INVOKE_AGENTCORE_MCP_EVENT_INVALID");
+	const obj = event;
+	if (Object.keys(obj).length === 0) return {
+		method: "tools/list",
+		params: {}
+	};
+	if (typeof obj["method"] !== "string") throw new CdkdError(`MCP --event must include a string "method" (a JSON-RPC method such as "tools/list" or "tools/call"). Got keys: ${Object.keys(obj).join(", ")}.`, "LOCAL_INVOKE_AGENTCORE_MCP_EVENT_INVALID");
+	return {
+		method: obj["method"],
+		...obj["params"] !== void 0 && { params: obj["params"] }
+	};
+}
+/** Print the MCP JSON-RPC response; exit 1 when it carried a JSON-RPC error. */
+function emitMcpResult(result) {
+	if (!result.ok) {
+		getLogger().warn("MCP server returned a JSON-RPC error.");
+		process.exitCode = 1;
+	}
+	process.stdout.write(`${result.raw}\n`);
+}
+/**
+* Build the JSON-RPC request to send to an A2A runtime from `--event`:
+*   - no `--event` (empty object) → `agent/getCard` (discover the agent's card),
+*   - an object with a string `method` → that method + its `params`,
+*   - anything else → a fail-fast error.
+*
+* Exported for unit testing.
+*/
+function buildA2aRequest(event) {
+	if (event === void 0 || event === null) return {
+		method: "agent/getCard",
+		params: {}
+	};
+	if (typeof event !== "object" || Array.isArray(event)) throw new CdkdError("A2A --event must be a JSON object describing a JSON-RPC request (e.g. {\"method\":\"tasks/send\",\"params\":{\"id\":\"...\",\"message\":{...}}}).", "LOCAL_INVOKE_AGENTCORE_A2A_EVENT_INVALID");
+	const obj = event;
+	if (Object.keys(obj).length === 0) return {
+		method: "agent/getCard",
+		params: {}
+	};
+	if (typeof obj["method"] !== "string") throw new CdkdError(`A2A --event must include a string "method" (a JSON-RPC method such as "agent/getCard" or "tasks/send"). Got keys: ${Object.keys(obj).join(", ")}.`, "LOCAL_INVOKE_AGENTCORE_A2A_EVENT_INVALID");
+	return {
+		method: obj["method"],
+		...obj["params"] !== void 0 && { params: obj["params"] }
+	};
+}
+/** Print the A2A JSON-RPC response; exit 1 when it carried a JSON-RPC error. */
+function emitA2aResult(result) {
+	if (!result.ok) {
+		getLogger().warn("A2A server returned a JSON-RPC error.");
+		process.exitCode = 1;
+	}
+	process.stdout.write(`${result.raw}\n`);
+}
+/** Map a `--platform` value to the architecture `buildContainerImage` expects. */
+function platformToArchitecture(platform) {
+	return platform === "linux/amd64" ? "x86_64" : "arm64";
+}
+function forwardAwsEnv$1(env) {
+	for (const key of [
+		"AWS_ACCESS_KEY_ID",
+		"AWS_SECRET_ACCESS_KEY",
+		"AWS_SESSION_TOKEN",
+		"AWS_REGION",
+		"AWS_DEFAULT_REGION"
+	]) {
+		const value = process.env[key];
+		if (value !== void 0) env[key] = value;
+	}
+}
+async function assumeAgentCoreExecutionRole(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-invoke-agentcore-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new CdkdError(`AssumeRole(${roleArn}) returned no usable credentials.`, "LOCAL_INVOKE_AGENTCORE_ASSUMEROLE_NO_CREDS");
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
+	}
+}
+async function readEvent$1(options) {
+	if (options.event && options.eventStdin) throw new CdkdError("--event and --event-stdin are mutually exclusive.", "LOCAL_INVOKE_AGENTCORE_EVENT_FLAG_CONFLICT");
+	if (options.eventStdin) return parseEvent$1(await readStdin$1(), "<stdin>");
+	if (options.event) {
+		let raw;
+		try {
+			raw = readFileSync(options.event, "utf-8");
+		} catch (err) {
+			throw new CdkdError(`Failed to read --event file '${options.event}': ${err instanceof Error ? err.message : String(err)}`, "LOCAL_INVOKE_AGENTCORE_EVENT_READ_FAILED");
+		}
+		return parseEvent$1(raw, options.event);
+	}
+	return {};
+}
+function parseEvent$1(raw, source) {
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new CdkdError(`Failed to parse event payload from ${source} as JSON: ${err instanceof Error ? err.message : String(err)}`, "LOCAL_INVOKE_AGENTCORE_EVENT_PARSE_FAILED");
+	}
+}
+async function readStdin$1() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf-8");
+}
+/**
+* Read `process.stdin` line-buffered and yield each line as a string (trailing
+* `\r?\n` stripped). The async iterable completes when stdin EOFs (Ctrl-D /
+* end-of-pipe), and surrenders the underlying stream when its `return()` is
+* called — so the WS client can close down the source when the server closes
+* first without leaving stdin held open.
+*
+* Exported so a unit test can drive the iterable shape directly.
+*/
+async function* readStdinLines() {
+	const { createInterface } = await import("node:readline");
+	const rl = createInterface({
+		input: process.stdin,
+		crlfDelay: Infinity
+	});
+	try {
+		for await (const line of rl) yield line;
+	} finally {
+		rl.close();
+	}
+}
+function readEnvOverridesFile$1(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new CdkdError(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`, "LOCAL_INVOKE_AGENTCORE_ENV_VARS_READ_FAILED");
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new CdkdError(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`, "LOCAL_INVOKE_AGENTCORE_ENV_VARS_PARSE_FAILED");
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CdkdError(`--env-vars file '${filePath}' must contain a JSON object at the top level.`, "LOCAL_INVOKE_AGENTCORE_ENV_VARS_NOT_OBJECT");
+	return parsed;
+}
+function createLocalInvokeAgentCoreCommand() {
+	const cmd = new Command("invoke-agentcore").description("Run a Bedrock AgentCore Runtime container locally and invoke it once over its protocol contract: HTTP (POST /invocations + GET /ping on 8080) or MCP (POST /mcp Streamable HTTP on 8000). Resolves the AWS::BedrockAgentCore::Runtime, pulls/builds its container, injects env vars + AWS credentials, and prints the response. For an MCP runtime, runs the session handshake then sends one JSON-RPC request (tools/list by default, or the method/params from --event). Target accepts a CDK display path (MyStack/MyAgent) or stack-qualified logical ID (MyStack:MyAgentRuntime1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick from a list. Supports the container artifact and the CodeConfiguration managed-runtime artifact (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent calls real AWS for managed services.").argument("[target]", "CDK display path or stack-qualified logical ID of the AgentCore Runtime to invoke (omit to pick interactively in a TTY)").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--session-id <id>", "AgentCore runtime session id header value (default: a random UUID)")).addOption(new Option("--ws", "Stream over the HTTP-protocol agent's bidirectional /ws WebSocket endpoint (on 8080) instead of POST /invocations: send --event as the first frame and print every received frame to stdout until the agent closes. Ignored for an MCP runtime.").default(false)).addOption(new Option("--ws-interactive", "REPL mode for --ws: after the initial --event frame, read additional frames from stdin (one frame per line, trailing newline stripped) and send each as a text frame until stdin EOFs (Ctrl-D) or the agent closes. Only meaningful with --ws.").default(false)).addOption(new Option("--bearer-token <jwt>", "Bearer JWT to present when the runtime declares a customJwtAuthorizer. Verified against the runtime OIDC discovery URL (signature / issuer / expiry / audience) before the container starts, then forwarded to /invocations as Authorization: Bearer <jwt>.")).addOption(new Option("--no-verify-auth", "Skip inbound JWT verification even when the runtime declares a customJwtAuthorizer (local-dev escape hatch). A --bearer-token, if given, is still forwarded.")).addOption(new Option("--sigv4", "Sign the /invocations POST with AWS SigV4 (service bedrock-agentcore) using the resolved credentials, matching the cloud default when the runtime declares no customJwtAuthorizer. Opt-in: default unsigned. Mutually exclusive with --bearer-token; ignored on a JWT-protected runtime.").default(false)).addOption(new Option("--platform <platform>", "docker --platform for the agent container (linux/amd64 or linux/arm64)").choices(["linux/amd64", "linux/arm64"]).default("linux/arm64")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for the local-build path")).addOption(new Option("--no-build", "Skip docker build on the local-asset path (use the previously-built tag). No-op for the ECR / registry pull paths.")).addOption(new Option("--container-host <host>", "Host to bind the agent port to").default("127.0.0.1")).addOption(new Option("--timeout <ms>", "Per-request timeout in milliseconds. Applied to POST /invocations, POST /mcp, and the /ws open-to-close window. Raise this for long-running agent calls that exceed the default.").default(12e4).argParser(parseTimeoutMs)).addOption(new Option("--assume-role [arn]", "Assume the runtime's execution role and forward STS-issued temp credentials to the container so the agent runs with the deployed role. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) uses the runtime's RoleArn when it is a literal ARN; (3) `--no-assume-role` opts out. Off by default — the developer's shell credentials are forwarded unchanged.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Load cdkd's S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::ImportValue in env vars with the deployed physical IDs / cross-stack exports. Mutually exclusive with --from-cfn-stack.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. For CDK apps deployed via the upstream CDK CLI. Bare form uses the resolved stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state.")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).action(withErrorHandling(async (target, options) => {
+		await localInvokeAgentCoreCommand(target, options);
+	}));
+	[
+		...commonOptions,
+		...appOptions,
+		...contextOptions,
+		...stateOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
 //#endregion
 //#region src/cli/commands/local-invoke.ts
 /**
@@ -50447,10 +51280,10 @@ function suggestAssumeRoleFromState(state, logicalId) {
 *
 * Exported for unit testing.
 */
-function resolveExecutionRoleArnFromState(state, logicalId) {
+function resolveExecutionRoleArnFromState(state, logicalId, roleProperty = "Role") {
 	const lambda = state.resources[logicalId];
 	if (!lambda) return void 0;
-	const roleRef = lambda.properties?.["Role"] ?? lambda.observedProperties?.["Role"];
+	const roleRef = lambda.properties?.[roleProperty] ?? lambda.observedProperties?.[roleProperty];
 	if (typeof roleRef === "string" && roleRef.startsWith("arn:")) return roleRef;
 	if (typeof roleRef === "object" && roleRef !== null) {
 		const refLogicalId = pickReferencedLogicalId(roleRef);
@@ -50495,6 +51328,7 @@ function createLocalCommand() {
 	local.addCommand(createLocalStartApiCommand());
 	local.addCommand(createLocalRunTaskCommand());
 	local.addCommand(createLocalStartServiceCommand());
+	local.addCommand(createLocalInvokeAgentCoreCommand());
 	return local;
 }
 
@@ -51607,7 +52441,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.190.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.191.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());