Status panel
Compose a session queue, pending approvals and questions, and descendant-session navigation
StatusPanel groups queued messages, pending interactions, and descendant sessions above a composer. Categories show counts, expand from a shared capsule surface, and follow content size. It respects reduced motion, keyboard navigation, and hidden-content accessibility.
Supply a session boundary
Pass a required session_key representing the full input owner, plus optional queue, interactions, auto_expand_interactions, sub_sessions, error, and translate. Empty categories disappear. The panel starts collapsed by default. Set auto_expand_interactions to open Interaction once when pending interactions become available, including after asynchronous loading. Manually collapsing the panel or selecting a category cancels any remaining automatic expansion for this instance. After that, arriving items only update counts. If the selected category becomes empty, it collapses.
Changing session_key releases expansion state, form state, and local submission identities, and allows automatic interaction expansion again. Remounting the panel starts the same fresh lifecycle. Include the Agent, Session, and any scope needed to distinguish drafts, group sessions, and archived views. The SDK does not read a store or subscribe to Session data.
Collapsing the panel or changing categories preserves the currently mounted form. Hidden content is inert and excluded from accessibility navigation. Selecting a different interaction unmounts the previous form, releasing its temporary input, including private values. Use globally unique PendingInteractionItem.key values when items come from several Agents or Sessions.
Queue and resources
queue uses MessageQueueProps: ordered queued_messages with message_id, input, and sending; queue_paused; optional editing_message_id; and the callbacks remove_queued_message, send_queued_message, edit_queued_message, set_queue_paused, and pin_queued_message.
The host owns draft storage, dispatch, pause policy, and editing in its composer. Sending entries cannot be edited or moved. Editing locks queue actions. The pin action cannot cross an in-flight entry. Each row shows text plus attachment/reference nodes in document order. Supply render_resources(input) to customize previews, or use QueuedMessageResources with its optional attachment/reference host renderers. Callbacks own queue errors.
Interactions and private input
interactions.items contains shared SessionAgentInteraction snapshots plus optional key, source label, and open_details. respond(input, private_question, item) receives the full selected source so the host can route the response precisely.
AgentInteraction supports approvals, text, password, single-select, and multi-select questions, per-question navigation, optional notes, and canonical read-only results. Pass read_only for message history, answer_placeholder for public text fields, and presentation="inbox" with optional external_heading for a standalone page. Unregistered interaction types show a generic summary.
The host must route a private_question response through its private submission API or IPC. Do not send it through a public response endpoint or persist raw answers in application state. Private answers remain in the mounted form and clear after a submission attempt; failure uses a generic error. The SDK provides presentation and the callback marker, not a secret store or transport.
A rejected callback keeps the interaction available for retry. A successful response is removed immediately and deduplicated while canonical updates arrive. The canonical Session remains the source of final status. Local suppression lasts for the current panel instance; it does not replace backend idempotency.
Descendant sessions
sub_sessions takes ordered items and on_select(address). A row has key, opaque host-owned address, title, depth (direct children use one), and status: idle, working, action_required, failed, or completed. The callback receives the complete address unchanged. Navigation failures appear in the list. The host supplies the descendant tree and handles routing.
Use individual components
The root package also exports StatusPanelHeader, MessageQueue, QueuedMessageResources, PendingInteractionArea, AgentInteraction, ApprovalInteractionCard, QuestionInteractionCard, QuestionField, SubSessionList, SubSessionStatusIcon, and PillSwitcher. Public prop types are exported alongside them. Set a React key for the full owner when mounting individual stateful components. Each text-bearing component accepts translate(key, values?); English is the fallback. StatusPanel passes its translator to internal components.
Styles
In addition to the standard SDK styles, load the status layout once:
@import "@downcity/ui/status-panel.css";Panel controls share a compact visual contract: pause/resume is 24px high with 14px icons; queue row actions are 20px with 12px icons; pagination is 24px with 14px icons. Chat approval and submit buttons use 28px capsules with 11px labels and 14px icons. presentation="inbox" uses 32px actions with 12px labels and 16px icons. Ordinary controls are transparent; confirmation and submit actions use the theme primary color. Controls include hover, open, keyboard-focus, and disabled feedback.
The host provides data, localized text, callbacks, and optional resource renderers. Desktop stores, routing, IPC, and panel management are outside the SDK.