Designing Status-Aware Floating Widgets for Long-Running AI Agent Tasks: Key Engineering Decisions

1. The Problem: Long-Running Tasks Don’t Match the Attention Economy

Early code-completion tools followed a simple request-response model, with latency typically in the hundreds of milliseconds to a few seconds. Users naturally stay in place and wait.

Once a coding agent takes over multi-file refactors, dependency upgrades, test fixes, or code review, a single run can last minutes or longer. The run also includes many tool calls along the way: reading files, searching the codebase, running builds, executing tests, and parsing errors.

This creates a structural mismatch: the execution rhythm of the task and the attention rhythm of the user are not in sync. Users cannot keep their eyes fixed on the terminal or editor. They are left with two poor options:

• Repeatedly switch back to the window to check progress, paying a context-rebuild cost with every switch.
• Forget about the task altogether until it has long since failed.

What is really missing is a low-bandwidth, always-present, non-focus-stealing status channel. It does not need to carry much information, but it must meet three conditions:

• Always visible.
• Semantically readable.
• Able to reliably bring attention back when a decision is needed.

A floating status widget on the desktop is essentially the visual shell of this channel, not a toy. Understanding this is the prerequisite for every design decision that follows.

2. A Three-Layer Observability Model: What the Widget Should Show

Pushing raw “what is the agent doing?” data onto the screen does not work. Raw event streams are extremely noisy, and users become more confused after a glance. A more sensible approach is to divide observability into three layers. The widget consumes only the top two.

• L1 — Raw event layer: tool call start and end, file reads and writes, command exit codes, token consumption, and durations. It is the finest-grained layer, which makes it the basis for logging and auditing. It should not be exposed to users directly.
• L2 — Semantic state layer: L1 reduced to a finite set of states, such as running, awaiting input, reviewable, done, failed, and cancelled. This is the only data source for the widget.
• L3 — Human-readable summary layer: a one-line description of current progress, such as “Gathering context by source” or “Build failure located; retrying.”

The key engineering principle is that L2 must be derived from L1, not maintained in parallel. In many implementations, state is hard-coded with if-else branches scattered across the codebase. The result is zombie states, such as a widget that shows “running” while the task has actually died. State should instead be the deterministic result of passing the event stream through a reducer.

type TaskState = "running" | "awaiting_input" | "reviewable" | "done" | "failed" | "cancelled";
interface Event { seq: number; type: string; payload: unknown; at: number; }
// Reducer: a pure function. The same event sequence always yields the same state,
// which makes replay and debugging straightforward.
function reduce(state: TaskState, ev: Event): TaskState {
  switch (ev.type) {
    case "tool.start":     return state === "awaiting_input" ? state : "running";
    case "tool.end":       return state;
    case "input.required": return "awaiting_input";
    case "patch.ready":    return "reviewable";
    case "task.failed":    return "failed";
    case "task.done":      return "done";
    default:               return state;
  }
}

Pure-function reduction brings an additional benefit. After a process restart, replaying the event log restores the correct state, so there is no need to rely on volatile in-memory variables.

3. The State Machine and an Attention-Escalation Strategy

The point of the state machine design is not how many states it has, but which states are worth escalating and interrupting the user for. A practical approach is to grade states by interruption cost:

1. Silent changes (default): progress percentage and the current step update the widget only. No system notifications are sent.
2. Soft prompt: the task enters the reviewable state. The widget plays a subtle animation or changes its badge, but does not pop up a window.
3. Hard interruption: the agent is waiting for user input, needs a permission confirmation, or has hit its retry limit after consecutive failures. Only now should a system-level notification be used, optionally accompanied by a sound.

This grading can be quantified directly as a false-interruption rate: the number of hard notifications triggered per unit of time, divided by the number of completed tasks.

If this value is high, the state machine is mistakenly treating auto-recoverable situations as blocking. The right response is to add auto-handling rules at the L1 event layer, not to let users turn notifications off.

4. Cross-Application Floating Overlays: Implementation Trade-offs

The most valuable capability of a floating widget is staying present across applications. That is also the most easily underestimated technical challenge, spanning three areas: window management, permissions, and power consumption.

Window level and hit area. The widget needs to sit above regular application windows without blocking what the user is currently doing. Common strategies include:

• Use the topmost level.
• Keep a small fixed size.
• Snap to a screen edge by default.

The widget should respond to mouse events only within its own rectangle and keep events outside it click-through. That way it never becomes an “invisible obstacle” that still swallows clicks.

While the widget is being dragged, provide magnetic snapping and position memory inside its snap zone. Positions should be persisted per display.

Permissions and degradation path. Most desktop and mobile platforms require explicit authorization to draw over other applications, and the feature is unavailable without it. A degradation path is therefore required:

• When authorization is not available, fall back to a persistent tray icon or a system activity card.
• Core status information remains reachable, just without the overlay.

Any design in which the overlay is the only entry point is fragile.

Multiple displays and scaling. The widget should be laid out in logical pixels under different scale factors, and its position should be recalculated when it crosses a display boundary. When an app enters exclusive fullscreen (a game or a presentation, for example), the widget should hide itself proactively to avoid getting in the way.

Aggregating multiple tasks. Users often run several sessions in parallel. In this situation, the widget should not open a separate window for each session. Instead, it should aggregate them:

• The main widget displays the session the user is currently focused on.
• A badge shows the number of other active sessions and how many of them are awaiting input or reviewable.
• Clicking the badge expands a list.

Otherwise, the overlay itself becomes a new source of clutter.

