Consider streaming-first architecture for subagents and background operations

[evansenter]

Context

Clemini currently uses manual Delta accumulation in a loop:

loop {
    tokio::select! {
        Some(event) = stream.next() => { /* accumulate function calls */ }
        _ = cancellation_token.cancelled() => { break; }
    }
}
// Execute tools after stream completes

This works well for the current single-agent, sequential model. However, if we want to add:

• Subagents - spawning child agents for parallel work
• Background bash - commands that run while conversation continues
• Parallel tool execution - fire multiple tools at once
• File watchers - reactive events during session

...the manual loop approach becomes unwieldy with N concurrent sources.

Related Issues

These are the specific features that would benefit from streaming-first architecture:

Feature	Issue	Status
Subagents (RFC)	#3	🔮 RFC
Task tool (implementation)	#78	📋 Ready to implement
Background bash	#13, #69, #70	✅ Implemented
Parallel tool execution	#76	🔮 Speculative
File watchers	#77	🔮 Speculative

Note: #78 (Task tool) can be implemented today using process-based approach—no streaming-first refactor needed. See comment below for details.

Proposed Pattern: Stream<Item = Result<Event>>

Instead of manual accumulation, agents return a stream of events:

trait Agent {
    fn execute(&self, query: &str, ctx: Context) -> impl Stream<Item = Result<AgentEvent>>;
}

Events could be:

enum AgentEvent {
    // Progress
    TextDelta(String),
    ToolExecuting { name: String, args: Value },
    ToolCompleted { name: String, result: Value, duration: Duration },
    
    // Subagents
    SubagentSpawned { id: String, query: String },
    SubagentEvent { id: String, event: Box<AgentEvent> },
    
    // Background operations  
    BackgroundStarted { id: String, command: String },
    BackgroundOutput { id: String, chunk: String },
    BackgroundCompleted { id: String, exit_code: i32 },
    
    // Completion
    FinalResult { content: String, metadata: Value },
    
    // Extensible
    Custom { event_type: String, data: Value },
}

Why this helps

Multiple concurrent sources merge cleanly:

let merged = select_all(vec![
    main_agent.execute(query, ctx).boxed(),
    subagent.execute(sub_query, ctx).boxed(),
    background_monitor.boxed(),
]);

while let Some(event) = merged.next().await {
    // Uniform handling regardless of source
}

Hierarchical cancellation: Parent stream dropping cancels children via standard Rust drop semantics.

Composability: Interceptors/middleware wrap streams without changing agent code:

let logged = agent.execute(query, ctx)
    .inspect(|e| log::debug!("{:?}", e));

Reference Implementation

Gemicro uses this pattern in its agent trait:

• Trait definition: agents/gemicro-core/src/agent.rs
• Event types: gemicro-core/src/update.rs
• Example agent: agents/gemicro-prompt-agent/

Key patterns from gemicro:

1. AgentUpdate::custom(event_type, message, data) for soft-typed extensibility
2. AgentUpdate::final_result() signals completion
3. Unknown event types are logged and ignored, not errors

Trade-offs

Aspect	Current (manual loop)	Streaming-first
Simplicity	✓ Simpler for single-agent	More abstraction
Cancellation	✓ Fine-grained control	Cooperative via drop
Concurrency	✗ Doesn't scale	✓ Merges cleanly
genai-rs integration	✓ Direct	Needs adapter layer

Recommendation

Don't implement this now—the current approach is right for clemini's current scope. But if/when we add subagents or background operations, this pattern becomes valuable enough to justify the refactor.

This issue exists to document the pattern for future reference.

[evansenter]

Update: Created evansenter/gemicro#266 to extract gemicro-streaming-events as a minimal shared crate.

Key findings from analysis:

• The streaming types (AgentUpdate, ResultMetadata, FinalResult) have zero internal gemicro dependencies — just serde + serde_json
• Extraction is a straightforward refactor (~225 lines of code)
• Clemini can adopt via adapter pattern from InteractionProgress → AgentUpdate

This unblocks streaming-first architecture for clemini without pulling in all of gemicro-core.

[evansenter]

Stepping Stone: Tool Output via Events

We're implementing a stepping stone toward this architecture: routing tool output through the event system.

Current Problem

5 tools call log_event() directly (bash, todo_write, ask_user, kill_shell, edit), bypassing the event channel. This causes race conditions between async events and direct logging, resulting in wrong output order.

Solution

Add AgentEvent::ToolOutput(String) and give tools access to the event sender. Tools emit events instead of calling log_event() directly.

How This Aligns with #59

• Our ToolOutput event fits the proposed Stream<Item = AgentEvent> model
• Establishes the pattern: tools → events → handlers
• When Consider streaming-first architecture for subagents and background operations #59 is implemented, tools would emit to their stream instead of events_tx
• This work is incremental progress without requiring the full streaming-first refactor

Implementation

PR coming shortly with:

1. New ToolOutput event variant
2. on_tool_output handler method
3. Event sender injection into tools
4. Tool updates to emit events

This ensures correct output ordering while keeping the door open for the full streaming architecture later.

[evansenter]

Note: Process-Based Approach Works Without This Refactor

For Claude Code-style Task (subagents) functionality, a process-based approach works without streaming-first architecture:

// Pseudocode for task tool
fn task_tool(prompt: &str, background: bool) -> Result<Value> {
    let child = Command::new("cargo")
        .args(["run", "--", "-p", prompt])
        .spawn()?;
    
    if background {
        // Store handle, return task_id for later retrieval
        Ok(json!({"task_id": "abc123", "status": "running"}))
    } else {
        // Wait and return output
        let output = child.wait_with_output()?;
        Ok(json!({"output": String::from_utf8_lossy(&output.stdout)}))
    }
}

Why this works:

• Each subprocess is a fresh clemini instance with its own context
• No shared state between parent and child agents
• Parent can fire-and-forget (background) or wait for completion
• No streaming coordination needed - just process lifecycle management

This issue (#59) becomes valuable for:

• Real-time streaming of child agent output to parent
• Shared context/memory between agents
• Coordinated cancellation across agent trees
• Unified event streams for complex multi-agent workflows

The process-based approach is a solid MVP. This streaming-first refactor would enable more sophisticated agent coordination later.