AI Chat: Bedrock integration with streaming, session persistence, AWS docs search

[yimsk]

Summary

• AI chat overlay (Ctrl+L) with Bedrock Converse API streaming
• Session persistence with tool use/result tracking
• Extended thinking mode for complex queries
• AWS docs search tool (search_aws_docs)
• Session history UI (Ctrl+H)
• Tool call limit (max 50/query, configurable)
• Resource pagination (100 default, 2000 max)
• Session pruning optimization (1000x faster)

Configuration

New AI section in config.yaml:

ai:
  profile: ""        # AWS profile for Bedrock (empty = current profile)
  region: ""         # AWS region (empty = current region)
  max_tool_calls_per_query: 50
  max_tool_rounds: 15
  session_persistence: false
  max_sessions: 100

Test Plan

• Unit tests pass (bedrock_test.go, session_test.go, tools_test.go)
• Code review complete (no blocking issues)
• Manual testing: chat overlay lifecycle
• Manual testing: session save/load
• Manual testing: tool execution (list/getresources)
• Manual testing: multi-turn conversations
• Manual testing: stream cancellation
• Manual testing: region/profile context

Related

Closes #123

[claude]

Pull Request Review: AI Chat with Bedrock Integration

This is an impressive and well-executed feature addition! The AI chat overlay with AWS Bedrock integration adds significant value to claws. The implementation demonstrates good architectural design, comprehensive testing, and attention to detail.

---

✅ Strengths

1. Architecture & Code Quality

• Clean separation of concerns: The internal/ai/ module is well-structured with distinct responsibilities:
  • bedrock.go: API client and streaming
  • session.go: Session persistence
  • tools.go: Tool execution
• Consistent error handling: Proper use of apperrors.Wrap() throughout
• Context propagation: Excellent use of context for cancellation, region/profile overrides, and filters
• Stream cancellation: Proper cleanup with mutex-protected streamCancel to prevent goroutine leaks (lines 98-238 in chat_overlay.go)

2. Security

• File permissions: Session files use 0600 and directories use 0700 - excellent for protecting sensitive data
• Tool call limits: Defense-in-depth with max_tool_calls_per_query (default 50) to prevent LLM runaway
• Input validation: Proper bounds checking on pagination offset/limit parameters
• Safe resource access: Profile/region isolation through AWS SDK context

3. Performance

• Session pruning optimization: Smart use of file modification time instead of JSON parsing - 1000x faster!
• Resource pagination: Sensible defaults (100) with max limit (2000) to prevent memory issues
• Concurrent region fetching: Already leverages existing multi-region infrastructure
• Streaming response: Real-time UI updates via ConverseStream API

4. User Experience

• Session persistence: Optional (default off for privacy) with history UI (Ctrl+H)
• Extended thinking: Collapsible reasoning blocks for complex queries
• Context awareness: Automatically detects current resource, service, region, profile
• Tool result display: Collapsible tool calls to reduce noise
• Error feedback: Clear error messages with actionable guidance

5. Testing

• Comprehensive coverage: 998 lines of tests across 3 test files
  • bedrock_test.go: 287 lines
  • session_test.go: 385 lines
  • tools_test.go: 326 lines
• Unit tests: Well-isolated tests for core functionality
• Edge cases: Tests cover error conditions, empty states, limits

6. Documentation

• New doc: docs/ai-chat.md with setup and usage guide
• IAM permissions: Clear documentation of required Bedrock permissions
• Configuration: Well-documented AI config section with sensible defaults
• README: Updated with screenshot and feature description

---

🔍 Code Quality Observations

Excellent Practices

1. Type safety: Strong typing with custom types (Role, StopReason, ContextMode)
2. Helper functions: Clean abstractions like NewUserMessage(), formatResourceDetail()
3. Stream processing: Proper state machine for handling streaming events
4. Resource unwrapping: Consistent use of dao.UnwrapResource() for wrapper handling
5. Timeout handling: Context-based cancellation in AWS docs search

Minor Observations

1. UUID dependency: Added as direct dependency (good - not indirect)
2. Magic numbers: Some constants could be named (e.g., 10 buffer size on line 168)
3. Error logging: Consistent use of log.Debug/Warn - good logging hygiene

---

🛡️ Security Considerations

✅ Well Handled

• Session data protected with proper file permissions
• Tool execution sandboxed to read-only AWS API calls
• No command injection risks (uses AWS SDK, not shell commands)
• Profile/region isolation prevents cross-account leaks
• Tool call limits prevent abuse

💡 Recommendations (Future)

