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.

Option	Type	Default	Description
progress_style	"line" | "feed"	"line"	Legacy overwritten line vs. new multi-line feed.
progress_max_lines	int	8	Trailing lines shown in feed style.
progress_max_line_chars	int	120	Per-line cap; word-aware truncation.

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.

Event type	Line state	Glyph
TOOL_CALL_START / DELTA_TOOL_CALL	running	⏳
TOOL_CALL_END / TOOL_CALL_RESULT	done	✓
TOOL_PROGRESS	running (command-output kind)	⏳
ERROR	error (terminal, sticks)	✗

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

The default progress_style="line" is byte-identical to today’s behaviour. The feed is fully opt-in — nothing changes until you set progress_style: feed.

---

Best Practices

Use feed for long multi-tool turns

The rolling feed shines when a turn calls several tools. Short single-tool turns are fine with the default line style.

Keep max_lines small on chat platforms

Chat platforms rate-limit message edits. A small progress_max_lines keeps the rendered feed compact and edit-friendly.

Log errors even though the feed shows them

The feed renders ✗ for errors, but keep your own error logging — the feed is a bounded rolling view, not a durable audit trail.

Reuse the pure compositor anywhere

merge_progress_line and render_progress are pure and dependency-free, so you can render progress in a TUI, web UI, or tests without any transport.

---

Related

Streaming

Streaming responses from agents

Streaming Tool Events

Typed tool-call events during streaming

Tool Progress Streaming

Emit mid-tool progress updates

Run Stream Events

Consuming the run event stream