Power control. Animations must be throttled. When state has not changed, lower the refresh frequency or stop drawing entirely, and keep animations within a few hundred milliseconds to avoid frequent repaints. A persistent desktop process affects whole-system power draw, and users will notice. This matters more than visual polish.

5. Engine-to-Widget Communication: Process Boundaries and Reliability

The widget is usually a separate process or rendering layer, decoupled from the core engine that executes tasks. Its communication with that engine therefore needs careful design.

• Prefer an in-process event bus: within a single process, use publish/subscribe to decouple components. This has zero serialization overhead.
• Use local channels across processes: a local socket or named pipe carrying length-prefixed binary or JSON frames is enough. There is no need to introduce a heavyweight protocol.
• Use a combined incremental and full-state channel: normally, push only incremental events. When a connection is established or re-established, first request a full state snapshot, then switch to the incremental stream. This avoids a permanently misaligned state caused by, for example, three events lost in the middle.
• Make events idempotent and sequence them: attach a monotonically increasing seq to every event. The consumer discards events whose seq is not contiguous and triggers a resync. This is the most effective defense against zombie states.
• Apply backpressure and coalescing: merge high-frequency events, such as streaming output, into a single summary within a fixed time window before pushing it. This prevents the UI thread from being flooded.

When tasks run server-side for a long time, such as builds on a container platform or scripts on a remote machine, status push can use a message queue for peak shaving and fan-out. A persistent connection can deliver updates in real time, while logs and metrics go into log services and the monitoring and alerting system. On cloud platforms such as Baidu AI Cloud, these capabilities are common building blocks. How they are combined is unrelated to the desktop overlay, which still only consumes L2 state.

6. Persistent Activity vs. Instant Notification: Dividing the Labor

Operating systems actually provide two notification carriers with different semantics. Mixing them leads to a poor result on both sides:

Dimension	Instant notification	Persistent activity card
Lifetime	Short-lived; requires user action or dismisses automatically	Lives as long as the task
Semantics	“You need to make a decision”	“Something is happening”
Quantity control	The fewer, the better	Can stay long-term and grows and shrinks with tasks

The correct division of labor is that progress information goes to the persistent carrier, and decision requests go to instant notifications. Pushing every minute-by-minute progress change as a system notification is the most common failure mode. Users will quickly mute notifications across the board, and as a result they miss even genuinely important blockers.

The system’s focus or Do Not Disturb mode must also be respected. While it is active, non-blocking status updates should only refresh the persistent card, with no sound and no pop-ups.

7. Interaction Design: From Watching to Using

The value of the overlay goes beyond display. Surfacing frequent actions on it can significantly reduce context switches:

• A single click returns to the main window, serving as the shortcut for switching tasks.
• In-place actions on the overlay, such as “Approve changes,” “Stop,” and “Retry,” cover the two most common outcomes: reviewable and failed.
• Hovering expands the most recent L3 summaries into a lightweight timeline.

Accessibility is a part that cannot be skipped. Pure icons and animations do not work well with screen readers, so the overlay needs readable semantic labels, such as “Task A, running, 3 of 7 steps complete.” It must also support the following:

• Full keyboard access.
• A visible focus indicator.
• Adequate color contrast.
• An option to turn animations off.

Animations that flash too frequently should also be avoided.

8. Anthropomorphic Expression: Effective, but Bounded

Giving a status carrier a character persona and several sets of persona lines is a way to reduce cognitive load. It translates “build failed” into “I’m watching the sparks,” so users can tell at a glance that the task is still alive. Multiple personas and line templates can also keep long-term, high-frequency use from becoming visually fatiguing.

Three boundaries must be respected, or the persona will turn from a feature into a burden:

1. It must not override the real state. Persona copy is a decorative layer. The state labels (running, awaiting input, reviewable) must always be present and must never be replaced. Redundant encoding through color and shape is also needed, rather than relying on text alone.
2. It must not add interaction cost. Interactive feedback should be optional and purely visual. “Petting” the character must never interrupt or delay the task action path.
3. It must not weaken information density. Persona copy must not crowd out progress information. At compact sizes, it should automatically degrade to a minimal status indicator.

9. Shipping Checklist

• L2 state is derived from the event stream by a pure-function reducer. It can be replayed and verified, and no second, parallel-maintained copy of state exists.
• Events carry a monotonically increasing sequence number. After a disconnection, the widget supports a “full snapshot plus incremental resume” recovery, and the consumer can detect packet loss and self-heal.
• The overlay has a clear permission degradation path. Without authorization, a usable status entry is still available.
• Multiple tasks are aggregated, and only one overlay instance exists at any given time.
• Interruptions are graded by severity. Hard notifications are used only for genuinely blocking situations and respect the system’s Do Not Disturb mode.
• The overlay supports drag-and-snap, remembers its position per display, and hides automatically in exclusive fullscreen.
• Redrawing and animations stop when there is no state change, and power consumption is measurable.
• Displayed content is redacted. No secrets, full local file paths, or internal host names are shown, only summaries and steps.
• Accessibility labels, keyboard operation, contrast, and an animation toggle are all in place.
• Metrics are observable: average task duration, number of context switches, first-response wait time, false-interruption rate, and zombie-state rate.

10. Conclusion

A floating widget is worth building because it solves a long-overlooked problem: executing a long-running task requires a dedicated status channel that does not steal focus. Its technical depth lies in unglamorous but demanding engineering: state reduction, reliable cross-process synchronization, window layering and permission handling, notification semantics, and accessibility.

Done well, these give users more than a cute icon. They give users back a sense of control over their own task progress, which is the prerequisite for working in parallel.