Agent creation UX + syncing

[samanthamsong]

Epic: «Chat & everyday UX feel great» (#839)
Backlog Doc ID: #37 · Priority: P2 · Area: chat & ux

Description
Improve agent creation UX and syncing.

Definition of done
Agent creation is smooth and syncs reliably.

Part of the «Chat & everyday UX feel great» tracking issue (#839).

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 26, 2026, 2:41 PM ET / 18:41 UTC.

Summary
Keep open: current main can list, cache, and display existing agents, but I found no create-agent API/UI or narrower resolved item for the requested creation UX. The related tracking issue is still open and broader than this child work.

Reproducibility: not applicable. this is a backlog UX feature request, not a concrete bug report. No steps, logs, or failing current-main path identify a specific sync failure to reproduce.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Needs maintainer UX/protocol scoping before repair automation because source inspection shows list/files sync support but no create-agent command or UI contract.

Review details

Best possible solution:

Define a narrow agent creation flow and sync contract first, then implement WinUI affordances against supported gateway APIs with regression coverage for agent list refresh and stale/missing agent handling.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a backlog UX feature request, not a concrete bug report. No steps, logs, or failing current-main path identify a specific sync failure to reproduce.

Is this the best way to solve the issue?

Unclear: a maintainable solution needs a defined gateway create/sync contract and WinUI flow before implementation. Adding ad hoc UI around the current list/files-only agent API would not be a complete fix.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The issue has no concrete user flow, reproduction, or acceptance detail beyond smooth/reliable agent creation, so implementation scope could span WinUI, gateway protocol, and upstream agent lifecycle behavior.

Codex review notes: model internal, reasoning high; reviewed against 1c377cb64b65.

Label changes

Label changes:

• add P2: This is a normal-priority UX/product improvement in chat and agent workflows, with no crash, data loss, or urgent regression evidence.
• add impact:session-state: The request concerns agent creation state staying synchronized between gateway data and the Windows UI.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority UX/product improvement in chat and agent workflows, with no crash, data loss, or urgent regression evidence.
• impact:session-state: The request concerns agent creation state staying synchronized between gateway data and the Windows UI.

Evidence reviewed

What I checked:

• Issue scope: The issue body asks to improve agent creation UX and syncing, with a definition of done that agent creation is smooth and syncs reliably; it has no comments or linked implementation PR.
• Current client API only exposes list/file agent operations: The operator gateway facade exposes RequestAgentsListAsync, RequestAgentFilesListAsync, and RequestAgentFileGetAsync, but no create/update/delete agent method. (src/OpenClaw.Shared/IOperatorGatewayClient.cs:102, 1c377cb64b65)
• Current gateway client sends list/file requests, not creation requests: OpenClawGatewayClient has agent methods for agents.list, agents.files.list, and agents.files.get; source search found no agents.create or create-agent implementation. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:964, 1c377cb64b65)
• Existing sync support is list refresh into AppState: GatewayService requests the agents list on connection and stores AgentsList updates in AppState, which supports existing-agent sync but does not implement creation UX. (src/OpenClaw.Tray.WinUI/Services/GatewayService.cs:179, 1c377cb64b65)
• Existing UI displays synced agents in navigation: HubWindow rebuilds agent navigation items from the cached AgentsList JSON, confirming display/sync plumbing for existing agents. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:664, 1c377cb64b65)
• Protocol snapshot documents a limited Windows client subset: The protocol snapshot lists sessions and agents.files request surfaces and notes Windows does not yet implement upstream spawn/subagent orchestration fields, so creation/sync scope likely needs protocol direction. (tests/OpenClaw.Shared.Tests/Protocol/gateway-protocol-snapshot.json:54, 1c377cb64b65)

Likely related people:

• christineyan4: Authored the merged multi-agent chat/nav sync work that requests agent lists on connect, applies cached AgentsList to HubWindow, and caches per-agent workspace files. (role: recent area contributor; confidence: high; commits: de0c3db9dde9, a482ca9e1713; files: src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs, src/OpenClaw.Tray.WinUI/Services/AppState.cs, src/OpenClaw.Tray.WinUI/Services/GatewayService.cs)
• bkudiess: Authored merged hub/sidebar UX work touching dynamic agent icons and navigation behavior, which is adjacent to any agent creation entry point in the hub shell. (role: adjacent UX contributor; confidence: medium; commits: b5d870e66da9; files: src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml, src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs, src/OpenClaw.Tray.WinUI/Assets/SidebarIcons/Agents.svg)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.