RFC: Publish Trajectory Events to Event Bus for Cross-Session Debugging

[evansenter]

Summary

Add optional trajectory event publishing to the event bus, enabling cross-session debugging and observability.

Background

This is the gemicro-side implementation of cross-session debugging described in dotfiles#57.

Prerequisites:

• RFC: REPL Session Registration with Event Bus #195 - REPL session registration (session presence)
• feat(core): Add SSE-based event push notifications (#181) #190 - HubCoordination with SSE

What this adds: Publishing trajectory step events so other sessions/tools can observe what's happening.

Proposed Design

New Event Types

// Published to event bus during agent execution
pub enum TrajectoryEvent {
    /// LLM request/response completed
    StepCompleted {
        phase: String,
        model: String,
        tokens_in: usize,
        tokens_out: usize,
        duration_ms: u64,
        tool_calls: Vec<String>,
    },
    
    /// Tool execution failed
    ToolFailed {
        tool_name: String,
        error: String,
    },
    
    /// Agent entered new phase
    PhaseStarted {
        phase: String,
    },
    
    /// Agent completed phase
    PhaseCompleted {
        phase: String,
        success: bool,
    },
}

Integration Point

Option A: Hook into TrajectoryBuilder

impl TrajectoryBuilder {
    pub fn with_event_publisher(mut self, publisher: EventBusPublisher) -> Self {
        self.event_publisher = Some(publisher);
        self
    }
    
    pub fn add_step(&mut self, step: TrajectoryStep) {
        self.steps.push(step.clone());
        
        // Publish to event bus if configured
        if let Some(publisher) = &self.event_publisher {
            publisher.publish(TrajectoryEvent::StepCompleted { ... });
        }
    }
}

Option B: Wrap AgentRunner with event publishing

pub struct ObservableAgentRunner {
    inner: AgentRunner,
    publisher: EventBusPublisher,
}

Recommendation: Option A - less wrapper overhead, direct integration.

Payload Structure

{
  "type": "trajectory_step_completed",
  "session_id": "gemicro-abc123",
  "correlation_id": "workflow-xyz",
  "step": {
    "phase": "research",
    "model": "claude-sonnet-4-20250514",
    "tokens_in": 1500,
    "tokens_out": 450,
    "duration_ms": 2300,
    "tool_calls": ["web_search", "file_read"]
  }
}

Configuration

# Enable trajectory publishing
gemicro -i --event-bus-url http://localhost:8765 --publish-trajectory

# With correlation ID for cross-session tracing
gemicro -i --event-bus-url http://localhost:8765 --publish-trajectory --correlation-id "feature-auth"

Privacy Considerations

• No LLM content: Only metadata (model, tokens, duration, tool names)
• Opt-in: --publish-trajectory flag required
• Correlation IDs: User-provided, not auto-generated from content

Success Criteria

• Trajectory events appear in event bus when --publish-trajectory enabled
• Events include session_id for attribution
• Optional correlation_id for cross-session tracing
• No performance degradation when publishing disabled

Related

• RFC: REPL Session Registration with Event Bus #195 - Session registration (prerequisite)
• feat(core): Add SSE-based event push notifications (#181) #190 - HubCoordination with SSE
• Add structured observability with tracing crate #81 - Structured observability with tracing (could integrate)
• dotfiles#57 - Original RFC (blocked on this)
• [claude-event-bus#TBD] - Event bus storage side

[evansenter]

Cross-reference: The event-bus storage side is tracked in claude-event-bus#55.