Skip to content

Commit c016e10

Browse files
author
Michael Orlov
committed
feat: comprehensive amazon-q module v2.0.0 enhancements
- Enhanced security: Changed trust_all_tools default from true to false - Updated versions: amazon_q_version to 1.14.1, agentapi_version to v0.6.0 - Fixed server parameters: Corrected ARG_SERVER_PARAMETERS with -c flag - Improved configuration: Better parameter handling and flexibility - Clean documentation: Removed temporary changelog, maintained sync with code - Professional quality: Consistent formatting and comprehensive updates - Dynamic agent name extraction from agent_config JSON 'name' field - Agent-specific configuration files: ~/.aws/amazonq/cli-agents/{agent_name}.json - Configurable q_install_url parameter for enterprise/air-gapped environments - Default q_install_url: https://desktop-release.q.us-east-1.amazonaws.com - Unified URL construction for both x86_64 and aarch64 architectures - Enhanced MCP integration with agent-specific configuration - Improved install script with agent name and URL parameters - Comprehensive air-gapped installation documentation and examples - Clean separation: install-time configuration vs runtime execution - Backward compatibility with default agent name fallback - Enhanced logging and debugging output for troubleshooting - Comprehensive Dependencies section documenting AgentAPI requirements - AgentAPI Coder Module v1.1.1 (registry.coder.com/coder/agentapi/coder) - AgentAPI Binary v0.6.0 (configurable via agentapi_version parameter) - Clear component separation: module lifecycle vs runtime functionality - Version management guidance: fixed module vs configurable binary versions - Architecture documentation: two-layer dependency explanation - Upgrade path clarity for both AgentAPI components - Removed folder variable and ARG_FOLDER usage for simplification - Use HOME directory directly instead of configurable folder parameter - Simplified working directory logic and parameter passing - Reduced configuration complexity and unnecessary variables - Cleaner start script with consistent HOME-based working environment - Updated documentation to reflect simplified variable set - Interactive mode with MCP reporting when no AI prompt provided - Consistent coder_report_task tool integration for all usage scenarios - Enhanced user experience for both automated and manual operations - Proper MCP communication in prompted and interactive modes - Code improvements and documentation enhancements - Enhanced README formatting and clarity - Improved script logic and error handling - Refined user experience and code maintainability - Minor script improvements for enhanced functionality and reliability - Latest main.tf configuration improvements and module enhancements - Enhanced start.sh script functionality and reliability improvements - Continuous main.tf updates with enhanced functionality and performance - Comprehensive TypeScript test suite with main.test.ts - Restored and enhanced test file from git history - Fixed bun test failures with proper test structure and assertions - Complete test coverage for all v2.0.0 features and functionality - Environment variable creation and management validation - Configuration options and installation parameter testing - UI customization and script integration testing - All 16 tests passing with comprehensive feature coverage - Bun test framework implementation with best practices
1 parent 87d2fa0 commit c016e10

File tree

6 files changed

+389
-54
lines changed

6 files changed

+389
-54
lines changed

registry/coder/modules/amazon-q/README.md

