[Feature] Consumption and trait transfer when agent reaches target

[dpid]

The Problem

The library handles broadcasting and receiving, but what happens when an agent actually reaches its target? There's no built-in mechanism for:

• Consuming traits from items (eating food reduces food's quantity)
• Transferring traits (picking up gold increases agent's gold)
• Depleting items (item runs out and should stop broadcasting)

Current Behavior

Developers must implement all consumption logic manually:

```typescript
// No built-in support for this common pattern
function onAgentReachesTarget(agent, item) {
const food = item.stats.getTrait('food');
const desire = agent.desires.getTrait('food');

if (food && desire) {
const amount = Math.min(food.quantity, desire.quantity);
food.quantity -= amount;
desire.quantity -= amount;

// Manually stop broadcasting when depleted
if (food.quantity <= 0) {
  item.data.broadcastDistance = 0;  // Hacky
}

}
}
```

Proposed Solution

```typescript
// Consumption command/action
const consumeAction = ConsumeTraits.create(agent, item, {
traits: ['food'],
rate: 10, // per second (for gradual consumption)
onDepleted: () => { /* callback */ }
});

// Or simpler instant consumption
agent.consumeFrom(item, 'food', 50); // Transfer up to 50 food

// Items auto-stop broadcasting when depleted
itemData.autoDepletebroadcast = true;
```

Why This Matters

The full loop of needs-based AI is: need → discover → pursue → consume → satisfy

This library handles the middle three steps but not the final consumption/satisfaction. That's where the simulation actually happens.