@caddis/cli 0.0.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/aws-agentic-ai/services/runtime/README.md

@@ -0,0 +1,215 @@
+# Runtime Service
+
+The Runtime service provides a secure, serverless hosting environment for deploying and running AI agents or tools. It handles scaling, session management, security isolation, and infrastructure management.
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Framework Agnostic** | Works with LangGraph, Strands, CrewAI, or custom agents |
+| **Model Flexibility** | Supports any LLM (Bedrock, Claude, Gemini, OpenAI) |
+| **Protocol Support** | MCP (Model Context Protocol) and A2A (Agent to Agent) |
+| **Session Isolation** | Dedicated microVM per session with isolated CPU, memory, filesystem |
+| **Extended Execution** | Up to 8 hours for long-running workloads |
+| **100MB Payloads** | Handle multimodal content (text, images, audio, video) |
+| **Bidirectional Streaming** | HTTP API and WebSocket for real-time interactions |
+
+## Quick Start
+
+### Prerequisites
+- AWS CLI configured with appropriate permissions
+- Docker installed for container builds
+- Python 3.9+ for SDK usage
+
+### Deploy an Agent
+
+**Step 1: Install AgentCore SDK**
+```bash
+pip install bedrock-agentcore
+```
+
+**Step 2: Create agent code**
+```python
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+
+app = BedrockAgentCoreApp()
+
+@app.handler()
+async def handle_request(request, context):
+    user_input = request.get("input", "")
+    # Your agent logic here
+    return {"response": f"Processed: {user_input}"}
+```
+
+**Step 3: Create AgentCore Runtime**
+```bash
+aws bedrock-agentcore-control create-agent-runtime \
+  --agent-runtime-name my-agent \
+  --runtime-artifact '{"containerConfiguration": {"containerUri": "<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/my-agent:latest"}}' \
+  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/AgentRuntimeExecutionRole \
+  --network-configuration '{"networkMode": "PUBLIC"}' \
+  --region us-west-2
+```
+
+**Step 4: Invoke agent**
+```bash
+aws bedrock-agentcore-runtime invoke-agent-runtime \
+  --agent-runtime-endpoint-arn arn:aws:bedrock-agentcore:us-west-2:<ACCOUNT_ID>:runtime/my-agent/endpoint/DEFAULT \
+  --payload '{"input": "Hello, agent!"}' \
+  --region us-west-2
+```
+
+## Core Components
+
+### AgentCore Runtime
+Containerized application hosting your AI agent or tool code. Each runtime:
+- Has a unique identity
+- Is versioned for controlled deployment and updates
+- Can use popular frameworks or custom implementations
+
+### Versions
+Immutable snapshots of configuration:
+- Version 1 (V1) created automatically with new runtime
+- Each update creates a new version
+- Enables rollback capabilities
+
+### Endpoints
+Addressable access points to runtime versions:
+- **DEFAULT**: Automatically created, points to latest version
+- Custom endpoints for different environments (dev, test, prod)
+- Unique ARN for invocation
+
+Endpoint states: `CREATING` → `READY` (or `CREATE_FAILED`) → `UPDATING` → `READY`
+
+### Sessions
+Individual interaction contexts with complete isolation:
+- Dedicated microVM per session
+- Preserves context across interactions
+- Persists up to 8 hours
+- Auto-terminates after 15 minutes idle
+
+Session states: `Active` → `Idle` → `Terminated`
+
+## Authentication
+
+### Inbound (Who Can Access Your Agent)
+
+| Method | Description |
+|--------|-------------|
+| **IAM (SigV4)** | AWS credentials for identity verification |
+| **OAuth 2.0** | External identity providers (Cognito, Okta, Entra ID) |
+
+**OAuth Flow**:
+1. User authenticates with identity provider
+2. Client receives bearer token
+3. Token passed in authorization header
+4. Runtime validates token
+5. Request processed or rejected
+
+### Outbound (Accessing External Services)
+
+| Method | Use Case |
+|--------|----------|
+| **OAuth** | Services supporting OAuth flows |
+| **API Keys** | Key-based authentication |
+
+**Modes**:
+- **User-delegated**: Acting on behalf of end user
+- **Autonomous**: Acting with service-level credentials
+
+## Common Operations
+
+### List Agent Runtimes
+```bash
+aws bedrock-agentcore-control list-agent-runtimes \
+  --region us-west-2
+```
+
+### Get Runtime Details
+```bash
+aws bedrock-agentcore-control get-agent-runtime \
+  --agent-runtime-id <RUNTIME_ID> \
+  --region us-west-2
+```
+
+### Update Runtime
+```bash
+aws bedrock-agentcore-control update-agent-runtime \
+  --agent-runtime-id <RUNTIME_ID> \
+  --runtime-artifact '{"containerConfiguration": {"containerUri": "<NEW_IMAGE_URI>"}}' \
+  --region us-west-2
+```
+
+### Delete Runtime
+```bash
+aws bedrock-agentcore-control delete-agent-runtime \
+  --agent-runtime-id <RUNTIME_ID> \
+  --region us-west-2
+```
+
+## Long-Running Agents
+
+For workloads exceeding request/response cycles (up to 8 hours):
+
+```python
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+
+app = BedrockAgentCoreApp()
+
+@app.handler()
+async def handle_request(request, context):
+    # Add async task
+    task_id = context.add_async_task("background-processing")
+
+    # Start background work
+    # ... long-running operation ...
+
+    # Complete task when done
+    context.complete_async_task(task_id)
+
+    return {"status": "Task started", "task_id": task_id}
+```
+
+## Streaming Responses
+
+Enable real-time partial results:
+
+```python
+@app.handler()
+async def handle_request(request, context):
+    async for chunk in generate_response(request):
+        yield {"partial": chunk}
+    yield {"complete": True}
+```
+
+## Supported Frameworks
+
+| Framework | Description |
+|-----------|-------------|
+| **LangGraph** | Graph-based agent workflows |
+| **Strands** | AWS-native agent framework |
+| **CrewAI** | Multi-agent collaboration |
+| **Custom** | Any Python-based agent |
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| 504 Gateway Timeout | Container issues, ARM64 compatibility | Ensure container exposes port 8080, use ARM64 image |
+| 403 AccessDeniedException | Missing permissions | Verify IAM role and policies |
+| exec format error | Wrong architecture | Build ARM64 containers with buildx |
+| Session terminated after 15min | Idle timeout | Implement ping handler with HEALTHY_BUSY status |
+
+## Related Services
+
+- **[Gateway Service](../gateway/README.md)**: Expose APIs as tools for agents
+- **[Memory Service](../memory/README.md)**: Store agent conversation history
+- **[Identity Service](../identity/README.md)**: Manage agent credentials
+- **[Observability Service](../observability/README.md)**: Monitor agent performance
+
+## References
+
+- [AWS Runtime Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html)
+- [How Runtime Works](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html)
+- [Runtime Troubleshooting](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-troubleshooting.html)
+- [Runtime API Reference](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/)