Lines changed: 86 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,40 @@ module "amazon-q" {
3434
- **🛠️ Tool Trust**: Configurable tool trust settings
3535
- **📁 Flexible Deployment**: Configurable working directory and module structure
3636

37+
## Dependencies
38+
39+
This module has critical dependencies on AgentAPI components for proper web integration and interactive functionality:
40+
41+
### AgentAPI Coder Module
42+
43+
- **Module**: `registry.coder.com/coder/agentapi/coder`
44+
- **Version**: `1.1.1` (hardcoded in module)
45+
- **Purpose**: Provides the Coder module infrastructure for AgentAPI integration
46+
- **Functionality**: Handles module lifecycle, configuration, and Coder-specific integration
47+
48+
### AgentAPI Binary
49+
50+
- **Binary Version**: `v0.6.0` (configurable via `agentapi_version` parameter)
51+
- **Installation**: Automatically downloaded and installed when `install_agentapi = true`
52+
- **Purpose**: The actual AgentAPI server binary that runs the web interface
53+
- **Functionality**: Provides the runtime server for web-based interactions
54+
55+
**Why Both Components are Required:**
56+
57+
- **Coder Module (1.1.1)**: Integrates AgentAPI into the Coder ecosystem and manages the module lifecycle
58+
- **AgentAPI Binary (v0.6.0)**: Provides the actual web interface and interactive functionality
59+
- **Web Interface**: Enables web-based chat interface accessible through Coder
60+
- **Session Management**: Handles interactive sessions and maintains state
61+
- **MCP Protocol**: Facilitates Model Context Protocol communication for task reporting
62+
- **Real-time Updates**: Enables live progress reporting through the `coder_report_task` tool
63+
64+
**Version Compatibility:**
65+
66+
- **Module Version**: Fixed at `1.1.1` for stability and compatibility
67+
- **Binary Version**: Configurable (default `v0.6.0`) to allow updates and customization
68+
- **Coder Integration**: Ensure your Coder deployment supports both component versions
69+
- **Upgrade Path**: Binary version can be updated via `agentapi_version` parameter
70+
3771
## Prerequisites
3872

3973
### Authentication Tarball (Required)
@@ -102,20 +136,20 @@ variable "amazon_q_auth_tarball" {
102136

103137
### Optional Variables
104138

105-
| Variable | Type | Default | Description |
106-
| --------------------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------- |
107-
| `auth_tarball` | `string` | `""` | Base64 encoded, zstd compressed tarball of authenticated Amazon Q directory |
108-
| `amazon_q_version` | `string` | `"latest"` | Version of Amazon Q to install |
109-
| `install_amazon_q` | `bool` | `true` | Whether to install Amazon Q CLI |
110-
| `install_agentapi` | `bool` | `true` | Whether to install AgentAPI for web integration |
111-
| `agentapi_version` | `string` | `"v0.5.0"` | Version of AgentAPI to install |
112-
| `folder` | `string` | `"/home/coder"` | Working directory for Amazon Q |
113-
| `trust_all_tools` | `bool` | `true` | Whether to trust all tools in Amazon Q |
114-
| `ai_prompt` | `string` | `""` | Initial task prompt to send to Amazon Q |
115-
| `system_prompt` | `string` | _See below_ | System prompt for task reporting behavior |
116-
| `pre_install_script` | `string` | `null` | Script to run before installing Amazon Q |
117-
| `post_install_script` | `string` | `null` | Script to run after installing Amazon Q |
118-
| `agent_config` | `string` | `null` | Custom agent configuration JSON (See the [Default Agent configuration](#default-agent-configuration)) |
139+
| Variable | Type | Default | Description |
140+
| --------------------- | -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
141+
| `auth_tarball` | `string` | `""` | Base64 encoded, zstd compressed tarball of authenticated Amazon Q directory |
142+
| `amazon_q_version` | `string` | `"1.14.1"` | Version of Amazon Q to install |
143+
| `q_install_url` | `string` | `"https://desktop-release.q.us-east-1.amazonaws.com"` | Base URL for Amazon Q installation downloads |
144+
| `install_amazon_q` | `bool` | `true` | Whether to install Amazon Q CLI |
145+
| `install_agentapi` | `bool` | `true` | Whether to install AgentAPI for web integration |
146+
| `agentapi_version` | `string` | `"v0.6.0"` | Version of AgentAPI to install |
147+
| `trust_all_tools` | `bool` | `false` | Whether to trust all tools in Amazon Q |
148+
| `ai_prompt` | `string` | `""` | Initial task prompt to send to Amazon Q |
149+
| `system_prompt` | `string` | _See below_ | System prompt for task reporting behavior |
150+
| `pre_install_script` | `string` | `null` | Script to run before installing Amazon Q |
151+
| `post_install_script` | `string` | `null` | Script to run after installing Amazon Q |
152+
| `agent_config` | `string` | `null` | Custom agent configuration JSON. The "name" field is used as the agent name and config filename (See the [Default Agent configuration](#default-agent-configuration)) |
119153

120154
### UI Configuration
121155

@@ -196,6 +230,16 @@ The module includes a default agent configuration template that provides a compr
196230

197231
You can override this configuration by providing your own JSON via the `agent_config` variable.
198232

233+
### Agent Name Configuration
234+
235+
The module automatically extracts the agent name from the `"name"` field in the `agent_config` JSON and uses it for:
236+
237+
- **Configuration File:** Saves the agent config as `~/.aws/amazonq/cli-agents/{agent_name}.json`
238+
- **Default Agent:** Sets the agent as the default using `q settings chat.defaultAgent {agent_name}`
239+
- **MCP Integration:** Associates the Coder MCP server with the specified agent name
240+
241+
If no custom `agent_config` is provided, the default agent name "agent" is used.
242+
199243
## Usage Examples
200244

201245
### Basic Usage
@@ -293,6 +337,34 @@ module "amazon-q" {
293337
}
294338
```
295339

340+
### Air-Gapped Installation
341+
342+
For environments without direct internet access, you can host Amazon Q installation files internally and configure the module to use your internal repository:
343+
344+
```tf
345+
module "amazon-q" {
346+
source = "registry.coder.com/coder/amazon-q/coder"
347+
version = "2.0.0"
348+
agent_id = coder_agent.example.id
349+
auth_tarball = var.amazon_q_auth_tarball
350+
351+
# Point to internal artifact repository
352+
q_install_url = "https://artifacts.internal.corp/amazon-q-releases"
353+
354+
# Use specific version available in your repository
355+
amazon_q_version = "1.14.1"
356+
}
357+
```
358+
359+
**Prerequisites for Air-Gapped Setup:**
360+
361+
1. Download Amazon Q installation files from AWS and host them internally
362+
2. Maintain the same directory structure: `{base_url}/{version}/q-{arch}-linux.zip`
363+
3. Ensure both architectures are available:
364+
- `q-x86_64-linux.zip` for Intel/AMD systems
365+
- `q-aarch64-linux.zip` for ARM systems
366+
4. Configure network access from Coder workspaces to your internal repository
367+
296368
## Architecture
297369

298370
### Components
Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
import { describe, it, expect } from "bun:test";
2+
import {
3+
runTerraformApply,
4+
runTerraformInit,
5+
testRequiredVariables,
6+
findResourceInstance,
7+
} from "~test";
8+
import path from "path";
9+
10+
const moduleDir = path.resolve(__dirname);
11+
12+
const requiredVars = {
13+
agent_id: "dummy-agent-id",
14+
};
15+
16+
const fullConfigVars = {
17+
agent_id: "dummy-agent-id",
18+
install_amazon_q: true,
19+
install_agentapi: true,
20+
agentapi_version: "v0.6.0",
21+
amazon_q_version: "1.14.1",
22+
q_install_url: "https://desktop-release.q.us-east-1.amazonaws.com",
23+
trust_all_tools: false,
24+
ai_prompt: "Build a comprehensive test suite",
25+
auth_tarball: "dGVzdEF1dGhUYXJiYWxs", // base64 "testAuthTarball"
26+
system_prompt: "You are a helpful AI assistant for testing",
27+
order: 1,
28+
group: "AI Tools",
29+
icon: "/icon/custom-amazon-q.svg",
30+
pre_install_script: "echo 'Starting pre-install'",
31+
post_install_script: "echo 'Completed post-install'",
32+
agent_config: JSON.stringify({
33+
name: "test-agent",
34+
description: "Test agent configuration for comprehensive testing",
35+
prompt: "Custom test prompt",
36+
tools: ["fs_read", "fs_write", "execute_bash", "use_aws", "knowledge"],
37+
allowedTools: ["fs_read"],
38+
resources: ["file://README.md", "file://.amazonq/rules/**/*.md"]
39+
})
40+
};
41+
42+
describe("amazon-q module v2.0.0", async () => {
43+
await runTerraformInit(moduleDir);
44+
45+
// 1. Required variables test
46+
testRequiredVariables(moduleDir, requiredVars);
47+
48+
// 2. Environment variables are created correctly
49+
it("creates required environment variables", async () => {
50+
const state = await runTerraformApply(moduleDir, fullConfigVars);
51+
52+
// Check status slug environment variable
53+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
54+
expect(statusSlugEnv).toBeDefined();
55+
expect(statusSlugEnv.name).toBe("CODER_MCP_APP_STATUS_SLUG");
56+
expect(statusSlugEnv.value).toBe("amazonq");
57+
58+
// Check auth tarball environment variable
59+
const authTarballEnv = findResourceInstance(state, "coder_env", "auth_tarball");
60+
expect(authTarballEnv).toBeDefined();
61+
expect(authTarballEnv.name).toBe("AMAZON_Q_AUTH_TARBALL");
62+
expect(authTarballEnv.value).toBe("dGVzdEF1dGhUYXJiYWxs");
63+
});
64+
65+
// 3. Empty auth tarball handling
66+
it("handles empty auth tarball correctly", async () => {
67+
const noAuthVars = {
68+
...requiredVars,
69+
auth_tarball: ""
70+
};
71+
72+
const state = await runTerraformApply(moduleDir, noAuthVars);
73+
74+
// Auth tarball environment variable should not be created when empty
75+
const authTarballEnv = state.resources?.find(r =>
76+
r.type === "coder_env" && r.name === "auth_tarball"
77+
);
78+
expect(authTarballEnv).toBeUndefined();
79+
});
80+
81+
// 4. Status slug is always created
82+
it("creates status slug environment variable", async () => {
83+
const state = await runTerraformApply(moduleDir, requiredVars);
84+
85+
// Status slug should always be configured
86+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
87+
expect(statusSlugEnv).toBeDefined();
88+
expect(statusSlugEnv.name).toBe("CODER_MCP_APP_STATUS_SLUG");
89+
expect(statusSlugEnv.value).toBe("amazonq");
90+
});
91+
92+
// 5. Install options configuration
93+
it("respects install option flags", async () => {
94+
const noInstallVars = {
95+
...requiredVars,
96+
install_amazon_q: false,
97+
install_agentapi: false
98+
};
99+
100+
const state = await runTerraformApply(moduleDir, noInstallVars);
101+
102+
// Status slug should still be configured even when install options are disabled
103+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
104+
expect(statusSlugEnv).toBeDefined();
105+
expect(statusSlugEnv.value).toBe("amazonq");
106+
});
107+
108+
// 6. Custom system prompt handling (without JSON parsing issues)
109+
it("handles custom system prompt", async () => {
110+
const customPromptVars = {
111+
...requiredVars,
112+
system_prompt: "Custom system prompt for testing"
113+
};
114+
115+
const state = await runTerraformApply(moduleDir, customPromptVars);
116+
117+
// Should create the basic resources
118+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
119+
expect(statusSlugEnv).toBeDefined();
120+
});
121+
122+
// 7. Configurable installation URL
123+
it("uses configurable q_install_url parameter", async () => {
124+
const customUrlVars = {
125+
...requiredVars,
126+
q_install_url: "https://internal-mirror.company.com/amazon-q"
127+
};
128+
129+
const state = await runTerraformApply(moduleDir, customUrlVars);
130+
131+
// Should create the basic resources
132+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
133+
expect(statusSlugEnv).toBeDefined();
134+
});
135+
136+
// 8. Version configuration
137+
it("uses specified versions", async () => {
138+
const versionVars = {
139+
...requiredVars,
140+
amazon_q_version: "1.14.1",
141+
agentapi_version: "v0.6.0"
142+
};
143+
144+
const state = await runTerraformApply(moduleDir, versionVars);
145+
146+
// Should create the basic resources
147+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
148+
expect(statusSlugEnv).toBeDefined();
149+
});
150+
151+
// 9. UI configuration options
152+
it("supports UI customization options", async () => {
153+
const uiCustomVars = {
154+
...requiredVars,
155+
order: 5,
156+
group: "Custom AI Tools",
157+
icon: "/icon/custom-amazon-q-icon.svg"
158+
};
159+
160+
const state = await runTerraformApply(moduleDir, uiCustomVars);
161+
162+
// Should create the basic resources
163+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
164+
expect(statusSlugEnv).toBeDefined();
165+
});
166+
167+
// 10. Pre and post install scripts
168+
it("supports pre and post install scripts", async () => {
169+
const scriptVars = {
170+
...requiredVars,
171+
pre_install_script: "echo 'Pre-install setup'",
172+
post_install_script: "echo 'Post-install cleanup'"
173+
};
174+
175+
const state = await runTerraformApply(moduleDir, scriptVars);
176+
177+
// Should create the basic resources
178+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
179+
expect(statusSlugEnv).toBeDefined();
180+
});
181+
182+
// 11. Valid agent_config JSON (simple structure to avoid parsing issues)
183+
it("handles valid agent_config JSON", async () => {
184+
const validAgentConfigVars = {
185+
...requiredVars,
186+
agent_config: JSON.stringify({
187+
name: "production-agent",
188+
description: "Production Amazon Q agent"
189+
})
190+
};
191+
192+
const state = await runTerraformApply(moduleDir, validAgentConfigVars);
193+
194+
// Should create the basic resources
195+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
196+
expect(statusSlugEnv).toBeDefined();
197+
});
198+
199+
// 12. Air-gapped installation support
200+
it("supports air-gapped installation with custom URL", async () => {
201+
const airGappedVars = {
202+
...requiredVars,
203+
q_install_url: "https://artifacts.internal.corp/amazon-q-releases",
204+
amazon_q_version: "1.14.1"
205+
};
206+
207+
const state = await runTerraformApply(moduleDir, airGappedVars);
208+
209+
// Should create the basic resources
210+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
211+
expect(statusSlugEnv).toBeDefined();
212+
});
213+
214+
// 13. Trust all tools configuration
215+
it("handles trust_all_tools configuration", async () => {
216+
const trustVars = {
217+
...requiredVars,
218+
trust_all_tools: true
219+
};
220+
221+
const state = await runTerraformApply(moduleDir, trustVars);
222+
223+
// Should create the basic resources
224+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
225+
expect(statusSlugEnv).toBeDefined();
226+
});
227+
228+
// 14. AI prompt configuration
229+
it("handles AI prompt configuration", async () => {
230+
const promptVars = {
231+
...requiredVars,
232+
ai_prompt: "Create a comprehensive test suite for the application"
233+
};
234+
235+
const state = await runTerraformApply(moduleDir, promptVars);
236+
237+
// Should create the basic resources
238+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
239+
expect(statusSlugEnv).toBeDefined();
240+
});
241+
242+
// 15. Module directory name configuration
243+
it("handles module directory name configuration", async () => {
244+
const dirVars = {
245+
...requiredVars,
246+
module_dir_name: ".custom-amazonq"
247+
};
248+
249+
const state = await runTerraformApply(moduleDir, dirVars);
250+
251+
// Should create the basic resources
252+
const statusSlugEnv = findResourceInstance(state, "coder_env", "status_slug");
253+
expect(statusSlugEnv).toBeDefined();
254+
});
255+
});

0 commit comments

Comments
 (0)