Skip to content

BuilderIO/agent-native / packages/core/src/templates/default/.agents/skills/progress

progress

Unverified

Report live progress from long-running agent tasks. Use when a task takes more than a few seconds, so the user can watch status in the runs tray instead of staring at a spinner.

Progress

Overview

progress_runs is the framework's "what is the agent doing right now" primitive. The agent starts a run at the top of a long task, updates it as work proceeds, and completes it with a terminal status. The UI renders active runs in a header-bar widget with a percent bar, current step, and spinner/check/X — live visibility into work that would otherwise be opaque.

Separate concern from notifications:

NotificationsProgress
ShapeOne-shot event — "X happened"Continuous state — "X is 45% done"
UI surfaceBell + toastRuns tray with percent bar
LifecycleDismissable (read/unread)Running → terminal (succeeded/failed/cancelled)

Common pattern: on completion, emit a notify() so the user sees the outcome when they're not actively watching the tray.

Tool

All progress operations go through a single manage-progress tool with an action parameter:

ActionPurpose
startMark the start of a long task. Returns a runId.
updateUpdate percent and/or current step. Call frequently.
completeMark terminal status: succeeded, failed, cancelled.
listList recent runs (all or --active=true).

Canonical Flow

manage-progress --action=start --title "Triage 128 unread emails" --step "Fetching inbox"
  → runId=abc

manage-progress --action=update --runId=abc --percent=25 --step="Classifying 32/128"
manage-progress --action=update --runId=abc --percent=75 --step="Drafting replies 97/128"

manage-progress --action=complete --runId=abc --status=succeeded
notify --severity=info --title="Triage done" --body="12 archived, 6 drafts ready to review"

Best Practices

  • Start a run for anything > ~5 seconds. Users want feedback; a spinner with no context feels frozen.
  • Update at natural checkpoints, not every iteration. Every 5–10% is enough for most UIs.
  • Always call manage-progress --action=complete at the end — including the error path. An orphaned running row is worse than no row.
  • Pair with notify on completion. The tray tells users what's running; notifications tell them what finished.
  • Use metadataJson on manage-progress --action=start to pass a link back to the produced artifact (thread id, document path), so the UI can deep-link from the runs tray.

Runs API

Mounted at /_agent-native/runs/* by core-routes-plugin. Read-only over HTTP — writes flow through the agent tools:

MethodRoute
GET/_agent-native/runs?active=true&limit=50
GET/_agent-native/runs/:id
DELETE/_agent-native/runs/:id

UI Surface

Ships as <RunsTray /> at @agent-native/core/client/progress:

import { RunsTray } from "@agent-native/core/client/progress";

export function HeaderBar() {
  return (
    <header className="flex items-center gap-2">
      {/* … */}
      <RunsTray />
    </header>
  );
}

Inline header widget — mount next to the notifications bell. Shows a spinner icon + count badge when runs are active; click opens a dropdown with a live percent bar per run. Hides the trigger entirely when no active runs. Polls active=true every pollMs (default 3s).

Event Bus Integration

Two events emit on the bus so automations can react:

  • run.progress.started — { runId, title, step? }
  • run.progress.updated — { runId, percent, step, status }

Example automation: "when a run takes longer than 5 minutes, notify me."

Related Skills

  • notifications — fire one when a run finishes so the user sees the outcome.
  • automations — subscribe to run.progress.updated to build watchdogs on slow runs.
  • delegate-to-agent — if you're delegating a long task, start a run on the delegator side so the caller has visibility.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall