feat: add gateway import command with executionRoleArn support

[jesseturner21]

Summary

• Add agentcore import gateway --arn <gatewayArn> command that imports an existing AWS gateway with its targets into a local agentcore project
• Preserve the gateway's original IAM execution role via executionRoleArn, matching the pattern used by runtime and memory imports
• On deploy, CDK uses iam.Role.fromRoleArn() instead of creating a new role, keeping original permissions intact
• Unhide the import command from the TUI and add gateway ARN support to the ARN input component

Changes

Gateway Import Command

• src/cli/commands/import/import-gateway.ts — new import command that fetches gateway details + targets from AWS, maps them to the local schema, writes agentcore.json and deployed-state.json, then runs CDK synth for CloudFormation import
• src/cli/aws/agentcore-control.ts — extract roleArn from GetGateway API response

executionRoleArn Support

• src/schema/schemas/mcp.ts — add optional executionRoleArn field to gateway schema
• src/cli/commands/import/import-gateway.ts — map AWS roleArn → executionRoleArn during import

CDK Constructs (separate PR in agentcore-l3-cdk-constructs)

• Gateway.ts — use fromRoleArn when executionRoleArn is set, add addToPolicy guard method
• AgentCoreMcp.ts — use gateway.addToPolicy() for policy engine grants
• mcp.ts — add executionRoleArn to CDK schema

E2E Tests

• e2e-tests/import-resources.test.ts — gateway import test, field verification (including executionRoleArn), deployed-state verification
• e2e-tests/fixtures/import/setup_gateway.py — creates gateway + MCP server target for testing
• e2e-tests/fixtures/import/common.py — gateway wait helpers

Test plan

• 3301 unit tests pass
• 152 CDK construct tests pass
• E2e: create real AWS gateway, import it, verify executionRoleArn matches original role ARN
• Verify agentcore.json contains all gateway fields (name, resourceName, description, authorizerType, enableSemanticSearch, exceptionLevel, executionRoleArn, tags, targets)
• Verify deployed-state.json has gateway entry with gatewayId
• Run full e2e suite with CDK tarball: CDK_TARBALL=<path> npm run test:e2e

[github-actions]

Package Tarball

aws-agentcore-0.11.0.tgz

How to install

npm install https://github.com/aws/agentcore-cli/releases/download/pr-855-tarball/aws-agentcore-0.11.0.tgz

[aidandaly24]

Comprehensive review

Reviewed via 5 parallel Opus 4.7 agents tracing the CLI command flow, CDK Gateway construct, CFN IMPORT pipeline, cross-repo schema sync, and AWS→CLI mapping end-to-end. All findings below were verified against the current PR head (343469b) by a second pass.

Blockers that need a fix before merge (inline on each):

• B3: import gateway missing --name/--target/-y Commander flags
• B4: unresolvable OAuth/API_KEY credential silently strips outboundAuth → next deploy removes live auth
• B6: enableSemanticSearch: false → CDK omits ProtocolConfiguration → drift on first UPDATE after IMPORT
• B7: lambda → lambdaFunctionArn swap erases OAuth on live Lambda targets

High-priority (inline where possible):

• H1: gateway logical-ID fallback chain misses when user passes --name + ≥2 un-deployed gateways
• H2: re-import fast path writes out-of-band targets to config without reconciling with CFN
• H3: re-import with --name override leaves deployed-state keyed under the old name
• H5: parseAndValidateArn pre-flight regexes hardcode arn:aws: — blocks GovCloud/China (AGENTS.md violation)
• H7: executionRoleArn/resourceName are z.string().optional() with no validation
• H8: resourceName and executionRoleArn don't co-vary in the schema

Two findings whose target lines fall outside the PR diff (can't be inlined — flagging here):

H9 — LLM-compacted schemas missing the new fields. src/schema/llm-compacted/mcp.ts (file is not in this diff): the AgentCoreGateway interface there omits resourceName and executionRoleArn. These compacted files are vended as read-only LLM context via cli/templates/schema-assets.ts, so LLMs generating user agentcore.json files won't know these fields exist. Same gap in the companion CDK PR. Fix: add both fields to both files.

H10 — Live openApiSchema target with GATEWAY_IAM_ROLE is uninportable. src/schema/schemas/mcp.ts:57 (outside the hunk touched by this PR): TARGET_TYPE_AUTH_CONFIG.openApiSchema has authRequired: true and iamRoleFallback: false. But resolveOutboundAuth at import-gateway.ts:214-217 falls through to return undefined for GATEWAY_IAM_ROLE, and AWS service-side accepts GATEWAY_IAM_ROLE on OpenAPI targets. So a legitimate live config maps to a spec with no outboundAuth and fails Zod superRefine. Fix: change to { authRequired: false, validAuthTypes: ['OAUTH', 'API_KEY'], iamRoleFallback: true } and update the superRefine message.

Nice work overall — the CFN IMPORT pipeline reuse and rollback logic are clean. Pre-existing cross-repo schema drift (artifact vs build, AgentCoreMcpSpecSchema missing from CLI) is out of scope for this PR but worth a separate tracking issue.

[aidandaly24]

B3 (blocker) — Missing Commander flags.

Only --arn is registered here, but handleImportGateway reads options.name, options.target, options.yes (lines 428, 452, and via ImportResourceOptions). Commander's default behavior rejects unknown options with process.exit(1) unless allowUnknownOption() is called; grep shows no such call in src/cli. Running agentcore import gateway --name foo will fail at parse time.

The flow test at __tests__/import-gateway-flow.test.ts invokes handleImportGateway({...}) directly and bypasses Commander, so tests cannot catch this.

Sibling import-memory.ts:108-113 and import-runtime.ts:204-212 register all three.

Fix:

importCmd
  .command('gateway')
  .description('Import an existing AgentCore Gateway (with targets) from your AWS account')
  .option('--arn <gatewayArn>', 'Gateway ARN to import')
  .option('--name <name>', 'Local name for the imported gateway')
  .option('--target <target>', 'Deployment target name (only needed if project has multiple targets)')
  .option('-y, --yes', 'Auto-confirm prompts')
  .action(/* ... */);

[aidandaly24]

B4 (blocker) — Unresolvable credential silently strips outboundAuth; next deploy removes live auth.

When credentials.get(providerArn) misses, we return undefined and the caller spreads ...(outboundAuth && { outboundAuth }), producing a target spec with no outboundAuth key. Per-target consequences:

• mcpServer / apiGateway: spec validates (default NONE). CDK then emits credentialProviderConfigurations: undefined. CloudFormation UPDATE with the property removed reverts it to service default — live credential provider is stripped.
• openApiSchema: fails Zod superRefine because authRequired: true. Import hard-fails at writeProjectSpec with a cryptic Zod error (overlaps H10).
• smithyModel / lambdaFunctionArn: iamRoleFallback, not affected.

Fix: treat "auth configured but unresolvable" as a hard failure distinct from "no auth configured".

if (!credentialName) {
  throw new Error(
    `Target "${detail.name}" uses OAuth credential provider ${providerArn}, but no matching ` +
      `credential exists in this project's deployed-state.json. Import the credential first ` +
      `(\`agentcore add credential\` or from the owning project) and re-run.`
  );
}

Apply the same to the API_KEY branch at line 211.

[aidandaly24]

B6 (blocker) — enableSemanticSearch: false produces ProtocolConfiguration drift.

const enableSemanticSearch = gateway.protocolConfiguration?.mcp?.searchType === 'SEMANTIC';

Three live states collapse to two import values: SEMANTIC → true; explicit NONE or absent → false. The CDK companion (Gateway.ts:223-233 in the companion PR) returns undefined when enableSemanticSearch === false, omitting ProtocolConfiguration from the synth template. CFN IMPORT itself only compares identifier properties, so the import succeeds — but on the first post-import agentcore deploy, CFN sees ProtocolConfiguration absent in template vs present-on-live and issues an UpdateGateway call rewriting live state.

Fix: emit explicit NONE/SEMANTIC in both CDK and mapping. In the companion CDK PR:

private buildProtocolConfiguration(gateway: AgentCoreGateway) {
  return {
    mcp: { searchType: gateway.enableSemanticSearch === false ? 'NONE' : 'SEMANTIC' },
  };
}

[aidandaly24]

B7 (blocker) — Live Lambda target with OAuth outbound auth silently loses OAuth on import.

TARGET_TYPE_AUTH_CONFIG.lambda at schemas/mcp.ts:61 allows ['OAUTH', 'NONE'], so a live AWS Lambda-backed target CAN have OAuth. This mapper drops outboundAuth entirely (even the ...(outboundAuth && ...) spread is missing), and the destination lambdaFunctionArn schema at schemas/mcp.ts:62 has validAuthTypes: [] so it couldn't accept OAuth anyway. On top of that, the CDK companion at Gateway.ts:398 hardcodes [{ credentialProviderType: 'GATEWAY_IAM_ROLE' }], overwriting the live OAuth provider on next deploy.

Fix: preserve outboundAuth in the mapper, relax TARGET_TYPE_AUTH_CONFIG.lambdaFunctionArn.validAuthTypes, and wire buildCredentialConfig(target) into the CDK lambdaFunctionArn branch.

if (s3Uri) {
  onProgress(`Mapping compute-backed Lambda target "${detail.name}" to lambdaFunctionArn type`);
  return {
    name: detail.name,
    targetType: 'lambdaFunctionArn',
    lambdaFunctionArn: { lambdaArn, toolSchemaFile: s3Uri },
    ...(outboundAuth && { outboundAuth }),
  };
}

[aidandaly24]

H1 (high) — Logical-ID fallback chain misses with --name + multiple un-deployed gateways.

Tiers 1-2 search for ${projectName}-${localName} and localName, but the CDK synthesizes Name: gateway.resourceName (the live AWS name, set at line 282). When the user passes --name foo that differs from the AWS name, localName='foo' and resourceName=awsName — neither tier matches. Tier 3 (single-candidate) saves only when exactly one un-deployed gateway logical ID exists. If the project has ≥2 new gateways in the synth, all tiers miss → return [] → rollback.

Currently latent because --name isn't wired through Commander (see B3), but will be reachable once B3 is fixed.

Fix: add gatewayDetail.name as an explicit fallback.

gatewayLogicalId ??= findLogicalIdByProperty(
  synthTemplate,
  'AWS::BedrockAgentCore::Gateway',
  'Name',
  gatewayDetail.name,
  { excludeLogicalIds: deployedIds }
);

[aidandaly24]

H2 (high) — Re-import fast path can write out-of-band targets to config.

The fast path fetches all live targets, maps them into mappedTargets, writes to agentcore.json, and returns without touching CFN. If a target was added to the live gateway out-of-band between imports, it gets written into config but not into the CFN stack. The next agentcore deploy synthesizes a CfnGatewayTarget with a Name that matches a live un-managed resource → CloudFormation CREATE fails with CREATE_FAILED (AWS API returns ConflictException/ValidationException).

Fix: run the full pipeline on re-import. The existing buildResourcesToImport callback already handles deployedIds exclusion and produces an empty list when every target is already in the stack, which we can treat as success. Remove the early return here and fall through to the main path.

[aidandaly24]

H3 (high) — Re-import with --name override leaves deployed-state keyed under old name.

if (!options.name) {
  localName = existingResource;
}

If the user passes --name newName, localName stays as the user's value. The pushed spec has name: newName but deployed-state.json still has its entry keyed under existingResource. Downstream consumers — status/action.ts, deploy, remove — all match by agentCoreGateways[i].name, so status reports an orphan, remove newName can't clean up deployed-state, and deploy treats it as a new gateway.

Currently latent because --name isn't wired through Commander (see B3).

Fix: reject the mismatch.

if (options.name && options.name !== existingResource) {
  return failResult(
    logger,
    `Gateway "${existingResource}" is already managed under that name in deployed-state.json. ` +
      `Either omit --name (the existing name will be reused) or first rename the deployed-state entry.`,
    'gateway',
    options.name
  );
}

[aidandaly24]

H5 (high) — Partition hardcode blocks GovCloud / China.

This regex and the one at line 145 both hardcode arn:aws:. The ARN_PATTERN at line 229 correctly uses arn:[^:]+:, but these pre-flight checks run first and reject GovCloud (arn:aws-us-gov:) and China (arn:aws-cn:) ARNs before the right validator ever runs. Direct violation of AGENTS.md: "ARN regex patterns must use arn:[^:]+:".

Fix:

// line 131-139
if (arn && !ARN_PATTERN.test(arn)) {
  throw new Error(
    `Not a valid ARN: "${arn}".\nExpected format: arn:<partition>:bedrock-agentcore:<region>:<account>:<runtime|memory|evaluator|online-evaluation-config|gateway>/<id>`
  );
}

// line 145
const arnRegionMatch = /^arn:[^:]+:bedrock-agentcore:([^:]+):/.exec(arn);

[aidandaly24]

H7 (high) — executionRoleArn / resourceName have no validation.

Both fields are z.string().optional() with no regex, no length bound. Weaker than LambdaFunctionArnConfigSchema.lambdaArn (.min(1).max(170) at line 106) and weaker than the existing GatewayNameSchema. A user hand-writing agentcore.json with a malformed role ARN or invalid gateway name only discovers it at CFN deploy time with a ValidationException.

Fix:

resourceName: GatewayNameSchema.optional(),
executionRoleArn: z.string()
  .regex(/^arn:[^:]+:iam::\d{12}:role\/.+/, 'Must be a valid IAM role ARN')
  .max(2048)
  .optional(),

H8 (high, same file) — resourceName and executionRoleArn don't co-vary.

Only-resourceName → CDK creates a fresh role against a custom gateway name (ambiguous config; unclear whether import or create-with-custom-name). Only-executionRoleArn → CDK uses imported role with a project-generated gateway name (the imported role silently drops all addToPolicy calls for outbound-auth targets). Add a .refine():

.refine(
  data => (data.resourceName !== undefined) === (data.executionRoleArn !== undefined),
  {
    message: 'resourceName and executionRoleArn must be set together (import) or both omitted (fresh gateway)',
    path: ['resourceName'],
  }
)

Apply identically to the CDK repo (agentcore-l3-cdk-constructs/src/schema/schemas/mcp.ts:598).