Support structured background tasks with clean REPL rendering and task status

[harvisaiagent-bot]

Summary

The first iteration for issue #147 can improve the current situation by making stdout safer while the prompt is active, but there is still room for a more complete design for background work in the REPL.

Right now, even if prompt rendering is not corrupted, background output still behaves like plain stdout. A more ergonomic long-term approach would be to treat background tasks as first-class REPL entities with structured output and visible task state.

Motivation

When a command starts background work, the UX would ideally be cleaner than simple interleaved stdout. For example, instead of background output appearing in the middle of the interactive flow, Vulcano could manage it explicitly and redraw the prompt in a more intentional way.

There is also a nice opportunity to surface background task information in the UI itself, for example using a bottom toolbar or status area provided by prompt_toolkit.

Current limitation

Using patch_stdout helps prevent prompt corruption, but it does not provide a structured model for:

• tracking active background tasks
• associating output with a specific task/job
• presenting task state in the UI
• deciding how and where background output should be rendered

Proposed direction

Explore a richer background-task model for Vulcano, where the REPL can:

• register background jobs/tasks explicitly
• keep track of currently running jobs
• render task output in a controlled way
• redraw the prompt cleanly without mixing user input and task logs
• optionally expose active tasks in a prompt_toolkit toolbar / status area

Example of desired UX

Instead of this style of output:

🌋 start_background interval=1 ticks=3
Background task started
🌋 hello name=Alice
Hello Alice!
[background] tick 0
[background] tick 1
[background] tick 2
🌋

A more structured experience could look like:

🌋 start_background interval=1 ticks=3
Background task started
[background] tick 0
[background] tick 1
[background] tick 2
🌋 hello name=Alice
Hello Alice!
🌋

And ideally, the prompt could stay responsive while Vulcano still knows how to redraw or queue the task output cleanly.

REPL and CLI parity

Any solution explored here should be evaluated in both execution modes supported by Vulcano:

• interactive REPL mode
• direct CLI/argument mode (executing a command directly without entering the REPL)

Even if the UX details are different in each case, the behavior should be coherent and intentionally designed in both modes. A change should not improve the REPL while leaving direct CLI execution with undefined or inconsistent behavior.

Possible implementation ideas

• a background-task registry in the app
• task-aware output APIs instead of raw print(...)
• output queues managed by the REPL layer
• a prompt_toolkit bottom toolbar with active job/task summaries
• richer Application / layout usage instead of relying only on PromptSession.prompt()

Why this matters

This would make Vulcano more suitable for:

• async workflows
• background polling / streaming commands
• long-running tasks
• interactive tools that need to stay responsive while work continues behind the scenes

Related

• Suggestions #63
• Handle async/background output cleanly while the REPL prompt is active #147

[harvisaiagent-bot]

I picked up issue #150 automatically after the 🚀 reaction.

PLAN

1. Read the issue body and follow-up comments for intent and constraints.
2. Inspect the existing repository code and documentation as the primary implementation context.
3. Identify the smallest repository-aligned change that satisfies the request.
4. Update code, documentation, and tests when they are needed for the change.
5. Open a PR and report it back here.

Detected work type: workflow_docs.

Planned repository changes:

• update README to reflect the current community-driven, AI-assisted workflow
• update AGENTS.md so AI/developer workflow expectations are explicit

[harvisaiagent-bot]

I reviewed the issue, comments, and current repository state, but I still could not derive a reliable repository-aligned implementation from the available context. I am not opening a PR to avoid low-quality changes. If you want, add a bit more concrete expected behavior in the issue/comments and I can try again.