PRD: Capability-Based Architecture for Composable AI Agents (v3)

[yacosta738]

Real Problem (not the symptom)

Your current system (sessionRAS based on traits) has a clear issue:

• It is optimized for a single large agent, not for composability
• Current traits (providers, channels, etc.) are coupled to a specific runtime
• You cannot extract capabilities as independent reusable modules
• Each new agent → likely code duplication or logic branching

👉 Translation: you are in a modular monolith, not a composable system

---

Strategic Objective

Move to a model of:

Composable Agent Capabilities Platform

Where each capability (channels, providers, media processing, etc.) is independent, plug-and-play, and self-descriptive with clear contracts.

Architecture Proposal

1. From traits → capabilities (modules)

```rust
struct Capability {
id: CapabilityId,
version: Version,
contracts: Contracts,
dependencies: Vec,
runtime_hooks: Hooks,
}
```

2. Explicit Contracts

```rust
trait ChannelInput {
fn input_type(&self) -> InputType;
fn payload(&self) -> &dyn Any;
}

trait ChannelAdapter {
fn can_handle(&self, input: &dyn ChannelInput) -> bool;
fn transform(&self, input: &dyn ChannelInput) -> NormalizedMessage;
}
```

3. Capability Registry

```
CapabilityRegistry
├── channels
├── providers
├── tools
└── processors
```

Responsibilities: dynamic discovery, dependency resolution, versioning, lazy loading.

4. Dependency Graph

```
Agent
├── declares: [channels, providers]
├── runtime resolves dependencies
└── injects capabilities
```

5. Execution Pipeline

```
Input → Normalization → Routing → Processing → Output
```

Expected Impact

• Modular agent composition
• Reduce code duplication across agents
• Faster development of specialized agents
• Clear extension model for third-party integrations

Scope - v3

• M1: Design contracts and interfaces
• M2: Implement CapabilityRegistry
• M3: Implement dependency resolution
• M4: Implement execution pipeline
• M5: Integration tests and documentation

Trade-offs

• Initial refactor cost (high)
• Need for strict contracts (initial pain)
• More complexity in runtime (dependency resolution)

Risks

1. You will create a fake plugin system (coupled underneath)
2. Contracts will be implicit → hard-to-debug bugs
3. Each capability will start depending on others internally → chaos

[linear]

DALLAY-249