# dirigent_protocol

**Version:** 0.2.0
**Status:** Active Development

ACP/MCP-aligned protocol library for agent-client interactions.

## Quick Links

- **Package README**: [README.md](README.md) - Main documentation
- **Streaming Model**: [docs/streaming_model.md](docs/streaming_model.md) - Detailed SessionUpdate guide
- **Migration Guide**: [docs/migration_from_0.1.md](docs/migration_from_0.1.md) - Upgrading from 0.1.x
- **Architecture Doc**: [../../docs/architecture/protocol.md](../../docs/architecture/protocol.md) - System design

## Purpose

This package provides the core event protocol for Dirigent, enabling:
- Real-time streaming of agent interactions
- Provider-agnostic event representation
- Tool lifecycle management
- Structured content representation

## Key Types

```rust
use dirigent_protocol::{
    Event,              // Top-level event enum
    SessionUpdate,      // Streaming content updates
    ContentBlock,       // Structured content (Text, ResourceLink)
    ToolCall,           // Tool execution state
    ToolCallStatus,     // Pending → Running → Completed/Error
    TurnCompleteTrigger, // How turn completion was detected
};
```

## Event Semantics: MessageCompleted vs TurnComplete vs SessionIdle

Understanding the distinction between these three events is critical for correct system behavior:

### MessageCompleted - "Metadata is ready"
- **Purpose**: Informational - signals that message metadata exists
- **Timing**: Emitted when message record is created, content may still be streaming
- **Consumer action**: Update UI status indicators ("Assistant is typing" → "Complete")
- **Example**: Show message timestamp, update message count

### TurnComplete - "All content received" (ACTIONABLE)
- **Purpose**: **Primary finalization signal** - all content for this turn is complete
- **Timing**: Emitted AFTER all content chunks, tool calls, and metadata updates
- **Consumer action**: **Finalize storage, lock state, trigger post-processing**
- **Example**: Write message to disk, mark as immutable, generate summaries

### SessionIdle - "No recent activity"
- **Purpose**: Informational - indicates session is quiet
- **Timing**: Emitted AFTER TurnComplete as final safety signal
- **Consumer action**: Hide spinners, update activity indicators
- **Example**: Remove "typing" animation, update last activity timestamp

### Event Ordering Guarantee

```text
1. MessageStarted         (message created)
2. SessionUpdate::*Chunk  (content streaming)
3. SessionUpdate::ToolCall* (tool execution)
4. MessageCompleted       (metadata ready) ← UI: "Complete"
5. TurnComplete          ← FINALIZE HERE!
6. SessionIdle           ← UI: hide spinner
```

### Consumer Behavior Table

| Consumer | MessageCompleted | TurnComplete | SessionIdle |
|----------|------------------|--------------|-------------|
| **Archivist** | Ignore | **Finalize and write** | Safety net |
| **UI Cache** | Update status | **Lock state** | Hide spinner |
| **Conductor Bridge** | - | **Flush response** | Fallback flush |

### TurnCompleteTrigger Variants

The `TurnCompleteTrigger` enum indicates **how** the system determined completion:

- **`ExplicitSignal`**: Upstream provider sent explicit completion (e.g., OpenCode session.idle)
- **`ResponseReceived`**: JSON-RPC response received (ACP stdio - response is last message)
- **`OperationsComplete`**: All tracked operations finished (e.g., pending tool calls resolved)
- **`IdleTimeout { duration_ms }`**: Timeout-based detection (fallback mechanism)

**For most consumers**, treat all triggers the same - the turn is complete. The trigger type is primarily for debugging and observability.

## Usage Pattern

```rust
use dirigent_protocol::{Event, SessionUpdate, ContentBlock};

fn handle_event(event: Event) {
    match event {
        Event::SessionUpdate { session_id, update } => {
            match update {
                SessionUpdate::AgentMessageChunk { message_id, content, .. } => {
                    if let ContentBlock::Text { text } = content {
                        println!("Agent: {}", text);
                    }
                }
                SessionUpdate::ToolCall { tool_call, .. } => {
                    println!("Tool: {}", tool_call.tool_name);
                }
                _ => {}
            }
        }
        _ => {}
    }
}
```

## Architecture

