Agent progress trace

Problem Context

• The product starts an AI agent, workflow, tool sequence, background automation, code task, research task, content operation, support action, deployment, or customer-facing side effect.
• The run can include generated text, tool calls, data retrieval, approval gates, retries, skipped steps, blocked permissions, failures, cancellations, and final artifacts.
• Users need to know whether the agent is still working, waiting, blocked, retrying, safe to leave, safe to cancel, or finished.
• Some details may be sensitive or too verbose for the trace and should move to tool-use visibility, logs, or audit history instead of overwhelming the progress view.
• The trace may start from a reviewed agent plan preview and later produce durable audit records after completion.

Selection Rules

• Choose agent progress trace when an agent or automation run has started and users need live status across multiple steps or tools.
• Use agent plan preview before execution starts; use agent progress trace after Run begins.
• Use streaming response when the primary observable work is generated output arriving in chunks, not a multi-step run lifecycle.
• Use activity log when users need retained investigative records after the run, not live execution monitoring.
• Use progress bar when one bounded system operation has measurable percent, byte, row, or item progress.
• Use human approval gate when the run is paused at one authorization checkpoint; keep the trace responsible for showing where that gate sits in the larger run.
• Use tool-use visibility when users must inspect exact tool names, inputs, outputs, permissions, or payloads; keep the progress trace as the run-level timeline.
• Show current step, last completed step, queued next step, blocked step, retry, skip, cancel, and final outcome states before adding decorative motion.
• Preserve trace identity across refresh, route change, mobile handoff, retry, cancellation, and final result.
• Do not title raw logs, hidden tool events, or post-hoc audit rows as a progress trace unless they support live run monitoring.

Required States

• Run started state tied to run ID, plan version, objective, and user who started the run.
• Queued, active, completed, skipped, waiting, blocked, retrying, failed, cancelled, and completed run states.
• Current step state with label, purpose, owner, elapsed time, and last event time.
• Tool call pending, tool call running, tool call succeeded, tool call failed, and tool detail available states.
• Human approval gate waiting state linked to the canonical gate.
• Permission blocked, missing input, rate limited, offline, timeout, stale plan, and fallback route states.
• Partial result and generated output available states without confusing output streaming with step progress.
• Run resumed, retried, cancelled, rolled back, and final handoff to result or audit states.
• Mobile compact trace state with current, previous, next, blocked, and final outcome visibility.

Interaction Contract

• The trace belongs to one run ID, reviewed plan version, objective, actor, start time, current state, and final state.
• Each trace item identifies a step or event, its status, time, owner, and whether details are available, hidden, redacted, blocked, or unsafe to expose.
• The trace differentiates queued, active, completed, failed, skipped, blocked, waiting, cancelled, and final states in text, not color alone.
• Opening step details reveals scoped information for that step and does not replace the trace with an unfiltered raw log.
• Cancel, stop, retry, resume, grant permission, open gate, view details, and view audit actions only appear when the run state supports them.
• Retries append or mark retry attempts without making completed earlier steps look newly completed unless they actually reran.
• If the run diverges from the reviewed plan, the trace shows the divergence, reason, and whether user review or approval is required.
• When the run completes, fails, or is cancelled, the trace remains available long enough to inspect outcome and links to durable audit or activity history.

Implementation Checklist

• Model run ID, plan version, objective, started by, start time, step IDs, event IDs, statuses, timestamps, active tool, queued work, blockers, retry attempts, cancellation state, final outcome, and audit link as structured data.
• Separate trace events from plan-preview records, streamed response chunks, raw tool payloads, human approval gate decisions, activity-log records, and telemetry events.
• Render a stable ordered list or timeline with active item, completed items, queued items, gates, blockers, retry attempts, final state, and details disclosure.
• Add actions for stop, cancel, retry failed step, resume, grant permission, open approval gate, view tool details, copy run ID, view result, and open audit according to state.
• Throttle live updates and assistive announcements to meaningful milestones rather than every low-level event.
• Redact or summarize sensitive tool inputs, private data, secrets, and payloads while linking to permissioned detail surfaces where appropriate.
• Persist the trace through refresh and background execution, and reconcile client state with canonical server run state.
• Test slow steps, duplicate events, out-of-order events, retry after failure, blocked permission, missing input, approval gate wait, cancelled run, stale plan divergence, final audit handoff, mobile wrapping, keyboard details, and screen-reader updates.

Common Generated-UI Mistakes

• Using one spinner or vague Thinking label for a multi-step agent run.
• Showing a progress bar percentage when the run has no honest measurable total.
• Dumping raw tool logs instead of a user-readable run trace.
• Calling a pre-run plan preview a progress trace before any work has started.
• Calling a post-run activity log a progress trace when users cannot monitor or intervene.
• Hiding approval gates, permission blockers, retries, skipped steps, and partial failures.
• Letting duplicate or out-of-order events make steps appear to run twice.
• Removing the trace immediately after failure, cancellation, or completion.

Critique Questions

• What run ID, plan version, and objective does this trace represent?
• Can users tell what is queued, active, completed, blocked, failed, skipped, cancelled, and final?
• Which tool details are safe to show inline, and which belong in tool-use visibility or audit history?
• What actions are available when the run stalls, waits for approval, needs permission, fails, or diverges from the reviewed plan?
• How does the trace handle duplicate, delayed, out-of-order, redacted, or retried events?
• Would agent plan preview, streaming response, progress bar, human approval gate, activity log, or tool-use visibility better fit the actual need?