[Feature]: Add progress notifications for sandbox operations to prevent user uncertainty and system lag

[louisdevzz]

Summary

Add real-time progress notifications when the agent is performing sandbox operations to keep users informed, prevent repeated inquiries, and avoid system lag from message loops.

Problem statement

Currently, when ZeroBuild's agent performs sandbox operations (creating sandbox, installing dependencies, building projects, running tests), users receive no progress updates. This creates several critical issues:

1. User uncertainty: Users cannot tell if the agent is actively working, stuck, or has crashed
2. Repeated inquiries: Users send multiple "are you there?" or "what's happening?" messages when they see no response
3. System lag: Each repeated inquiry triggers the agent to re-process, causing performance degradation and potential infinite loops
4. Poor UX: Users feel disconnected from the process and lose trust in the autonomous system
5. No visibility: For long-running operations (e.g., npm install, cargo build), users have no idea how much progress has been made

Example scenario:

• User requests: "Build a Next.js app"
• Agent starts: Creating sandbox, running npx create-next-app, installing dependencies
• User sees: No response for 2-3 minutes
• User sends: "Hello?", "Are you working?", "What's the status?"
• Agent receives: Multiple messages, tries to respond to each, gets confused, system lags

This pattern severely degrades the user experience and wastes computational resources.

Proposed solution

Implement a comprehensive progress notification system for all sandbox operations:

1. Status Message Categories

Operation Start:

🚀 Starting up the build environment...

Progress Updates:

📦 Creating project structure... (Step 1/5)
📥 Installing dependencies... This may take a few minutes (Step 2/5)
🔨 Building your project... (Step 3/5)
✅ Build complete! Starting server... (Step 4/5)
🌐 Getting your preview link... (Step 5/5)

Completion:

✨ Done! Your project is ready at: [URL]

Error/Retry:

⚠️  Encountered an issue: [brief description]
🔧 Retrying with alternative approach...

2. Implementation Strategy

A. Progress Callback Integration

• Inject progress callbacks into sandbox tool execution
• Trigger status updates at key milestones (start, 25%, 50%, 75%, complete)
• Use spinner/progress indicators for long-running operations

B. Smart Timing

• Send first update within 2 seconds of operation start
• Subsequent updates every 10-15 seconds for long operations
• Final confirmation immediately upon completion
• Error notifications within 1 second of failure

C. Operation-Specific Messages

Tool	Start Message	Progress	Complete
sandbox_create	"Starting up the build environment..."	N/A	"Build environment ready"
sandbox_run_command (scaffold)	"Creating your project..."	Progress %	"Project created"
sandbox_run_command (install)	"Installing dependencies..."	Time elapsed	"Dependencies installed"
sandbox_run_command (build)	"Building your project..."	Progress %	"Build successful"
sandbox_get_preview_url	"Getting your preview link..."	N/A	"Preview ready"
sandbox_save_snapshot	"Saving your project files..."	N/A	"Project saved"

D. Throttling & Deduplication

• Implement message queue to prevent spam
• Deduplicate rapid sequential operations
• Limit to max 1 update per 5 seconds unless error

3. Configuration Options

# In config file or env vars
agent:
  notifications:
    enabled: true
    verbosity: normal  # minimal, normal, detailed
    update_interval_sec: 10
    show_timestamps: false

Verbosity Levels:

• minimal: Only start and complete messages
• normal: Start, progress (every 15s), complete, errors
• detailed: All steps with timing information

4. Technical Implementation

// Add to Agent context
pub struct ProgressNotifier {
    channel: Channel,
    last_update: Instant,
    min_interval: Duration,
    verbosity: Verbosity,
}

impl ProgressNotifier {
    pub async fn notify(&mut self, stage: &str, message: &str) {
        if self.should_notify() {
            self.channel.send_message(format!("{} {}", stage, message)).await;
            self.last_update = Instant::now();
        }
    }
    
    pub async fn notify_progress(&mut self, operation: &str, percent: u8) {
        if self.should_notify() {
            self.channel.send_message(
                format!("{} {}% complete...", operation, percent)
            ).await;
        }
    }
}

5. Integration Points

• Tool trait: Add with_progress() method to tools
• Sandbox tools: Automatic progress for all sandbox operations
• Channel layer: Support for message updates/edits (if supported)
• Error handling: Immediate notification on failures

Non-goals / out of scope

• Real-time streaming of command output (too verbose)
• Progress bars in terminal (focus is on message-based channels)
• Predictive time estimates (too complex for initial implementation)
• Multi-user collaboration status (single user focus)
• Integration with external monitoring tools

Alternatives considered

1. Silent mode with periodic heartbeat

   • Send "Still working..." every 30 seconds
   • Rejected: Less informative, doesn't show actual progress

2. Wait for user to ask

   • Only respond when user sends "status?"
   • Rejected: Doesn't solve the root problem of user uncertainty

3. Log streaming

   • Stream all logs to user in real-time
   • Rejected: Too verbose, overwhelming, security concerns

4. Completion-only notification

   • Only notify when done
   • Rejected: Doesn't address long-running operation uncertainty

Acceptance criteria

• Progress messages sent within 2 seconds of operation start
• Progress updates every 10-15 seconds for operations >30 seconds
• Completion notification sent immediately upon success
• Error notification sent within 1 second of failure
• No duplicate messages within 5-second window
• Configurable verbosity levels (minimal, normal, detailed)
• Works across all supported channels (CLI, Telegram, Discord, Slack)
• Progress notifications for all sandbox operations (create, run, write, read)
• Documentation updated in AGENTS.md with message format examples
• Reduce "status inquiry" user messages by 80% (measured in beta)

Architecture impact

• src/agent/: Add ProgressNotifier to agent context
• src/tools/: Extend Tool trait with progress callback support
• src/tools/sandbox/: Integrate progress notifications into all sandbox tools
• src/channels/: Ensure channels support message throttling/deduplication
• src/config/: Add notification configuration schema
• AGENTS.md: Document progress notification behavior and configuration

Risk and rollback

Risk: Increased message volume could overwhelm users or rate limits.
Mitigation: Implement smart throttling, deduplication, and configurable verbosity.

Risk: Progress estimation may be inaccurate, causing confusion.
Mitigation: Use stage-based progress (Step X/Y) rather than percentage where estimation is unreliable.

Risk: Additional async complexity in tool execution.
Mitigation: Progress notifier is fire-and-forget; doesn't block tool execution.

Risk: Users on high-latency channels may see delayed updates.
Mitigation: Updates are best-effort; critical messages (start/complete/error) are prioritized.

Rollback:

• Feature flag: progress_notifications_enabled: false
• Revert to single "done" message on completion
• Disable via config without code change

Breaking change?

No

This is purely additive functionality. Existing behavior (silent operation) can be maintained via configuration.

Data hygiene checks

• I removed personal/sensitive data from examples, payloads, and logs.
• I used neutral, project-focused wording and placeholders.