1. Rate limiting: Consider per-session rate limits for API calls
2. Audit logging: Consider logging AI queries for compliance (opt-in)
3. Token budget: The thinkingBudget is configurable - good for cost control

---

🐛 Potential Issues

No Critical Issues Found! ✨

Minor Considerations

1. tools.go:322-324: Offset validation correctly returns isError=true - good catch from review
2. Pagination bounds: Properly handled with clear error messages
3. Race condition: Fixed with mutex on streamCancel assignment
4. Session directory: Created with 0700 permissions - excellent

---

🧪 Test Coverage

The test coverage is excellent:

1. bedrock_test.go: Tests client initialization, message conversion, tool configuration
2. session_test.go: Tests session creation, persistence, pruning, history
3. tools_test.go: Tests all 5 tools with various scenarios

Strengths:

• Tests use table-driven approach
• Edge cases covered (empty inputs, invalid offsets, missing resources)
• Session pruning tested with file count verification

---

📋 Best Practices Adherence

Follows Project Conventions ✅

1. DAO pattern: tools.go properly uses registry.GetDAO() and context filters
2. Error wrapping: Consistent use of apperrors.Wrap()
3. Config management: Uses config.File() for all configuration
4. Import organization: Fixed with goimports in final commits
5. Generated files: Properly added task-definitions/constants.go

Architecture Alignment ✅

1. Registry usage: Proper integration with resource registry
2. Context filtering: Follows established patterns for ECS cluster context
3. Multi-region support: Works seamlessly with existing infrastructure
4. Modal system: Follows existing modal patterns (width constants, lifecycle)

---

🚀 Performance Considerations

✅ Optimized

1. Session pruning: O(n log n) file sorting vs O(n) JSON parsing - huge win
2. Resource limits: Prevents unbounded API calls with sensible defaults
3. Stream buffering: 10-event buffer on channel to reduce blocking
4. Lazy loading: Sessions loaded on-demand, not upfront

💡 Future Optimizations

1. Caching: Consider caching AWS docs search results (future enhancement)
2. Tool result truncation: Very large resources might overwhelm context (already has limits)
3. Concurrent tool execution: Currently sequential - could parallelize independent tools (future)

---

📊 Metrics

• Lines Added: 5,480
• Lines Deleted: 234
• Files Changed: 93
• Test Files: 3 (998 lines of tests)
• Commits: 32 (incremental improvements based on reviews)
• Services Enhanced: 62 resources got Data field added for AI access

---

🎯 Recommendations

Before Merge

✅ All items addressed in the PR already!

Future Enhancements (Out of Scope)

1. Multi-turn conversation optimization: Implement conversation summarization for long sessions
2. Tool call caching: Cache identical tool calls within same session
3. Parallel tool execution: Execute independent tools concurrently
4. Cost tracking: Optional per-session token/cost tracking
5. Export conversations: Export chat history as markdown/JSON

---

🏆 Final Assessment

Recommendation: ✅ APPROVE and MERGE

This PR represents exceptional work:

• ✅ Clean architecture with excellent separation of concerns
• ✅ Comprehensive testing (998 lines)
• ✅ Strong security posture (file permissions, rate limits)
• ✅ Performance optimizations (1000x faster pruning)
• ✅ Great UX (session history, collapsible sections, context awareness)
• ✅ Well documented (new doc, updated README, IAM guide)
• ✅ Follows all project conventions and patterns
• ✅ No critical issues or bugs identified

The 32 commits show iterative refinement based on code review feedback, demonstrating excellent engineering discipline. The feature is production-ready and adds significant value to claws.

Excellent work! 🎉

---

📝 Detailed Comments by File

internal/ai/bedrock.go

• Line 175-213: Well-structured thinking config with proper beta flag
• Line 299-416: Stream processing handles all event types correctly
• Line 230-275: Content block conversion handles all cases (text, tool use, tool result, reasoning)

internal/ai/session.go

• Line 260-263: Directory permissions 0700 - excellent security
• Line 265-273: File permissions 0600 - excellent security
• Line 296-345: Pruning optimization using mtime - brilliant!

internal/ai/tools.go

• Line 266-345: Resource pagination with proper bounds checking
• Line 322-324: Offset validation returns isError=true ✅
• Line 636-720: AWS docs search with proper timeout handling

internal/view/chat_overlay.go

• Line 98-101: Mutex-protected stream cancel - prevents race conditions ✅
• Line 231-238: Proper cleanup on cancel
• Line 274-284: Session persistence with error handling

custom/ecs/task-definitions/

• Well-implemented new resource type
• Proper navigation from services/tasks
• Log group extraction for tail_logs tool

---

Review completed with focus on code quality, security, performance, testing, and architecture alignment.