package/bundles/antigravity-plugin-extras/skills/aws-cdk-development/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: aws-cdk-development
+context: fork
+description: AWS Cloud Development Kit (CDK) expert for building cloud infrastructure with TypeScript/Python. Use when creating CDK stacks, defining CDK constructs, implementing infrastructure as code, or when the user mentions CDK, CloudFormation, IaC, cdk synth, cdk deploy, or wants to define AWS infrastructure programmatically. Covers CDK app structure, construct patterns, stack composition, and deployment workflows.
+---
+
+# AWS CDK Development
+
+This skill provides comprehensive guidance for developing AWS infrastructure using the Cloud Development Kit (CDK), with integrated MCP servers for accessing latest AWS knowledge and CDK utilities.
+
+## AWS Documentation Requirement
+
+**CRITICAL**: This skill requires AWS MCP tools for accurate, up-to-date AWS information.
+
+### Before Answering AWS Questions
+
+1. **Always verify** using AWS MCP tools (if available):
+   - `mcp__aws-mcp__aws___search_documentation` or `mcp__*awsdocs*__aws___search_documentation` - Search AWS docs
+   - `mcp__aws-mcp__aws___read_documentation` or `mcp__*awsdocs*__aws___read_documentation` - Read specific pages
+   - `mcp__aws-mcp__aws___get_regional_availability` - Check service availability
+
+2. **If AWS MCP tools are unavailable**:
+   - Guide user to configure AWS MCP: See [AWS MCP Setup Guide](../../docs/aws-mcp-setup.md)
+   - Help determine which option fits their environment:
+     - Has uvx + AWS credentials → Full AWS MCP Server
+     - No Python/credentials → AWS Documentation MCP (no auth)
+   - If cannot determine → Ask user which option to use
+
+## Integrated MCP Servers
+
+This skill includes the CDK MCP server automatically configured with the plugin:
+
+### AWS CDK MCP Server
+**When to use**: For CDK-specific guidance and utilities
+- Get CDK construct recommendations
+- Retrieve CDK best practices
+- Access CDK pattern suggestions
+- Validate CDK configurations
+- Get help with CDK-specific APIs
+
+**Important**: Leverage this server for CDK construct guidance and advanced CDK operations.
+
+## When to Use This Skill
+
+Use this skill when:
+- Creating new CDK stacks or constructs
+- Refactoring existing CDK infrastructure
+- Implementing Lambda functions within CDK
+- Following AWS CDK best practices
+- Validating CDK stack configurations before deployment
+- Verifying AWS service capabilities and regional availability
+
+## Core CDK Principles
+
+### Resource Naming
+
+**CRITICAL**: Do NOT explicitly specify resource names when they are optional in CDK constructs.
+
+**Why**: CDK-generated names enable:
+- **Reusable patterns**: Deploy the same construct/pattern multiple times without conflicts
+- **Parallel deployments**: Multiple stacks can deploy simultaneously in the same region
+- **Cleaner shared logic**: Patterns and shared code can be initialized multiple times without name collision
+- **Stack isolation**: Each stack gets uniquely identified resources automatically
+
+**Pattern**: Let CDK generate unique names automatically using CloudFormation's naming mechanism.
+
+```typescript
+// ❌ BAD - Explicit naming prevents reusability and parallel deployments
+new lambda.Function(this, 'MyFunction', {
+  functionName: 'my-lambda',  // Avoid this
+  // ...
+});
+
+// ✅ GOOD - Let CDK generate unique names
+new lambda.Function(this, 'MyFunction', {
+  // No functionName specified - CDK generates: StackName-MyFunctionXXXXXX
+  // ...
+});
+```
+
+**Security Note**: For different environments (dev, staging, prod), follow AWS Security Pillar best practices by using separate AWS accounts rather than relying on resource naming within a single account. Account-level isolation provides stronger security boundaries.
+
+### Lambda Function Development
+
+Use the appropriate Lambda construct based on runtime:
+
+**TypeScript/JavaScript**: Use `@aws-cdk/aws-lambda-nodejs`
+```typescript
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+
+new NodejsFunction(this, 'MyFunction', {
+  entry: 'lambda/handler.ts',
+  handler: 'handler',
+  // Automatically handles bundling, dependencies, and transpilation
+});
+```
+
+**Python**: Use `@aws-cdk/aws-lambda-python`
+```typescript
+import { PythonFunction } from '@aws-cdk/aws-lambda-python-alpha';
+
+new PythonFunction(this, 'MyFunction', {
+  entry: 'lambda',
+  index: 'handler.py',
+  handler: 'handler',
+  // Automatically handles dependencies and packaging
+});
+```
+
+**Benefits**:
+- Automatic bundling and dependency management
+- Transpilation handled automatically
+- No manual packaging required
+- Consistent deployment patterns
+
+### Pre-Deployment Validation
+
+Use a **multi-layer validation strategy** for comprehensive CDK quality checks:
+
+#### Layer 1: Real-Time IDE Feedback (Recommended)
+
+**For TypeScript/JavaScript projects**:
+
+Install [cdk-nag](https://github.com/cdklabs/cdk-nag) for synthesis-time validation:
+```bash
+npm install --save-dev cdk-nag
+```
+
+Add to your CDK app:
+```typescript
+import { Aspects } from 'aws-cdk-lib';
+import { AwsSolutionsChecks } from 'cdk-nag';
+
+const app = new App();
+Aspects.of(app).add(new AwsSolutionsChecks());
+```
+
+**Optional - VS Code users**: Install [CDK NAG Validator extension](https://marketplace.visualstudio.com/items?itemName=alphacrack.cdk-nag-validator) for faster feedback on file save.
+
+**For Python/Java/C#/Go projects**: cdk-nag is available in all CDK languages and provides the same synthesis-time validation.
+
+#### Layer 2: Synthesis-Time Validation (Required)
+
+1. **Synthesis with cdk-nag**: Validate stack with comprehensive rules
+   ```bash
+   cdk synth  # cdk-nag runs automatically via Aspects
+   ```
+
+2. **Suppress legitimate exceptions** with documented reasons:
+   ```typescript
+   import { NagSuppressions } from 'cdk-nag';
+
+   // Document WHY the exception is needed
+   NagSuppressions.addResourceSuppressions(resource, [
+     {
+       id: 'AwsSolutions-L1',
+       reason: 'Lambda@Edge requires specific runtime for CloudFront compatibility'
+     }
+   ]);
+   ```
+
+#### Layer 3: Pre-Commit Safety Net
+
+1. **Build**: Ensure compilation succeeds
+   ```bash
+   npm run build  # or language-specific build command
+   ```
+
+2. **Tests**: Run unit and integration tests
+   ```bash
+   npm test  # or pytest, mvn test, etc.
+   ```
+
+3. **Validation Script**: Meta-level checks
+   ```bash
+   ./scripts/validate-stack.sh
+   ```
+
+The validation script now focuses on:
+- Language detection
+- Template size and resource count analysis
+- Synthesis success verification
+- (Note: Detailed anti-pattern checks are handled by cdk-nag)
+
+## Workflow Guidelines
+
+### Development Workflow
+
+1. **Design**: Plan infrastructure resources and relationships
+2. **Verify AWS Services**: Use AWS Documentation MCP to confirm service availability and features
+   - Check regional availability for all required services
+   - Verify service limits and quotas
+   - Confirm latest API specifications
+3. **Implement**: Write CDK constructs following best practices
+   - Use CDK MCP server for construct recommendations
+   - Reference CDK best practices via MCP tools
+4. **Validate**: Run pre-deployment checks (see above)
+5. **Synthesize**: Generate CloudFormation templates
+6. **Review**: Examine synthesized templates for correctness
+7. **Deploy**: Deploy to target environment
+8. **Verify**: Confirm resources are created correctly
+
+### Stack Organization
+
+- Use nested stacks for complex applications
+- Separate concerns into logical construct boundaries
+- Export values that other stacks may need
+- Use CDK context for environment-specific configuration
+
+### Testing Strategy
+
+- Unit test individual constructs
+- Integration test stack synthesis
+- Snapshot test CloudFormation templates
+- Validate resource properties and relationships
+
+## Using MCP Servers Effectively
+
+### When to Use AWS Documentation MCP
+
+**Always verify before implementing**:
+- New AWS service features or configurations
+- Service availability in target regions
+- API parameter specifications
+- Service limits and quotas
+- Security best practices for AWS services
+
+**Example scenarios**:
+- "Check if Lambda supports Python 3.13 runtime"
+- "Verify DynamoDB is available in eu-south-2"
+- "What are the current Lambda timeout limits?"
+- "Get latest S3 encryption options"
+
+### When to Use CDK MCP Server
+
+**Leverage for CDK-specific guidance**:
+- CDK construct selection and usage
+- CDK API parameter options
+- CDK best practice patterns
+- Construct property configurations
+- CDK-specific optimizations
+
+**Example scenarios**:
+- "What's the recommended CDK construct for API Gateway REST API?"
+- "How to configure NodejsFunction bundling options?"
+- "Best practices for CDK stack organization"
+- "CDK construct for DynamoDB with auto-scaling"
+
+### MCP Usage Best Practices
+
+1. **Verify First**: Always check AWS Documentation MCP before implementing new features
+2. **Regional Validation**: Check service availability in target deployment regions
+3. **CDK Guidance**: Use CDK MCP for construct-specific recommendations
+4. **Stay Current**: MCP servers provide latest information beyond knowledge cutoff
+5. **Combine Sources**: Use both skill patterns and MCP servers for comprehensive guidance
+
+## CDK Patterns Reference
+
+For detailed CDK patterns, anti-patterns, and architectural guidance, refer to the comprehensive reference:
+
+**File**: `references/cdk-patterns.md`
+
+This reference includes:
+- Common CDK patterns and their use cases
+- Anti-patterns to avoid
+- Security best practices
+- Cost optimization strategies
+- Performance considerations
+
+## Additional Resources
+
+- **Validation Script**: `scripts/validate-stack.sh` - Pre-deployment validation
+- **CDK Patterns**: `references/cdk-patterns.md` - Detailed pattern library
+- **AWS Documentation MCP**: Integrated for latest AWS information
+- **CDK MCP Server**: Integrated for CDK-specific guidance
+
+## GitHub Actions Integration
+
+When GitHub Actions workflow files exist in the repository, ensure all checks defined in `.github/workflows/` pass before committing. This prevents CI/CD failures and maintains code quality standards.