agent-chat-ux-v1-4-0

---
name: agent-chat-ux
version: 1.4.0
author: Charles Sears
description: "Multi-agent UX for OpenClaw Control UI — agent selector, per-agent sessions, session history viewer with search, agent-filtered Sessions tab with friendly names, Create Agent wizard, emoji picker, and backend agent CRUD."
---

# agent-chat-ux

**name:** agent-chat-ux  
**version:** 1.4.0  
**author:** Charles Sears  
**description:** Multi-agent UX for OpenClaw Control UI — agent selector, per-agent sessions, session history viewer with search, agent-filtered Sessions tab with friendly names, Create Agent wizard, emoji picker, and backend agent CRUD.

---

## ⚠️ Security & Transparency Notes

Before applying this skill's patches, be aware of the following:

### Credential Access (`agents.wizard`)

The AI Wizard backend (`agents.wizard` RPC) calls the configured model provider API directly via HTTP. To do this it needs an API key. It resolves credentials in this exact order:

1. **Default config auth** — uses it if the resolved mode is `api-key` (most common)
2. **Auth profile store** — searches for the first `api_key`-type profile matching the provider. Reads only `provider` and `type` fields to find it; does not log or return values.
3. **Environment variable** — `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` as a last resort

> **If you don't want the wizard reading your auth store**, set `ANTHROPIC_API_KEY` in your environment and ensure your default auth profile is already `api-key` mode — step 2 is skipped entirely in that case.

### External API Calls

`agents.wizard` makes a single HTTP POST to:
- `https://api.anthropic.com/v1/messages` (Anthropic models)
- `https://api.openai.com/v1/chat/completions` (OpenAI-compatible models)

No other outbound calls. The call carries your user-supplied description and nothing else from your system.

### Patch Scope

These patches modify **only** agent-related files:

| Patch | File modified | What it changes |
|---|---|---|
| `schema-agents.txt` | `src/gateway/protocol/schema/agents-models-skills.ts` | Adds `emoji` optional param to `AgentsUpdateParamsSchema` |
| `server-agents.txt` | `src/gateway/server-methods/agents.ts` | Adds `agents.wizard` RPC; fixes `agents.update` to write `- Emoji:` (not `- Avatar:`) so emoji edits persist correctly |
| `app-main.txt` | `ui/src/ui/app.ts` | Adds 19 `@state()` fields: 10 for Create Agent/Wizard + 9 for edit agent, delete agent |
| `app-render.txt` | `ui/src/ui/app-render.ts` | Wires create/wizard props + edit agent save handler (sends `emoji` param, not `avatar`; evicts identity cache after save) |
| `app-render-helpers.txt` | `ui/src/ui/app-render.helpers.ts` | Agent selector dropdown in chat header (uses `resolveAgentEmoji()` for correct emoji), per-agent session filter, `+` New Session button |
| `agents-view.txt` | `ui/src/ui/views/agents.ts` | Create Agent panel (manual + wizard modes, 103-emoji picker); Edit agent inline form (name/emoji/workspace); Delete agent with confirmation; always-editable Overview |
| `agents-utils.txt` | `ui/src/ui/views/agents-utils.ts` | `buildModelOptionsMulti()` for multi-select fallback dropdown |
| `agents-panels-cron.txt` | `ui/src/ui/views/agents-panels-status-files.ts` | Cron Jobs tab Scheduler card now shows agent-specific job count and next-wake (not global gateway stats) |

Each patch is scoped to a single concern. If any patch file modifies more than the files listed above, stop — you have an outdated copy.

### LLM Output Validation

Wizard model output is parsed as JSON and validated before use:
- Must be a JSON object with `name` (string), `emoji` (string), `soul` (string)
- `name` is capped at 100 characters, `emoji` at 10
- `soul` must be ≥ 20 characters
- Empty or non-JSON responses are rejected with a user-visible error — nothing is auto-created

### Source Code Modification

This skill applies `git apply` patches against `~/openclaw` and requires a UI + gateway rebuild. Changes are persistent. **Always backup before patching:**

```bash
cd ~/openclaw && git stash  # or git branch backup/pre-agent-ux
```

---

## What This Skill Adds

### 1. Agent Selector Dropdown in Chat Header
When multiple agents are configured, a dropdown appears **left of the session dropdown** in the chat header. Selecting an agent switches to that agent's most recent session (or falls back to a fresh webchat key for that agent). The session dropdown automatically filters to show **only sessions belonging to the selected agent**.

### 2. Per-Agent Session Filtering (Sorted Newest First)
Sessions are now scoped to the active agent and sorted newest-first. No more mixing other agents' cron jobs and subagent sessions into the current chat's session picker.

### 3. + New Session Button in Chat Header
A `+` icon button sits right of the session dropdown, allowing new sessions to be started without typing `/new`.

