Peter Steinberger
7170a6231a
* feat(agents): unify agent status into a durable progress_card
Replace the write-only update_plan to-do tool and the fragmented plan
rendering with one durable status artifact per session: progress_card
({plan?, markdown?}, replace-on-write, 8 KiB markdown / 50-step caps).
Cards persist in a lazy-additive session_progress_cards table in the
per-agent DB (no schema-version bump), broadcast progressCard.changed,
and render from the store with exactly one live placement per view
(session rail when visible, else the composer-adjacent bar); transcripts
collapse to one-line receipts, and the sidebar hovercard shows other
sessions' cards inline (markdown + <progress>, DOMPurify allowlist, no
iframes). The three stream-derived plan renderers and their dedup
heuristics are deleted.
Codex runs disable the native plan tool per thread
(tools.update_plan.enabled=false) and receive progress_card via the
dynamic-tool bridge; compaction restore now reinjects the card (steps +
bounded markdown). Card writes still emit the legacy plan stream event so
native apps and channels keep working until their per-platform
migrations. Policy names map update_plan -> progress_card; the shipped
tools.updatePlan=false kill switch is honored.
Net -277 production LOC; -480 test LOC.
* test(agents): regenerate Codex prompt snapshots for update_plan thread-config disable
* chore(protocol): allowlist progressCard.changed for native apps pending card migration
* fix(ci): repair progress card integration checks
* fix(codex): canonicalize native progress cards
* test(gateway): reconcile progress card method order
* test(codex): stabilize native approval fixture
3.5 KiB
summary, title, sidebarTitle, read_when
| summary | title | sidebarTitle | read_when | ||
|---|---|---|---|---|---|
| Maintain one durable plan and status card for a session | Progress card | Progress card |
|
progress_card is the single agent status tool for a session. It stores an ordered step plan, a compact Markdown note, or both. Each call replaces the whole card, so the latest write is the source of truth for someone following the work without reading the transcript.
The card is durable session state. A reconnect or page reload reads the latest card from the Gateway instead of reconstructing it from tool events or transcript history. The transcript keeps only a short update receipt, not another full copy of the card.
Update a card
Both input fields are optional:
plan: up to 50 ordered steps. Each step has non-emptysteptext and astatusofpending,in_progress, orcompleted. At most one step may bein_progress.markdown: a compact narrative about what happened, what is blocked, or what comes next. Use it when a glanceable note says more than the step list; do not repeat the plan in Markdown.
For example:
{
"plan": [
{ "step": "Inspect the failing route", "status": "completed" },
{ "step": "Repair the session owner", "status": "in_progress" },
{ "step": "Run focused verification", "status": "pending" }
],
"markdown": "The failure is isolated to session ownership. No blocker."
}
Every call is a replacement, not a patch. Omitting markdown removes the previous note; omitting plan removes the previous checklist.
The tool returns a short receipt such as Progress card updated (rev 4, 1/3 done) or Progress card updated (rev 4) when there is no plan. Its structured result contains the revision and either completed/total step counts or null when no plan is present. OpenClaw also emits plan events for native apps and channel renderers during their migration, but the durable card remains the authoritative state.
Format the note
Markdown accepts ordinary formatting, small tables, links, and optional progress bars:
Tests are running.
<progress value="3" max="7"></progress>
| check | state |
| ---------- | ------- |
| unit tests | passed |
| live flow | running |
The Control UI renders progress elements with value and max attributes. Other raw HTML is stripped by the Markdown sanitizer.
Limits
- Markdown: at most 8,192 UTF-8 bytes.
- Plan: at most 50 steps.
- Step text: non-empty and at most 512 UTF-8 bytes per step.
- Active work: at most one
in_progressstep.
The Gateway removes invisible Unicode and bidirectional control characters from Markdown and step text before storing the card.
Clear a card
Call progress_card with both parts absent or empty to remove the current card:
{}
An empty plan plus empty or whitespace-only Markdown also clears it. A successful clear returns Progress card cleared.
Where the card appears
The current chat shows exactly one live card:
- When the session rail is visible, the card appears in the rail.
- At narrow widths where the rail is hidden, the card appears in the collapsible surface beside the composer.
The two placements are mutually exclusive. Other sessions can show their latest card in the sidebar hovercard. All placements read the same Gateway-backed state and refresh after progressCard.changed notifications.