RFC-004: Sub-Clutches - Nested Pipeline Orchestration

[pontino]

Summary

Add support for nested clutches (sub-clutches), enabling modular pipeline composition and hierarchical orchestration.

Motivation

Complex workflows benefit from modular composition:

• Reusability: Define sub-pipelines once, use in multiple parent clutches
• Encapsulation: Hide implementation details of complex sub-workflows
• Testing: Test sub-clutches in isolation
• Team ownership: Different teams own different sub-clutches

Proposed API

Sub-Clutch Registration

# Define a reusable sub-clutch
validation_clutch = Clutch("validation", strategy=Strategy.SEQUENTIAL)

@validation_clutch.agent()
async def schema_check(data):
    return validate_schema(data)

@validation_clutch.agent()
async def business_rules(data):
    return validate_rules(data)

# Use in parent clutch
main_clutch = Clutch("main", strategy=Strategy.SEQUENTIAL)

main_clutch.add_sub_clutch(
    "validate",
    validation_clutch,
    context_mode=ContextMode.INHERIT,
)

@main_clutch.agent()
async def process(data):
    return transform(data)

Context Modes

class ContextMode(Enum):
    ISOLATED = "isolated"    # Fresh context for sub-clutch
    INHERIT = "inherit"      # Pass parent context
    SCOPED = "scoped"        # Inherit specific fields only

Error Modes

class ErrorMode(Enum):
    PROPAGATE = "propagate"  # Sub-clutch errors bubble up
    CONTAIN = "contain"      # Wrap in SubClutchError, continue

Implementation Scope

Phase 1: Core Sub-Clutch

• SubClutchNode class extending AgentNode
• add_sub_clutch method
• Circular reference detection

Phase 2: Context and Error Modes

• ISOLATED, INHERIT, SCOPED context modes
• PROPAGATE, CONTAIN error modes
• Handover with parent:: prefix support

Phase 3: Distributed Mode

• Namespaced channel support
• State propagation across processes

Reference

See eggai-clutch-rfcs/RFC-004-sub-clutches.md for full specification.