### 4. Create Agent Panel (Manual + AI Wizard)
The Agents tab gains a **+ Create Agent** button that expands a panel with two modes:

**Manual mode:**
- Agent name
- Workspace path (auto-generated from name if left blank)
- Emoji picker (see below)

**AI Wizard mode:**
- Describe the agent in plain English
- Click "Generate Agent" — AI generates name, emoji, and full SOUL.md
- Review the preview, then click "✅ Create This Agent"

After creation, the agents list **and** config form are both refreshed automatically — no "not found in config" error, no manual reload needed.

### 5. Emoji Picker Dropdown
The emoji field in Create Agent and Edit Agent forms is a **dropdown with 103 curated emojis** grouped into 5 categories (Tech & AI, People & Roles, Animals, Nature & Elements, Objects & Symbols), each showing the emoji and its name. A large live preview shows the selected emoji next to the dropdown.

### 6. Edit Agent Inline (Agents Overview)
The Agents Overview card now shows editable inputs directly — no toggle needed:
- **Name**, **Emoji** (dropdown, 103 emojis), **Workspace** are always editable
- Changes activate the bottom **Save** button — no separate inline Save/Cancel
- Emoji is saved as `- Emoji:` in IDENTITY.md (last-wins override of creation value); identity cache is evicted after save so changes appear immediately
- Edit uses the `emoji` param of `agents.update` (not `avatar`) so the correct IDENTITY.md key is written

### 7. Delete Agent
- 🗑️ **Delete** button appears in the Overview header for non-default agents
- Inline confirmation dialog before deletion; hidden for the main/default agent

### 8. Agent-Specific Cron Stats
The **Scheduler** card on the Cron Jobs tab previously showed global gateway stats (total job count, global next wake). Now:
- **Jobs** → count of cron jobs targeting *this agent only*
- **Next wake** → earliest `nextRunAtMs` across this agent's jobs (`n/a` if no jobs)
- **Subtitle** → "Agent cron scheduling status." (was "Gateway cron status.")
This means agents with no crons correctly show `Jobs: 0` / `Next wake: n/a`.

### 9. Agents Tab — Model Selector Cleanup
- Removed the redundant read-only "Primary Model" row from the Overview grid (it's already editable in the Model Selection section below)
- **Fallback models** converted from a free-text comma-separated input to a proper **`<select multiple>`** using the same full model catalog as the primary selector
- Added spacing and clear labels between primary and fallback fields
- Small hint "(hold Ctrl/⌘ to select multiple)" on the fallback selector

### 10. Backend — `agents.create` / `agents.update` / `agents.delete` / `agents.wizard`
New RPC handlers wired into the gateway:

| Method | Description |
|--------|-------------|
| `agents.create` | Provisions a new agent entry in config + scaffolds workspace (SOUL.md, AGENTS.md, USER.md) |
| `agents.update` | Patches agent config (name, workspace, model, identity, etc.) |
| `agents.delete` | Removes agent from config |
| `agents.wizard` | Calls the configured LLM to generate name, emoji, and SOUL.md from a plain-text description |

**Auth fix in `agents.wizard`:** Raw HTTP calls to the model API require an `api_key` token, not an OAuth/bearer token. The wizard now falls back to an explicit `api_key` profile (or `ANTHROPIC_API_KEY` env var) when the default resolved auth mode is `oauth` or `token`.

### 11. Session History Viewer (v1.4.0)
A modal overlay accessible from the **Sessions tab** that displays full conversation history for any session:
- **Agent dropdown filter** — scope sessions by agent
- **Session dropdown** — pick a session to view (filtered by agent)
- **Search bar** — debounced full-text search across message content (case-insensitive)
- **Role filter chips** — All / User / Assistant / System / Tool
- **Message timeline** — role icons (👤/🤖/⚙️/🔧), timestamps, and message text
- **Pagination** — "Load More" with count display (100 messages per page)
- Click "History" button on any row in the Sessions tab to open

### 12. Sessions Tab Overhaul (v1.4.0)
The Sessions tab now provides a unified multi-agent experience:
- **Agent filter dropdown** — filter sessions by agent (populated from `agents.list`)
- **Friendly session names** — "Main Session", "Cron: pipedream-token-refresh", "discord:#bot-chat" instead of raw keys like `agent:main:cron:cc63fdb3-...`
- **Agent identity column** — shows agent emoji + identity name (e.g. "🤖 Assistant") using `identity.name` → `name` → `id` fallback chain
- **Raw key shown as subtitle** — full technical key displayed in smaller muted monospace text below the friendly name
- **Label column removed** — redundant since the friendly name already incorporates label/displayName
- **CSS grid layout** — proper column alignment using `grid-template-columns` with proportional widths; headers align precisely with data
- **Empty state** — clear message when an agent has no sessions
- **Session count** — total/filtered count shown in the store info line
- **History button pre-selects** — clicking History on a row opens the modal with agent and session already se

... (truncated)