Streaming Progress Feed

Multi-line rolling status feed for tool progress during streaming

Replace the single overwritten tool line with a bounded, multi-line rolling status feed.

# Before — one overwritten line, looks frozen on long runs
🤔 Running web_search...

# After (progress_style="feed") — stable, in-place rolling feed
✓ web_search — 5 results
⏳ fetch_url
⏳ write_file — report.md

The compositor is a pure transform: ⏳ running, ✓ done, ✗ error.

Quick Start

1. Turn it on for a bot

   Set progress_style: feed under a channel’s streaming block in your bot YAML:

   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       streaming:
         mode: progress
         progress_style: feed

2. Tune the window

   Cap how many lines and characters the feed shows:

   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       streaming:
         mode: progress
         progress_style: feed
         progress_max_lines: 8
         progress_max_line_chars: 120

3. Build your own renderer

   The core compositor is pure and reusable — fold events, then render:

   from praisonaiagents.streaming import ProgressLine, merge_progress_line, render_progress
   
   lines = []
   for event in agent_events:
       lines = merge_progress_line(lines, event)
   
   print(render_progress(lines, max_lines=8, max_line_chars=120))

How It Works

Events fold by correlation id, so the same tool’s line advances in place from running to done or error.

The same correlation id updates the same line in place. Terminal states are sticky: once a line is error (or done), a late running event never downgrades it back.

Configuration Options

The streaming block accepts these keys per channel. Defaults preserve today’s single-line behaviour exactly.

The core render_progress function takes the same limits as keyword arguments max_lines and max_line_chars.

State Semantics

Each event type maps a line to a state and glyph.

A ProgressLine carries id, kind (tool, plan, approval, or command-output), text, and state (running, done, or error).

Best Practices

Related