Implement Capability-Based Bundle Abstraction

[robotdad]

Summary

Abstract bundles into user-facing "capabilities" that can be toggled on/off in settings. Users should never think about bundles - they see features they want to enable ("Browser Testing", "Python Development", etc.).

Current State

We have ~60% of the foundation in place:

• ✅ Capability-to-bundle mapping (Feature dataclass in features.py)
• ✅ Dependency tracking (requires field exists)
• ✅ Overlay-based bundle composition (Hybrid Pattern)
• ✅ Provider registration (exemplary 3-phase system)

What's Missing

• ❌ Dependency resolution - Topological sort to handle capability dependencies
• ❌ Hot-reload support - Toggle capabilities without server restart (Session ID Reuse pattern)
• ❌ Prerequisite checking - Verify external dependencies (e.g., agent-browser CLI)
• ❌ REST API endpoints - /api/capabilities for management
• ❌ Settings UI - Capability toggle cards in web interface

Architecture Analysis

Complete architectural analysis and implementation guidance available in session working directory:

Key Documents

1. distro-capability-implementation-review.md (19KB) - Gap analysis and roadmap
2. quick-start-guide.md (12KB) - Get to working system in ~2 hours
3. capability-based-bundle-architecture.md (29KB) - Complete specification
4. implementation-examples.py (23KB) - Working code for all components
5. SUMMARY.md (11KB) - Quick reference

Implementation Phases

Phase 1: Core Capability System (Week 1-2)

• Add DependencyResolver class with topological sort
• Add enabled_capabilities field to DistroSettings
• Create CapabilityManager class
• Add REST API endpoints (/api/capabilities)
• Test end-to-end capability toggle

Phase 2: Hot-Reload (Week 3)

• Implement SessionReconfigurationManager
• Use Session ID Reuse pattern for live reconfiguration
• Add debouncing for rapid changes
• Handle edge cases (mid-execution reload)

Phase 3: UI Integration (Week 4)

• Build settings page with capability cards
• Add toggle switches for each capability
• Show dependency warnings
• Display prerequisite status
• Add settings forms (conditional on enabled)

Phase 4: Advanced Features (Week 5+)

• Custom bundle registration (advanced mode)
• Prerequisite checking system
• Migration from existing bundle.md
• Capability presets ("Data Science", "Web Dev", etc.)

Key Patterns from Foundation

Session ID Reuse (Hot-Reload)

# When user toggles capability:
new_bundle = await compose_from_capabilities(new_enabled_list)
new_prepared = await new_bundle.prepare()
await old_session.close()

# SAME session_id = context preserved!
new_session = await new_prepared.create_session(
    session_id=old_session.session_id
)

3-Phase Capability Registration

Following our existing provider pattern:

def enable_capability(capability_id: str):
    # 1. Resolve dependencies
    ordered, warnings = resolver.resolve([capability_id])
    
    # 2. Update settings
    add_to_enabled_capabilities(ordered)
    
    # 3. Update overlay
    for cap in ordered:
        for include in FEATURES[cap].includes:
            overlay.add_include(include)

Files to Create/Modify

amplifier-distro/distro-server/src/amplifier_distro/
├── capability_resolver.py        # NEW - Dependency resolution
├── capability_manager.py          # NEW - Capability enable/disable logic
├── features.py                    # MODIFY - Add prerequisite checking
├── distro_settings.py             # MODIFY - Add enabled_capabilities field
├── overlay.py                     # EXISTING - Works as-is
└── server/
    └── app.py                     # MODIFY - Add /api/capabilities endpoints

Testing Strategy

1. Unit tests for DependencyResolver (circular dependency detection)
2. Integration tests for CapabilityManager (enable/disable flow)
3. API tests for endpoints (capability toggle, settings persistence)
4. E2E tests for hot-reload (verify no restart needed)

Success Criteria

• User can enable/disable capabilities via settings UI
• Dependencies are automatically resolved
• Changes apply without server restart
• Missing prerequisites show clear warnings
• Overlay stays in sync with enabled capabilities
• Provider registration continues to work unchanged

References

• Foundation: APPLICATION_INTEGRATION_GUIDE.md (Session ID Reuse, Hybrid Pattern)
• Foundation: PATTERNS.md (Bundle composition)
• Foundation: BUNDLE_GUIDE.md (Thin bundle pattern)

Notes

Our existing provider registration system is exemplary and follows foundation best practices. The capability system should use the same 3-phase pattern (resolve → settings → overlay).

Session ID: 3ceab724-0f25-44ea-b0bd-3d6dd1011e07