@go-to-k/cdkd 0.205.0 → 0.207.0

package/dist/cli.js

@@ -24,7 +24,7 @@ import { ACMClient, AddTagsToCertificateCommand, DeleteCertificateCommand, Descr
 import * as fs from "node:fs";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { AssociateVPCWithHostedZoneCommand, ChangeResourceRecordSetsCommand, ChangeTagsForResourceCommand, CreateHostedZoneCommand, CreateQueryLoggingConfigCommand, DeleteHostedZoneCommand, DeleteQueryLoggingConfigCommand, DisassociateVPCFromHostedZoneCommand, GetHostedZoneCommand, ListHostedZonesByNameCommand, ListHostedZonesCommand, ListQueryLoggingConfigsCommand, ListResourceRecordSetsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$6, Route53Client, UpdateHostedZoneCommentCommand, UpdateHostedZoneFeaturesCommand } from "@aws-sdk/client-route-53";
@@ -62,7 +62,7 @@ import { CreateNamespaceCommand, CreateTableBucketCommand, CreateTableCommand as
 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, 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, ConnectionRegistry, EcsTaskResolutionError, HOST_GATEWAY_MIN_VERSION, LocalInvokeBuildError, MCP_CONTAINER_PORT, MCP_PATH, a2aInvokeOnce, addAlbSpecificOptions, addCommonEcsServiceOptions, addStartServiceSpecificOptions, albStrategy, architectureToPlatform, attachAuthorizers, attachStageContext, availableApiIdentifiers, bufferToBody, buildAgentCoreCodeImage, buildCognitoJwksUrl, buildConnectEvent, buildContainerImage, buildCorsConfigByApiId, buildCorsConfigFromCloudFrontChain, buildDisconnectEvent, buildJwksUrlFromIssuer, buildMessageEvent, buildMgmtEndpointEnvUrl, buildStageMap, createAuthorizerCache, createFileWatcher, createJwksCache, createWatchPredicates, defaultCredentialsLoader, derivePseudoParametersFromRegion, discoverRoutes, discoverWebSocketApis, downloadAndExtractS3Bundle, filterRoutesByApiIdentifier, groupRoutesByServer, handleConnectionsRequest, invokeAgentCore, invokeAgentCoreWs, materializeLayerFromArn, mcpInvokeOnce, parseConnectionsPath, parseSelectionExpressionPath, pickAgentCoreCandidateStack, probeHostGatewaySupport, readMtlsMaterialsFromDisk, resolveAgentCoreTarget, resolveEnvVars, resolveRuntimeCodeMountPath, resolveRuntimeFileExtension, resolveRuntimeImage, resolveSingleTarget, resolveWatchConfig, runEcsServiceEmulator, signAgentCoreInvocation, startApiServer, substituteImagePlaceholders, tryResolveImageFnJoin, verifyJwtViaDiscovery, waitForAgentCorePing } from "cdk-local/internal";
+import { A2A_CONTAINER_PORT, A2A_PATH, AGENTCORE_A2A_PROTOCOL, AGENTCORE_AGUI_PROTOCOL, AGENTCORE_MCP_PROTOCOL, ConnectionRegistry, EcsTaskResolutionError, HOST_GATEWAY_MIN_VERSION, LocalInvokeBuildError, MCP_CONTAINER_PORT, MCP_PATH, a2aInvokeOnce, addAlbSpecificOptions, addCommonEcsServiceOptions, addStartServiceSpecificOptions, albStrategy, architectureToPlatform, attachAuthorizers, attachStageContext, availableApiIdentifiers, bufferToBody, buildAgentCoreCodeImage, buildCognitoJwksUrl, buildConnectEvent, buildContainerImage, buildCorsConfigByApiId, buildCorsConfigFromCloudFrontChain, buildDisconnectEvent, buildJwksUrlFromIssuer, buildMessageEvent, buildMgmtEndpointEnvUrl, buildStageMap, classifySourceChange, createAuthorizerCache, createFileWatcher, createFileWatcher as createFileWatcher$1, createJwksCache, createWatchPredicates, defaultCredentialsLoader, derivePseudoParametersFromRegion, discoverRoutes, discoverWebSocketApis, downloadAndExtractS3Bundle, filterRoutesByApiIdentifier, groupRoutesByServer, handleConnectionsRequest, invokeAgentCore, invokeAgentCoreWs, materializeLayerFromArn, mcpInvokeOnce, parseConnectionsPath, parseSelectionExpressionPath, pickAgentCoreCandidateStack, pickAgentCoreCandidateStack as pickAgentCoreCandidateStack$1, probeHostGatewaySupport, readMtlsMaterialsFromDisk, resolveAgentCoreTarget, resolveEnvVars, resolveRuntimeCodeMountPath, resolveRuntimeFileExtension, resolveRuntimeImage, resolveSingleTarget, resolveWatchConfig, runEcsServiceEmulator, 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";
@@ -44891,7 +44891,7 @@ async function applyCrossStackResolverToTask(task, context) {
 
 //#endregion
 //#region src/local/docker-runner.ts
-const execFileAsync$3 = promisify(execFile);
+const execFileAsync$4 = promisify(execFile);
 /**
 * Wraps `docker pull` / `docker run` / `docker rm` for `cdkd local invoke`.
 *
@@ -44989,7 +44989,7 @@ 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, {
+		const { stdout } = await execFileAsync$4(getDockerCmd(), args, {
 			maxBuffer: 10 * 1024 * 1024,
 			env: {
 				...process.env,
@@ -45032,7 +45032,7 @@ async function removeContainer(containerId) {
 	if (!containerId) return;
 	const logger = getLogger().child("docker");
 	try {
-		await execFileAsync$3(getDockerCmd(), [
+		await execFileAsync$4(getDockerCmd(), [
 			"rm",
 			"-f",
 			containerId
@@ -45051,7 +45051,7 @@ async function removeContainer(containerId) {
 async function ensureDockerAvailable() {
 	const cmd = getDockerCmd();
 	try {
-		await execFileAsync$3(cmd, [
+		await execFileAsync$4(cmd, [
 			"version",
 			"--format",
 			"{{.Server.Version}}"
@@ -46952,7 +46952,7 @@ async function localStartApiCommand(target, options) {
 			output: options.output,
 			watchConfig: resolveWatchConfig()
 		});
-		watcher = createFileWatcher({
+		watcher = createFileWatcher$1({
 			paths: [watchRoot],
 			ignored,
 			shouldTrigger,
@@ -48122,7 +48122,7 @@ function createLocalStartApiCommand() {
 
 //#endregion
 //#region src/local/ecs-network.ts
-const execFileAsync$2 = promisify(execFile);
+const execFileAsync$3 = promisify(execFile);
 /**
 * Docker network + AWS-published metadata-endpoints sidecar lifecycle for
 * `cdkd local run-task`. The sidecar (a small Go binary maintained by
@@ -48175,7 +48175,7 @@ async function createNetworkAndSidecar(args) {
 	await pullImage(METADATA_ENDPOINT_IMAGE, skipPull);
 	logger.info(`Creating docker network ${networkName} (subnet ${cidr})...`);
 	try {
-		await execFileAsync$2(getDockerCmd(), [
+		await execFileAsync$3(getDockerCmd(), [
 			"network",
 			"create",
 			"--driver",
@@ -48210,7 +48210,7 @@ async function createNetworkAndSidecar(args) {
 	sidecarArgs.push(METADATA_ENDPOINT_IMAGE);
 	logger.info(`Starting ECS local-container-endpoints sidecar at ${sidecarIp}...`);
 	try {
-		const { stdout } = await execFileAsync$2(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$3(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
 		return stdout.trim();
 	} catch (err) {
 		await destroyNetworkOnly(networkName);
@@ -48278,7 +48278,7 @@ async function destroyNetworkOnly(networkName) {
 	if (!networkName) return;
 	const logger = getLogger().child("ecs-network");
 	try {
-		await execFileAsync$2(getDockerCmd(), [
+		await execFileAsync$3(getDockerCmd(), [
 			"network",
 			"rm",
 			networkName
@@ -48411,7 +48411,7 @@ async function resolveSsm(entry, shape, client) {
 
 //#endregion
 //#region src/local/ecs-task-runner.ts
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync$2 = promisify(execFile);
 /**
 * Top-level orchestrator for `cdkd local run-task`. Coordinates image
 * preparation, secret resolution, docker-network bring-up, container
@@ -48471,7 +48471,7 @@ async function cleanupEcsRun(state, options) {
 	if (state.network && !state.network.ownedByCaller) await destroyTaskNetwork(state.network);
 	state.network = void 0;
 	for (const v of state.dockerVolumeNames) try {
-		await execFileAsync$1(getDockerCmd(), [
+		await execFileAsync$2(getDockerCmd(), [
 			"volume",
 			"rm",
 			v
@@ -48547,7 +48547,7 @@ async function runEcsTask(task, options, state) {
 		logger.info(`Starting container '${container.name}' (image=${imagePlan.get(container.name)})`);
 		let id;
 		try {
-			const { stdout } = await execFileAsync$1(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+			const { stdout } = await execFileAsync$2(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
 			id = stdout.trim();
 		} catch (err) {
 			const e = err;
@@ -48656,7 +48656,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 	let lastStatus = "";
 	while (Date.now() < deadline) {
 		try {
-			const { stdout } = await execFileAsync$1(getDockerCmd(), [
+			const { stdout } = await execFileAsync$2(getDockerCmd(), [
 				"inspect",
 				"--format",
 				"{{.State.Health.Status}}",
@@ -48679,7 +48679,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 }
 async function waitForContainerExit(containerId) {
 	try {
-		const { stdout } = await execFileAsync$1(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
+		const { stdout } = await execFileAsync$2(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
 		const code = Number.parseInt(stdout.trim(), 10);
 		return Number.isFinite(code) ? code : 1;
 	} catch (err) {
@@ -48689,7 +48689,7 @@ async function waitForContainerExit(containerId) {
 }
 async function stopContainer(containerId, graceSeconds) {
 	try {
-		await execFileAsync$1(getDockerCmd(), [
+		await execFileAsync$2(getDockerCmd(), [
 			"stop",
 			"-t",
 			String(graceSeconds),
@@ -48814,7 +48814,7 @@ async function realizeDockerVolumes(volumes, state) {
 		const dockerVolumeName = `cdkd-local-${v.name}-${randHex(4)}`;
 		args.push(dockerVolumeName);
 		try {
-			await execFileAsync$1(getDockerCmd(), args);
+			await execFileAsync$2(getDockerCmd(), args);
 			state.dockerVolumeNames.push(dockerVolumeName);
 			logger.debug(`Created docker volume ${dockerVolumeName} for task volume '${v.name}'`);
 		} catch (err) {
@@ -49280,6 +49280,292 @@ function createLocalStartServiceCommand() {
 	return addCommonEcsServiceOptions(cmd);
 }
 
+//#endregion
+//#region src/local/invoke-agentcore-watch-loop.ts
+/**
+* cdkd-owned `cdkd local invoke-agentcore --watch` reload loop.
+*
+* cdk-local PR #270's `runAgentCoreWatchLoop` hard-couples to cdk-local's OWN
+* `Synthesizer` / `LocalInvokeAgentCoreOptions` types, so it cannot be shimmed.
+* Instead this module re-implements the loop on top of cdk-local's already-
+* exported watch primitives (`createFileWatcher` / `createWatchPredicates` /
+* `resolveWatchConfig` / `classifySourceChange` + the `ReloadVerdict` /
+* `ReloadAssetContext` types) — the SAME pattern `cdkd local start-api --watch`
+* uses — and drives cdkd's OWN re-synth / image-build / docker pipeline through
+* the `rebuild` / `softReload` callbacks the command supplies.
+*
+* Behavior parity with cdk-local #270:
+*   - re-synth + reload the agent container on CDK source edits (watch the
+*     source tree, honoring `cdk.json` `watch.include` / `watch.exclude`);
+*   - per-firing classifier: an interpreted-language source edit inside a
+*     CodeConfiguration source tree takes a soft-reload FAST PATH (`docker cp`
+*     + `docker restart`, no rebuild); Dockerfile / compiled-source /
+*     asset-hash-changed / ambiguous edits force a full rebuild;
+*   - reload-chain serialization (no two reloads in parallel);
+*   - for the `--ws` session path: close the active socket cleanly on each
+*     reload (via the abort signal) and reopen against the new container;
+*   - for the default one-shot `/invocations` path: re-run the single shot
+*     after each reload (cdkd-specific — cdk-local treats single-shot as a
+*     no-op WARN).
+*/
+const execFileAsync$1 = promisify(execFile);
+/**
+* Run the `--watch` reload loop. Returns when the invocation closes naturally
+* with no pending reload (one-shot finished, or `--ws` agent closed), or when
+* a reload callback throws (the previous container may already be torn down,
+* so blocking on the next ping would hang). SIGINT runs the outer command's
+* cleanup + `process.exit`, so this loop is not the termination path on
+* user-initiated shutdown.
+*/
+async function runAgentCoreWatchLoop(args) {
+	const logger = getLogger();
+	const waitForPing = args.__waitForPing ?? waitForAgentCorePing;
+	let currentHostPort = args.hostPort;
+	let currentStacks = args.stacks;
+	let reloadChain = Promise.resolve();
+	let currentAbort;
+	let pendingReload = false;
+	let reloadFailed = false;
+	const watcherFactory = args.__watcherFactory ?? ((onChange) => {
+		const watchRoot = process.cwd();
+		const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
+			watchRoot,
+			output: args.options.output,
+			watchConfig: resolveWatchConfig()
+		});
+		logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
+		return createFileWatcher({
+			paths: [watchRoot],
+			ignored,
+			shouldTrigger,
+			onChange
+		});
+	});
+	const cdkOutDir = args.options.output;
+	const assetLoader = new AssetManifestLoader();
+	const watcher = watcherFactory((changedPaths) => {
+		reloadChain = reloadChain.then(async () => {
+			let verdict = {
+				kind: "rebuild",
+				reason: "classifier not consulted"
+			};
+			try {
+				let assetCtx;
+				if (args.__classifierContext) assetCtx = await args.__classifierContext(changedPaths);
+				else {
+					const { stacks: freshStacks } = await args.synthesizer.synthesize(args.synthOpts);
+					const oldAssetHash = await deriveOldAssetHash({
+						resolvedTarget: args.resolvedTarget,
+						resolved: args.resolved,
+						stacks: currentStacks,
+						cdkOutDir,
+						assetLoader
+					});
+					assetCtx = await loadAgentCoreAssetContext({
+						resolvedTarget: args.resolvedTarget,
+						resolved: args.resolved,
+						stacks: freshStacks,
+						cdkOutDir,
+						assetLoader,
+						...oldAssetHash !== void 0 && { oldAssetHash }
+					});
+				}
+				verdict = classifySourceChange(changedPaths, assetCtx);
+				logger.info(`Detected source change (${changedPaths.length} path(s)); verdict=${verdict.kind} (${verdict.reason}).`);
+			} catch (err) {
+				logger.warn(`Reload: classifier context unavailable (${err instanceof Error ? err.message : String(err)}); falling back to rebuild.`);
+				verdict = {
+					kind: "rebuild",
+					reason: "classifier context unavailable; falling back to rebuild"
+				};
+			}
+			pendingReload = true;
+			logger.warn("cdkd local invoke-agentcore --watch: source change detected; closing the active invocation so the client can reconnect to the rebuilt container.");
+			currentAbort?.abort();
+			try {
+				if (verdict.kind === "soft-reload") {
+					const { stacks: newStacks } = await args.softReload(verdict.newAssetSourceDir);
+					currentStacks = newStacks;
+					logger.info("Reload: soft-reloaded the agent container (docker cp + docker restart; container ID + host port preserved).");
+				} else {
+					const { hostPort: newHostPort, stacks: newStacks } = await args.rebuild();
+					currentHostPort = newHostPort;
+					currentStacks = newStacks;
+					logger.info(`Reload: rebuilt the agent container.`);
+				}
+			} catch (err) {
+				logger.error(`Reload failed: ${err instanceof Error ? err.message : String(err)}. The previous container may already be torn down; exiting --watch loop. Re-run cdkd local invoke-agentcore --watch to recover.`);
+				reloadFailed = true;
+				currentAbort?.abort();
+			}
+		}).catch((err) => {
+			logger.error(`Reload chain threw: ${err instanceof Error ? err.message : String(err)}`);
+		});
+	});
+	try {
+		let firstIteration = true;
+		while (true) {
+			if (reloadFailed) break;
+			await waitForPing(args.containerHost, currentHostPort);
+			const abort = new AbortController();
+			currentAbort = abort;
+			pendingReload = false;
+			try {
+				const outcome = await args.invokeOnce({
+					hostPort: currentHostPort,
+					abortSignal: abort.signal,
+					firstIteration
+				});
+				firstIteration = false;
+				if (outcome.pendingReload) pendingReload = true;
+			} finally {
+				currentAbort = void 0;
+			}
+			if (!pendingReload) {
+				await reloadChain.catch(() => void 0);
+				if (!pendingReload) break;
+			}
+			await reloadChain.catch(() => void 0);
+		}
+	} finally {
+		try {
+			await watcher.close();
+		} catch (err) {
+			logger.warn(`Watcher close failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+}
+/**
+* Soft-reload the agent container in place: `docker cp` the freshly-synthed
+* asset directory contents into the running container's WORKDIR + `docker
+* restart`.
+*
+* - WORKDIR is resolved from the live container's image config via
+*   `docker inspect --format '{{.Config.WorkingDir}}'`. An empty WORKDIR
+*   (Docker runtime default) maps to `/`. For CodeConfiguration runtimes the
+*   generated Dockerfile sets `WORKDIR /app`, so the copy lands there.
+* - The trailing `/.` on the source ensures CONTENTS are copied (not the
+*   directory itself); the trailing `/` on the dest forces docker cp to treat
+*   it as a directory.
+* - `docker restart` cycles PID 1 — the new source is picked up by the
+*   interpreted-language runtime on its next startup. The container ID + host
+*   port + network are preserved across the restart.
+*
+* @internal — exported for unit tests of the docker-cp + docker-restart shape
+* without standing up a real container.
+*/
+async function softReloadAgentContainer(containerId, newAssetSourceDir) {
+	const logger = getLogger();
+	const dockerCmd = getDockerCmd();
+	let workdir;
+	try {
+		const { stdout } = await execFileAsync$1(dockerCmd, [
+			"inspect",
+			"--format",
+			"{{.Config.WorkingDir}}",
+			containerId
+		]);
+		workdir = stdout.trim() || "/";
+	} catch (err) {
+		throw new CdkdError(`softReloadAgentContainer: docker inspect of container '${containerId}' failed: ${describeExecError(err)}.`, "LOCAL_INVOKE_AGENTCORE_WATCH_SOFT_RELOAD_INSPECT_FAILED");
+	}
+	const workdirDest = workdir.endsWith("/") ? workdir : `${workdir}/`;
+	logger.info(`Soft-reload: docker cp ${newAssetSourceDir} -> ${containerId}:${workdirDest}; restart.`);
+	try {
+		await execFileAsync$1(dockerCmd, [
+			"cp",
+			`${newAssetSourceDir}/.`,
+			`${containerId}:${workdirDest}`
+		], { maxBuffer: 64 * 1024 * 1024 });
+	} catch (err) {
+		throw new CdkdError(`softReloadAgentContainer: docker cp into '${containerId}:${workdir}' failed: ${describeExecError(err)}.`, "LOCAL_INVOKE_AGENTCORE_WATCH_SOFT_RELOAD_CP_FAILED");
+	}
+	try {
+		await execFileAsync$1(dockerCmd, ["restart", containerId]);
+	} catch (err) {
+		throw new CdkdError(`softReloadAgentContainer: docker restart of '${containerId}' failed: ${describeExecError(err)}.`, "LOCAL_INVOKE_AGENTCORE_WATCH_SOFT_RELOAD_RESTART_FAILED");
+	}
+}
+function describeExecError(err) {
+	if (!(err instanceof Error)) return String(err);
+	const stderr = err.stderr;
+	const stderrText = typeof stderr === "string" ? stderr.trim() : stderr instanceof Buffer ? stderr.toString("utf8").trim() : "";
+	return stderrText ? `${err.message}\n${stderrText}` : err.message;
+}
+/**
+* Build the per-firing classifier context for the agent container. Mirrors the
+* ECS service emulator's `loadAssetContextForTarget` shape: returns `undefined`
+* (and the classifier defaults to `'rebuild'`) when the runtime's image is not
+* a CDK docker-image asset, or when the asset manifest lookup misses.
+*
+* For a CodeConfiguration (`fromCodeAsset`) runtime we treat the bundle's
+* `codeAssetHash` as the asset hash + the staged source directory as
+* `newAssetSourceDir`, and synthesize a `Dockerfile` basename that never
+* matches a real file (the generated Dockerfile lives in a build tmpdir, not
+* the source tree, so chokidar can't observe an edit to it). A `fromS3` bundle
+* has no local source tree, so it returns `undefined` and the classifier
+* defaults to rebuild.
+*
+* NOTE: `loadAgentCoreAssetContext` is NOT exported from `cdk-local/internal`
+* (verified against `node_modules/cdk-local/dist/internal.d.ts`), so this
+* helper is copied locally; `deriveOldAssetHash` is copied for the same reason.
+*
+* @internal — exported for the watch loop's classifier dispatch test.
+*/
+async function loadAgentCoreAssetContext(args) {
+	const { resolvedTarget, resolved, stacks, cdkOutDir, assetLoader, oldAssetHash } = args;
+	const newCandidate = pickAgentCoreCandidateStack(resolvedTarget, stacks);
+	if (!newCandidate) return void 0;
+	if (resolved.codeArtifact) {
+		if (resolved.codeArtifact.s3Source) return void 0;
+		const manifest = await assetLoader.loadManifest(cdkOutDir, newCandidate.stackName);
+		if (!manifest) return void 0;
+		const asset = assetLoader.getFileAssets(manifest).get(resolved.codeArtifact.codeAssetHash);
+		if (!asset) return void 0;
+		const sourceDir = assetLoader.getAssetSourcePath(cdkOutDir, asset);
+		return {
+			...oldAssetHash !== void 0 && { oldAssetHash },
+			newAssetHash: resolved.codeArtifact.codeAssetHash,
+			newAssetSourceDir: sourceDir,
+			dockerFile: ".cdkd-agentcore-generated-Dockerfile"
+		};
+	}
+	if (resolved.containerUri === void 0) return void 0;
+	const manifest = await assetLoader.loadManifest(cdkOutDir, newCandidate.stackName);
+	if (!manifest) return void 0;
+	const dockerImageEntry = getDockerImageBySourceHash(manifest, resolved.containerUri);
+	if (!dockerImageEntry) return void 0;
+	const newDockerImage = dockerImageEntry.asset;
+	if (!newDockerImage.source.directory) return void 0;
+	const newAssetSourceDir = resolve(cdkOutDir, newDockerImage.source.directory);
+	return {
+		...oldAssetHash !== void 0 && { oldAssetHash },
+		newAssetHash: dockerImageEntry.hash,
+		newAssetSourceDir,
+		dockerFile: basename(newDockerImage.source.dockerFile ?? "Dockerfile")
+	};
+}
+/**
+* Derive the OLD (pre-reload) asset hash for the classifier's `oldAssetHash`
+* field. Code-artifact runtimes carry the hash on the boot-time
+* `resolved.codeArtifact.codeAssetHash`; container runtimes need a manifest
+* lookup against the previous-synth stacks to extract it. Returns `undefined`
+* when the OLD hash can't be derived — the classifier treats `undefined` as
+* "force rebuild", which is the conservative default.
+*
+* NOT exported from `cdk-local/internal`, so copied locally.
+*/
+async function deriveOldAssetHash(args) {
+	const { resolvedTarget, resolved, stacks, cdkOutDir, assetLoader } = args;
+	if (resolved.codeArtifact) return resolved.codeArtifact.codeAssetHash;
+	if (resolved.containerUri === void 0) return void 0;
+	const candidate = pickAgentCoreCandidateStack(resolvedTarget, stacks);
+	if (!candidate) return void 0;
+	const manifest = await assetLoader.loadManifest(cdkOutDir, candidate.stackName);
+	if (!manifest) return void 0;
+	return getDockerImageBySourceHash(manifest, resolved.containerUri)?.hash;
+}
+
 //#endregion
 //#region src/cli/commands/local-invoke-agentcore.ts
 /**
@@ -49361,7 +49647,7 @@ async function localInvokeAgentCoreCommand(target, options) {
 			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);
+		const candidate = pickAgentCoreCandidateStack$1(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,
@@ -49373,7 +49659,6 @@ async function localInvokeAgentCoreCommand(target, options) {
 		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);
@@ -49386,28 +49671,24 @@ async function localInvokeAgentCoreCommand(target, options) {
 				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 watchEligible = isAgentCoreWatchEligible(resolved.protocol);
+		const watchActive = options.watch === true && watchEligible;
+		if (options.watch === true && !watchEligible) logger.warn(`--watch is supported only on the HTTP / AGUI protocols; ignoring it for this ${resolved.protocol} runtime (its single shot runs once and exits).`);
 		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 }
+		const boot = await bootAgentCoreContainer({
+			resolved,
+			options,
+			profileCredentials,
+			profileCredsFile,
+			stateProvider,
+			loadedState,
+			imageContext,
+			isMcp,
+			isA2a
 		});
-		stopLogs = streamLogs(containerId);
+		containerId = boot.containerId;
+		const hostPort = boot.hostPort;
+		stopLogs = boot.stopLogs;
 		sigintHandler = () => {
 			cleanup().then(() => process.exit(130));
 		};
@@ -49423,19 +49704,146 @@ async function localInvokeAgentCoreCommand(target, options) {
 			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 }
+			const interactive = process.stdin.isTTY === true;
+			if (watchActive) await runAgentCoreWatchLoop({
+				containerHost,
+				hostPort,
+				options,
+				resolvedTarget,
+				resolved,
+				synthesizer,
+				synthOpts,
+				stacks,
+				invokeOnce: async ({ hostPort: port, abortSignal, firstIteration }) => {
+					const frameSource = interactive ? readStdinLines() : void 0;
+					logger.info(firstIteration ? interactive ? "Opening the agent /ws WebSocket (interactive — stdin lines = follow-up frames; Ctrl-D to end)..." : "Opening the agent /ws WebSocket and streaming frames..." : interactive ? "Re-opening the agent /ws WebSocket (interactive) against the rebuilt container..." : "Re-opening the agent /ws WebSocket against the rebuilt container...");
+					const wsResult = await invokeAgentCoreWs(containerHost, port, event, {
+						sessionId,
+						timeoutMs: options.timeout,
+						onMessage: wrapWsOnMessage((text) => process.stdout.write(text), interactive),
+						abortSignal,
+						...authorization && { authorization },
+						...frameSource && { frameSource }
+					});
+					await new Promise((r) => setTimeout(r, 250));
+					emitWsResult(wsResult);
+					return { pendingReload: abortSignal.aborted };
+				},
+				rebuild: async () => {
+					const result = await rebuildAgentCoreContainer({
+						cleanupBefore: async () => {
+							if (stopLogs) {
+								try {
+									stopLogs();
+								} catch {}
+								stopLogs = void 0;
+							}
+							if (containerId) {
+								await removeContainer(containerId);
+								containerId = void 0;
+							}
+						},
+						resolvedTarget,
+						options,
+						synthesizer,
+						synthOpts,
+						profileCredentials,
+						profileCredsFile,
+						stateProvider,
+						isMcp,
+						isA2a
+					});
+					containerId = result.containerId;
+					stopLogs = result.stopLogs;
+					return {
+						containerId: result.containerId,
+						hostPort: result.hostPort,
+						stacks: result.stacks
+					};
+				},
+				softReload: async (newSourceDir) => {
+					if (!containerId) throw new CdkdError("softReload: no live container to docker cp / docker restart into.", "LOCAL_INVOKE_AGENTCORE_WATCH_NO_CONTAINER");
+					await softReloadAgentContainer(containerId, newSourceDir);
+					const { stacks: newStacks } = await synthesizer.synthesize(synthOpts);
+					return { stacks: newStacks };
+				}
 			});
-			await new Promise((r) => setTimeout(r, 250));
-			emitWsResult(wsResult);
-		} else {
+			else {
+				await waitForAgentCorePing(containerHost, hostPort);
+				const frameSource = interactive ? readStdinLines() : void 0;
+				logger.info(interactive ? "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: wrapWsOnMessage((text) => process.stdout.write(text), interactive),
+					...authorization && { authorization },
+					...frameSource && { frameSource }
+				});
+				await new Promise((r) => setTimeout(r, 250));
+				emitWsResult(wsResult);
+			}
+		} else if (watchActive) await runAgentCoreWatchLoop({
+			containerHost,
+			hostPort,
+			options,
+			resolvedTarget,
+			resolved,
+			synthesizer,
+			synthOpts,
+			stacks,
+			invokeOnce: async ({ hostPort: port, abortSignal }) => {
+				const additionalHeaders = await buildSigV4HeadersIfRequested(options, resolved, loadedState, containerHost, port, event, sessionId);
+				const result = await invokeAgentCore(containerHost, port, event, {
+					sessionId,
+					timeoutMs: options.timeout,
+					onChunk: (text) => process.stdout.write(text),
+					...authorization && { authorization },
+					...additionalHeaders && { additionalHeaders }
+				});
+				await new Promise((r) => setTimeout(r, 250));
+				emitResult(result);
+				return { pendingReload: abortSignal.aborted };
+			},
+			rebuild: async () => {
+				const result = await rebuildAgentCoreContainer({
+					cleanupBefore: async () => {
+						if (stopLogs) {
+							try {
+								stopLogs();
+							} catch {}
+							stopLogs = void 0;
+						}
+						if (containerId) {
+							await removeContainer(containerId);
+							containerId = void 0;
+						}
+					},
+					resolvedTarget,
+					options,
+					synthesizer,
+					synthOpts,
+					profileCredentials,
+					profileCredsFile,
+					stateProvider,
+					isMcp,
+					isA2a
+				});
+				containerId = result.containerId;
+				stopLogs = result.stopLogs;
+				return {
+					containerId: result.containerId,
+					hostPort: result.hostPort,
+					stacks: result.stacks
+				};
+			},
+			softReload: async (newSourceDir) => {
+				if (!containerId) throw new CdkdError("softReload: no live container to docker cp / docker restart into.", "LOCAL_INVOKE_AGENTCORE_WATCH_NO_CONTAINER");
+				await softReloadAgentContainer(containerId, newSourceDir);
+				const { stacks: newStacks } = await synthesizer.synthesize(synthOpts);
+				return { stacks: newStacks };
+			}
+		});
+		else {
 			await waitForAgentCorePing(containerHost, hostPort);
 			const additionalHeaders = await buildSigV4HeadersIfRequested(options, resolved, loadedState, containerHost, hostPort, event, sessionId);
 			const result = await invokeAgentCore(containerHost, hostPort, event, {
@@ -49454,6 +49862,102 @@ async function localInvokeAgentCoreCommand(target, options) {
 	}
 }
 /**
+* `--watch` is supported only on the long-running HTTP / AGUI paths (the
+* `--ws` session AND the default one-shot `POST /invocations`, which the
+* reload re-runs). The MCP `POST /mcp` and A2A `POST /` paths run once and
+* exit with no reconnect surface, so `--watch` is a no-op WARN for them.
+*
+* Exported so a unit test can lock the eligibility contract without driving
+* the full synth + docker pipeline.
+*/
+function isAgentCoreWatchEligible(protocol) {
+	return protocol !== AGENTCORE_MCP_PROTOCOL && protocol !== AGENTCORE_A2A_PROTOCOL;
+}
+/**
+* Cold-boot (and rebuild) the agent container from an already-resolved runtime
+* descriptor: resolve an intrinsic fromS3 bucket, resolve the image, build the
+* container env, pick a free port, `docker run`, and start the log stream.
+*
+* Extracted from the main command so the `--watch` rebuild callback can re-run
+* the identical sequence against a fresh synth. The non-watch one-shot / `--ws`
+* paths and the watch loop both go through this helper, so the container boot
+* sequence is single-sourced.
+*
+* Exported so a unit test can drive the boot shape without the full command.
+*/
+async function bootAgentCoreContainer(args) {
+	const logger = getLogger();
+	const { resolved, options, profileCredentials, profileCredsFile, stateProvider, loadedState, imageContext, isMcp, isA2a } = args;
+	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})...`);
+	const containerId = await runDetached({
+		image,
+		mounts: [],
+		env: dockerEnv,
+		cmd: [],
+		hostPort,
+		host: containerHost,
+		platform: options.platform,
+		name: containerName,
+		...containerPort !== void 0 && { containerPort },
+		...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
+	});
+	let stopLogs;
+	try {
+		stopLogs = streamLogs(containerId);
+	} catch (err) {
+		await removeContainer(containerId).catch(() => {});
+		throw err;
+	}
+	return {
+		containerId,
+		hostPort,
+		stopLogs
+	};
+}
+/**
+* Rebuild the agent container for the `--watch` loop: tear down the OLD
+* container (via the supplied `cleanupBefore`), re-synth the CDK app, re-pick
+* the candidate stack + re-resolve the runtime (so a new asset hash / env /
+* image is picked up), then re-run {@link bootAgentCoreContainer}. The inbound
+* auth (bearer token / OIDC discovery URL) is NOT re-resolved — it is stable
+* across a CDK source edit, so the caller threads its boot-time `authorization`
+* back into the next invocation.
+*
+* Exported so a unit test can drive the rebuild shape without the full command.
+*/
+async function rebuildAgentCoreContainer(args) {
+	const { cleanupBefore, resolvedTarget, options, synthesizer, synthOpts, profileCredentials, profileCredsFile, stateProvider, isMcp, isA2a } = args;
+	await cleanupBefore();
+	const { stacks: newStacks } = await synthesizer.synthesize(synthOpts);
+	const newCandidate = pickAgentCoreCandidateStack$1(resolvedTarget, newStacks);
+	const { context: newImageContext, loaded: newLoaded } = stateProvider && newCandidate ? await buildAgentCoreImageContext(newCandidate, stateProvider, options) : {
+		context: void 0,
+		loaded: void 0
+	};
+	return {
+		...await bootAgentCoreContainer({
+			resolved: resolveAgentCoreTarget(resolvedTarget, newStacks, newImageContext),
+			options,
+			profileCredentials,
+			profileCredsFile,
+			stateProvider,
+			loadedState: newLoaded,
+			imageContext: newImageContext,
+			isMcp,
+			isA2a
+		}),
+		stacks: newStacks
+	};
+}
+/**
 * Enforce the runtime's inbound JWT authorizer (when declared) and return
 * the `Authorization` header to forward to `/invocations`.
 *
@@ -50050,11 +50554,45 @@ async function* readStdinLines() {
 		crlfDelay: Infinity
 	});
 	try {
-		for await (const line of rl) yield line;
+		for await (const line of rl) {
+			if (line.length === 0) continue;
+			yield line;
+		}
 	} finally {
 		rl.close();
 	}
 }
+/**
+* REPL prompt indicator for the auto-detected TTY mode. Written to stdout (no
+* trailing newline) after each received agent frame, so the user has a clear
+* visual signal that the REPL is waiting for input.
+*
+* Exported so a unit test can assert the prompt shape.
+*/
+const WS_REPL_PROMPT = "> ";
+/**
+* Wrap `onMessage` so each agent WS text frame lands on its own line when the
+* auto-REPL is active AND a `> ` prompt indicator follows. WS frames carry no
+* trailing `\n` by protocol (each frame is a discrete message); the cloud
+* `/ws` endpoint behaves the same. That's correct on the wire but visually
+* run-on in an interactive terminal — the user's next keystroke concatenates
+* onto the last frame's tail char and they have no signal that the REPL is
+* waiting for input. In interactive mode we append `\n` (unless already
+* present) and then write a `> ` prompt, so each agent message is presented as
+* its own line and the next input prompt is visible.
+*
+* Non-interactive (piped / CI) is unchanged — the raw stdout shape is what
+* scripts rely on, and the WS-protocol-faithful pass-through stays.
+*
+* Exported so a unit test can drive the wrapping without the full WS pipeline.
+*/
+function wrapWsOnMessage(sink, interactive) {
+	if (!interactive) return sink;
+	return (text) => {
+		sink(text.endsWith("\n") ? text : `${text}\n`);
+		sink("> ");
+	};
+}
 function readEnvOverridesFile$1(filePath) {
 	if (!filePath) return void 0;
 	let raw;
@@ -50073,7 +50611,7 @@ function readEnvOverridesFile$1(filePath) {
 	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) => {
+	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. When stdin is a TTY, auto-enters a REPL — each typed line is sent as a follow-up text frame until Ctrl-D / agent close; pipe from /dev/null to force one-shot in a TTY. Ignored for an MCP runtime.").default(false)).addOption(new Option("--watch", "Re-synth and reload the agent container on CDK source changes (follows cdk-local #270). Supported on the HTTP / AGUI protocols, both the --ws session AND the default one-shot POST /invocations (the reload re-runs the single shot). An interpreted-language source edit inside a CodeConfiguration source tree takes a soft-reload fast path (docker cp + docker restart, no rebuild); Dockerfile / compiled-source / asset-hash-changed / ambiguous edits force a full rebuild. For MCP / A2A runtimes --watch is a no-op WARN and the single shot proceeds.").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);
 	}));
 	[
@@ -52019,7 +52557,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.205.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.207.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());