```
dirigent_protocol/
├── src/
│   ├── types/           # Core types
│   │   ├── content.rs   # ContentBlock definitions
│   │   ├── updates.rs   # SessionUpdate variants
│   │   ├── tool.rs      # ToolCall, ToolCallStatus
│   │   └── meta.rs      # Provider metadata
│   ├── session.rs       # Session types
│   ├── conversation.rs  # Message types
│   ├── events.rs        # Event enum
│   └── adapters/        # Provider adapters
│       ├── opencode.rs  # OpenCode translation
│       └── rest.rs      # REST translation
├── docs/                # Detailed documentation
├── examples/            # Usage examples
└── tests/               # Integration tests
```

## Version 0.2.0 Changes

**Breaking:**
- Removed `Event::MessagePartAdded`

**New:**
- `SessionUpdate` event system (ACP-style)
- `ContentBlock` types (MCP-compatible)
- `ToolCall` with lifecycle tracking
- Provider metadata via `_meta`

See [docs/migration_from_0.1.md](docs/migration_from_0.1.md) for migration guide.

## Development

### Running Tests
```bash
cargo test --package dirigent_protocol
```

### Checking Code
```bash
cargo check --package dirigent_protocol
```

### Running Examples
```bash
cargo run --package dirigent_protocol --example session_metadata_demo
```

## Integration

This package is used by:
- **api** package: Server functions consume protocol events
- **web** package: UI renders protocol events
- **dirigent_core** (future): Runtime emits protocol events

## Adapters

The adapter system translates provider-specific events to Dirigent Protocol:

- **OpenCodeAdapter**: Translates OpenCode.ai events
- **RESTAdapter**: Converts REST API responses

Adapters preserve provider metadata in the `_meta` field for debugging and traceability.

## Current Scope

**Phase 1 (Implemented):**
- User/Agent/Thought message streaming
- Tool lifecycle (Pending → Running → Completed/Error)
- Text and ResourceLink content types
- Provider metadata support

**Deferred to Future Phases:**
- Plans and mode switching
- Permission system
- Embedded resources (full content)
- Rich media (images, audio)
- Multi-agent communication

See [../../docs/building/03_acp_prep/04_first_order_refactor.md](../../docs/building/03_acp_prep/04_first_order_refactor.md) for the full plan.

## Standards Alignment

**Agent-Client Protocol (ACP):**
- Session-centric streaming
- Separate content types (user/agent/thought)
- Tool status tracking

**Model Context Protocol (MCP):**
- ContentBlock structure
- Resource links
- Extensible content types

Differences from standards are documented in [../../docs/architecture/protocol.md](../../docs/architecture/protocol.md).

## Anti-Patterns

### Timeout-Based Event Waiting (FORBIDDEN)

**Never use timeout-based waiting to receive events that should be available immediately.**

```rust
// ❌ BAD - Race condition waiting for event
async fn wait_for_metadata_event(
    events: &mut broadcast::Receiver<Event>,
    timeout: Duration,
) -> Option<SessionMetadataReceived> {
    let start = Instant::now();
    while start.elapsed() < timeout {
        match tokio::time::timeout(Duration::from_millis(100), events.recv()).await {
            Ok(Ok(Event::SessionMetadataReceived { .. })) => return Some(...),
            _ => continue,
        }
    }
    None
}
```

**Why this is wrong:**
1. **Race condition**: The event may have been emitted before the receiver subscribed
2. **Arbitrary delays**: 500ms waits add latency for no good reason
3. **Silent failures**: Timeout expiring doesn't indicate the real problem
4. **Fragile**: Works "most of the time" but fails under load or timing variations

**Instead, pass data directly:**
```rust
// ✅ GOOD - Extract data from existing events
async fn create_session_in_connector(...) -> Result<(String, Option<Models>, Option<Modes>), String> {
    // The SessionCreated event already contains models/modes
    match event {
        Event::SessionCreated { session, .. } => {
            Ok((session.id, session.models, session.modes))
        }
    }
}
```

**Rule**: If you find yourself writing `timeout(Duration::from_millis(N), events.recv())` to wait for an event that "should" arrive, the architecture is wrong. Refactor to pass data directly through return values or existing event payloads.

## Contributing

When adding features:
1. Update type definitions in `src/types/`
2. Add comprehensive tests
3. Update documentation in `docs/`
4. Add examples if applicable
5. Update CHANGELOG.md

## See Also

- Main project: [../../CLAUDE.md](../../CLAUDE.md)
- Architecture docs: [../../docs/architecture/](../../docs/architecture/)
- Building docs: [../../docs/building/](../../docs/building/)