Notification / Inbox
Handle questions and approvals across Sessions and read work updates
Notification is Desktop's built-in City-level notification source, with one instance per City. Inbox appears at the top of Desktop's left navigation rail with an inbox icon. Open it with ⌘/Ctrl + 1; other number shortcuts follow the visible navigation order.
The Sidebar lists all Inbox items in two groups: Needs attention contains interaction requests and unread failures; Notifications contains other ordinary notifications and read history. Each item appears once. Reading a failure moves it to Notifications, while interrupted requests remain available for inspection. Mainview shows only the selected item's details or response form. Entering Inbox does not automatically select an item; a short prompt appears until selection. Closing details or clearing the selected update never opens or reads the next item. Narrow windows use Desktop's shared sidebar controls. Agent names come from the current directory; an unavailable Agent gets an explanatory label instead of an internal ID. Internal Session identifiers stay inside expandable source details.
Inbox uses Downcity's borderless layout. The Sidebar's standard header contains a single more menu for organizing notifications above an independently scrolling list. When there are no items, the sidebar centers an outlined inbox icon and “暂无通知” horizontally and vertically. Only nonempty groups appear when items exist. Loading and read failures have separate centered states, so a failure never appears as an empty inbox. The header menu always shows an ellipsis. Source availability explanations appear in the corresponding item details. Clicking the Inbox Rail entry automatically rereads content and checks source state, including when Inbox is already open. Repeated clicks during a refresh share the ongoing request, retaining the current selection and unsent input. Existing items remain available. Only a complete loading failure shows an error in the list area, with a prompt to click Inbox again to retry. Needs attention and Notifications use clear supporting headings with medium weight, smaller counts, and a left edge aligned with the list. Items use shared two-line sidebar rows with comfortable spacing: the title comes first and uses medium weight when attention is needed. Source and relative time sit closely together on the same baseline, separated by whitespace. Long source names truncate and reveal their full name on hover. Rows use a 32px avatar or business icon on the left, vertically centered with both text lines and a single menu button on the right. Each notification and pending request displays its attention indicator inside its own menu button, replacing the ellipsis. Buttons with an indicator stay visible; read items and items needing no attention show an ellipsis on hover, keyboard focus, or touch. Every item menu offers View details, while ordinary notifications also offer Mark as read and Clear. Opening the menu does not select or mark the item as read. Mainview uses the shared page spacing and scroll layout with a maximum reading width of 48rem. The title, source, full timestamp, and secondary source action lead directly into the body or form. Long code and Markdown stay within the available width; missing body content is omitted. Ordinary notifications omit redundant status labels; requests and failures retain relevant state. Item states share the Rail's attention colors: amber for requests needing a response, red for failures, and blue for success and informational notifications. Reading removes the dot while retaining the business outcome; a read failure still indicates failure. Requests that cannot receive a response use a neutral interrupted state. Agent items lead with an avatar, repeated beside the source name in details. Missing avatars or an unavailable directory use the default Agent icon; Power updates without an Agent use a business icon. Session and group notifications, including request headings, use the real source session title. Results and errors remain in the body, while original question and approval prompts are preserved. Renaming a source refreshes notification titles without changing read state. Blank titles display “未命名会话”; unavailable sources retain saved titles. Task notifications keep task titles. Matching question or approval titles appear once in details, while multiple questions retain individual prompts and navigation.
Answer questions or approve operations in the selected detail. Responses go directly to the original Session. Background refresh preserves selection and input. Switching away from an edited form asks before clearing it. Successful submission shows an inline confirmation with a Handle next action instead of immediately replacing the form.
Use View original session or View result in the detail to open its source. Navigation uses the Session's current workspace information. Deleted or archived sources produce a clear message rather than creating a replacement Session. Displaying a specific update detail in a focused, visible window marks that item as read without marking the entire collection.
Inbox, conversation indicators, navigation dots, and the Desktop application badge consume the same Notification Power snapshot. The badge and Inbox navigation number count respondable pending requests plus unread failure matters with scope=inbox. Ordinary replies only create conversation unread indicators and are excluded from this count. Existing Power data change events trigger coalesced refreshes.
Viewing the original conversation in a focused, visible window marks that target's ordinary updates as read. Inbox offers Mark as read in each notification row's menu as well as detail reading. The sidebar header's organization menu action Mark all notifications as read acknowledges only ordinary Inbox updates in the snapshot at the time of the click, across both groups, keeping the records. New matters and newer versions remain unread. The Clear this notification row menu action and Clear read notifications in the header menu remove only ordinary Inbox notifications, leaving conversation, Task, and Group history intact. Later events for the same matter can notify again. Every action checks the ID and created_at; clearing read updates uses the ordinary Inbox update snapshot at the time of the click, across both groups, and also requires the stored version to remain read. These actions never finish questions, approvals, or private input Interactions. Actions disable repeat submission while running and retain content with an error if they fail. Reading and opening sources leave pending requests intact. Session identity is independent of its Workspace binding. Archived or deleted sources and removed Agents or Groups retain their notification summaries and read state. Details explicitly show archived, removed, or unknown sources, and cannot create replacement sources. Recreating a fixed conversation after archiving does not redirect old notifications to the new record. When the original record identity is unavailable, the summary remains visible with an unknown source. Notification startup does not read conversation history. Source changes refresh the view; reads and explicit refreshes check only referenced sources, and snapshot reads never write or delete notifications. Unreachable directories or interaction sources remain unknown. System integration uses application icon badges, subject to platform support.
The original Session owns each request's state. Marking an update as read never answers a question or approves an operation. Refresh or inspect the original conversation when a request has been cancelled or its execution can no longer receive a response.
Notifications retains read history and shows background Work Main results and failures, Agent conversation failures, and notifications published at business Power delivery boundaries. Ordinary Agent replies remain conversation unread indicators and do not enter Notifications. Ordinary Work does not require an additional review step. Read the result and use the original conversation for follow-up requests. A Main collects its Children's results; Task, Memory, and Messenger internal steps do not publish separate ordinary completion updates. Group failures publish updates; successful group completion does not. Pending group requests reference members' original Interactions.
Each Agent conversation or group conversation updates one matter; successive runs of the same Task update one task matter. Execution history stays at its source. Repeating the original event preserves read state; a new result or changed summary becomes unread. Source kind, navigation target, display scope, and success/failure outcome are explicit fields. The UI never infers failure from titles. Withdrawal removes only the notification, without completing tasks, accepting results, approving operations, or changing execution state.
Private questions use the original Session's dedicated submission endpoint. Answers are never stored in notification records. The original Session always owns questions, approvals, and execution state.
Needs attention shows the combined count of respondable requests and unread failures; Notifications shows the remaining unread notification count. The navigation tooltip explains the pending request and unread failure totals. Success and informational updates keep their unread dots without increasing the application number. Power supplies pending_request_count, unread_update_count, unread_failure_count, and the final badge_count in the same snapshot, where badge_count = pending_request_count + unread_failure_count. Desktop consumes these values directly.
Host actions include notification.read({ notification_id, created_at }) for one version, notification.read_updates({ updates }) for a snapshot, notification.clear_update({ notification_id, created_at }) for one update, and notification.clear_read_updates({ updates }) for read snapshot updates. updates is an array of { notification_id, created_at } references. Each action returns its status and the complete Power snapshot; Renderers reject delayed snapshots by revision.
Trusted hosts supply existing Agent avatars through NotificationRendererOptions.render_agent_avatar(agent_id, size), where size is list (32px sidebar avatar) or detail (18px source row); the public Renderer does not resolve local avatar paths. render_interaction(item, respond, display) receives the detail's display.title and display.title_id, allowing hosts to reuse their interaction component, omit matching titles, and preserve accessible names. Desktop uses the form's presentation="inbox" layout. render_attention({ kind, outcome, presentation, label }) supplies the host's shared status mapping and colors; presentation is dot or status. Desktop reuses the Rail's attention_from_notification and attention_visual. Without this port, the public Renderer uses a neutral presentation.
SDK
Trusted user clients can use the Agent's interaction collection:
const pending = await agent.interactions.list();
const unsubscribe = agent.interactions.subscribe(handle_interaction_change);
await agent.interactions.respond({ reference, response });Each item's origin comes from the original Session and accurately identifies its role. Missing origins remain visible as unknown instead of being guessed from chat/work categories. Reading the collection does not start a model. Responses must match the original Session, Turn, and Interaction. Use the dedicated submit_private endpoint for private input instead of ordinary responses.