clawport-ui 0.4.0 → 0.4.2

package/app/api/chat/[id]/route.ts

@@ -129,10 +129,16 @@ export async function POST(
         Connection: 'keep-alive',
       },
     })
-  } catch (err) {
+  } catch (err: unknown) {
     console.error('Chat API error:', err)
+
+    let userMessage = 'Chat failed. Make sure OpenClaw gateway is running.'
+    if (err instanceof Error && 'status' in err && (err as { status: number }).status === 405) {
+      userMessage = 'Gateway returned 405. Enable the HTTP endpoint: set gateway.http.endpoints.chatCompletions.enabled = true in ~/.openclaw/openclaw.json, then restart the gateway.'
+    }
+
     return new Response(
-      JSON.stringify({ error: 'Chat failed. Make sure OpenClaw gateway is running.' }),
+      JSON.stringify({ error: userMessage }),
       { status: 500, headers: { 'Content-Type': 'application/json' } }
     )
   }

package/lib/agents-registry.ts

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync, readdirSync } from 'fs'
-import { join } from 'path'
+import { join, basename } from 'path'
 import bundledRegistry from '@/lib/agents.json'
 import type { Agent } from '@/lib/types'
 
@@ -13,13 +13,60 @@ const DISCOVER_COLORS = [
   '#06b6d4', '#ec4899', '#84cc16', '#8b5cf6', '#ef4444',
 ]
 
+// ---------------------------------------------------------------------------
+// Heading / identity extraction helpers (exported for testing)
+// ---------------------------------------------------------------------------
+
 /**
- * Extract a display name from SOUL.md content.
- * Returns the text of the first `# Heading` line, or null.
+ * Parse a SOUL.md heading into a clean agent name and optional title.
+ *
+ * Handles all observed heading formats:
+ *   "# SOUL.md — VERA"                 → name "VERA"
+ *   "# SOUL.md — KAZE, Flight Research Agent" → name "KAZE", title "Flight Research Agent"
+ *   "# ECHO — Community Voice Monitor" → name "ECHO", title "Community Voice Monitor"
+ *   "# SOUL.md - Who You Are"          → name null (not a useful agent name)
+ *   "# QUILL — Herald's Content Writer" → name "QUILL", title "Herald's Content Writer"
  */
-function extractNameFromSoul(content: string): string | null {
+export function parseSoulHeading(content: string): { name: string | null; title: string | null } {
   const match = content.match(/^#\s+(.+)/m)
-  return match ? match[1].trim() : null
+  if (!match) return { name: null, title: null }
+
+  let heading = match[1].trim()
+
+  // Strip "SOUL.md — ", "SOUL.md - ", "SOUL.md:" prefixes
+  heading = heading.replace(/^SOUL\.md\s*[—–\-:]\s*/i, '')
+
+  // If the heading is generic (e.g. "Who You Are"), it's not a useful agent name
+  if (/^who\s+you\s+are/i.test(heading)) return { name: null, title: null }
+
+  // Split on em-dash / en-dash to separate name from description
+  const dashParts = heading.split(/\s*[—–]\s*/)
+  const nameAndMaybeTitle = dashParts[0].trim()
+  const descAfterDash = dashParts.length > 1 ? dashParts.slice(1).join(' — ').trim() : null
+
+  // The name might contain a comma: "LUMEN, SEO Team Director"
+  const commaParts = nameAndMaybeTitle.split(/,\s*/)
+  const name = commaParts[0].trim() || null
+  const titleFromComma = commaParts.length > 1 ? commaParts.slice(1).join(', ').trim() : null
+
+  const title = titleFromComma || descAfterDash || null
+  return { name, title }
+}
+
+/**
+ * Parse an IDENTITY.md file for agent name and emoji.
+ *
+ * Expected format (generated by OpenClaw bootstrap):
+ *   - **Name:** Jarvis
+ *   - **Emoji:** 🤖
+ */
+export function parseIdentity(content: string): { name: string | null; emoji: string | null } {
+  const nameMatch = content.match(/\*\*Name:\*\*\s*(.+)/i)
+  const emojiMatch = content.match(/\*\*Emoji:\*\*\s*(\S+)/i)
+  return {
+    name: nameMatch ? nameMatch[1].trim() : null,
+    emoji: emojiMatch ? emojiMatch[1].trim() : null,
+  }
 }
 
 /**
@@ -32,93 +79,215 @@ function slugToName(slug: string): string {
     .join(' ')
 }
 
+/**
+ * Read a file and return its content, or null on any error.
+ */
+function safeRead(filePath: string): string | null {
+  try {
+    if (!existsSync(filePath)) return null
+    return readFileSync(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Scan a directory for sub-agent .md files (e.g. sub-agents/QUILL.md, members/WRITER.md).
+ * Returns an array of { fileName, content } for each .md file found.
+ */
+function scanSubAgentDir(dirPath: string): { fileName: string; content: string }[] {
+  if (!existsSync(dirPath)) return []
+  try {
+    return readdirSync(dirPath)
+      .filter(f => f.endsWith('.md'))
+      .map(f => {
+        const content = safeRead(join(dirPath, f))
+        return content ? { fileName: f, content } : null
+      })
+      .filter((x): x is { fileName: string; content: string } => x !== null)
+  } catch {
+    return []
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-discovery
+// ---------------------------------------------------------------------------
+
 /**
  * Auto-discover agents from $WORKSPACE_PATH.
  *
- * Scans the workspace for a root SOUL.md and agent subdirectories
- * under agents/. Each subdirectory with a SOUL.md becomes an agent.
+ * Scans the workspace for:
+ *   - IDENTITY.md at root (for root agent name/emoji)
+ *   - SOUL.md at root (root orchestrator)
+ *   - agents/<dir>/SOUL.md (top-level agents)
+ *   - agents/<dir>/sub-agents/*.md (nested sub-agents)
+ *   - agents/<dir>/members/*.md (team member agents)
+ *
  * Returns null if nothing can be discovered.
  */
 function discoverAgents(workspacePath: string): AgentEntry[] | null {
   const agentsDir = join(workspacePath, 'agents')
   const rootSoulPath = join(workspacePath, 'SOUL.md')
+  const identityPath = join(workspacePath, 'IDENTITY.md')
   const hasRoot = existsSync(rootSoulPath)
 
-  // Scan agents/ directory for subdirectories with SOUL.md
-  let agentDirs: string[] = []
+  // Scan agents/ directory for all subdirectories (even without SOUL.md, may have sub-agents)
+  let allAgentDirs: string[] = []
   if (existsSync(agentsDir)) {
     try {
       const entries = readdirSync(agentsDir, { withFileTypes: true })
-      agentDirs = entries
-        .filter(e => e.isDirectory() && existsSync(join(agentsDir, e.name, 'SOUL.md')))
-        .map(e => e.name)
-    } catch {
-      // Can't read directory
-    }
+      allAgentDirs = entries.filter(e => e.isDirectory()).map(e => e.name)
+    } catch {}
   }
 
-  // Need at least a root or one agent to return a discovered registry
-  if (!hasRoot && agentDirs.length === 0) return null
+  // Need at least a root or agent directories to discover
+  if (!hasRoot && allAgentDirs.length === 0) return null
 
   const discovered: AgentEntry[] = []
+  let colorIndex = 0
 
-  // Build root agent from workspace SOUL.md
+  // --- Root agent ---
   let rootId = 'main'
   let rootName = 'Main'
+  let rootEmoji = '\u{1F916}'
+
   if (hasRoot) {
-    try {
-      const content = readFileSync(rootSoulPath, 'utf-8')
-      const extracted = extractNameFromSoul(content)
-      if (extracted) {
-        rootName = extracted
-        rootId = extracted.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'main'
+    // Try IDENTITY.md first (most reliable source for name/emoji)
+    const identityContent = safeRead(identityPath)
+    if (identityContent) {
+      const identity = parseIdentity(identityContent)
+      if (identity.name) {
+        rootName = identity.name
+        rootId = identity.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'main'
       }
-    } catch {}
+      if (identity.emoji) rootEmoji = identity.emoji
+    }
+
+    // Fall back to SOUL.md heading if IDENTITY.md didn't provide a name
+    if (rootName === 'Main') {
+      const soulContent = safeRead(rootSoulPath)
+      if (soulContent) {
+        const parsed = parseSoulHeading(soulContent)
+        if (parsed.name) {
+          rootName = parsed.name
+          rootId = parsed.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'main'
+        }
+      }
+    }
+
+    // Collect all agent IDs that report to root (including those without SOUL.md but with sub-agents)
+    const directReportIds: string[] = []
 
     discovered.push({
       id: rootId,
       name: rootName,
       title: 'Orchestrator',
       reportsTo: null,
-      directReports: agentDirs,
+      directReports: directReportIds, // populated below
       soulPath: 'SOUL.md',
       voiceId: null,
-      color: DISCOVER_COLORS[0],
-      emoji: '\u{1F916}',
+      color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
+      emoji: rootEmoji,
       tools: ['read', 'write', 'exec', 'message'],
       memoryPath: null,
       description: 'Top-level orchestrator.',
     })
+
+    // We'll fill directReportIds as we discover agents below
+    for (const dirName of allAgentDirs) {
+      const hasSoul = existsSync(join(agentsDir, dirName, 'SOUL.md'))
+      const hasSubAgents = existsSync(join(agentsDir, dirName, 'sub-agents'))
+      const hasMembers = existsSync(join(agentsDir, dirName, 'members'))
+      if (hasSoul || hasSubAgents || hasMembers) {
+        directReportIds.push(dirName)
+      }
+    }
   }
 
-  // Build child agents from agents/ subdirectories
-  agentDirs.forEach((dirName, i) => {
+  // --- Top-level agents ---
+  for (const dirName of allAgentDirs) {
+    const soulFile = join(agentsDir, dirName, 'SOUL.md')
+    const hasSoul = existsSync(soulFile)
+    const subAgentsDir = join(agentsDir, dirName, 'sub-agents')
+    const membersDir = join(agentsDir, dirName, 'members')
+    const hasSubAgents = existsSync(subAgentsDir)
+    const hasMembers = existsSync(membersDir)
+
+    // Skip directories with nothing useful
+    if (!hasSoul && !hasSubAgents && !hasMembers) continue
+
     let name = slugToName(dirName)
     let title = 'Agent'
+    const subAgentIds: string[] = []
 
-    try {
-      const content = readFileSync(join(agentsDir, dirName, 'SOUL.md'), 'utf-8')
-      const extracted = extractNameFromSoul(content)
-      if (extracted) name = extracted
-      const roleMatch = content.match(/^(?:Role|Title):\s*(.+)/mi)
-      if (roleMatch) title = roleMatch[1].trim()
-    } catch {}
+    // Parse SOUL.md for name and title
+    if (hasSoul) {
+      const content = safeRead(soulFile)
+      if (content) {
+        const parsed = parseSoulHeading(content)
+        if (parsed.name) name = parsed.name
+        if (parsed.title) title = parsed.title
+
+        // Also check for Role: or Title: lines as fallback
+        if (title === 'Agent') {
+          const roleMatch = content.match(/^##\s*Role\b/mi)
+          if (roleMatch) {
+            // Try to get first line after ## Role
+            const afterRole = content.slice(roleMatch.index! + roleMatch[0].length)
+            const firstLine = afterRole.match(/\n\s*\n(.+)/)?.[1]?.trim()
+            // Don't use long role descriptions as titles
+            if (firstLine && firstLine.length < 80) title = firstLine
+          }
+        }
+      }
+    }
+
+    // Discover sub-agents (sub-agents/ and members/ directories)
+    const subAgentFiles = [
+      ...scanSubAgentDir(subAgentsDir),
+      ...scanSubAgentDir(membersDir),
+    ]
+
+    for (const sub of subAgentFiles) {
+      const subId = `${dirName}-${basename(sub.fileName, '.md').toLowerCase()}`
+      subAgentIds.push(subId)
+
+      const subParsed = parseSoulHeading(sub.content)
+      const subName = subParsed.name || slugToName(basename(sub.fileName, '.md'))
+      const subTitle = subParsed.title || 'Agent'
+
+      discovered.push({
+        id: subId,
+        name: subName,
+        title: subTitle,
+        reportsTo: dirName,
+        directReports: [],
+        soulPath: null, // sub-agents use non-standard paths, soul loaded differently
+        voiceId: null,
+        color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
+        emoji: subName.charAt(0).toUpperCase(),
+        tools: ['read', 'write'],
+        memoryPath: null,
+        description: `${subName} agent.`,
+      })
+    }
 
     discovered.push({
       id: dirName,
       name,
       title,
       reportsTo: hasRoot ? rootId : null,
-      directReports: [],
-      soulPath: `agents/${dirName}/SOUL.md`,
+      directReports: subAgentIds,
+      soulPath: hasSoul ? `agents/${dirName}/SOUL.md` : null,
       voiceId: null,
-      color: DISCOVER_COLORS[(i + 1) % DISCOVER_COLORS.length],
+      color: DISCOVER_COLORS[colorIndex++ % DISCOVER_COLORS.length],
       emoji: name.charAt(0).toUpperCase(),
       tools: ['read', 'write'],
       memoryPath: null,
       description: `${name} agent.`,
     })
-  })
+  }
 
   return discovered.length > 0 ? discovered : null
 }

package/lib/agents.test.ts

@@ -122,6 +122,7 @@ vi.mock('@/lib/agents.json', () => ({
 
 // We need to import AFTER mocks are set up
 import { getAgents, getAgent } from './agents'
+import { parseSoulHeading, parseIdentity } from './agents-registry'
 
 beforeEach(() => {
   vi.clearAllMocks()
@@ -131,15 +132,105 @@ beforeEach(() => {
   mockReaddirSync.mockReturnValue([])
 })
 
-/** Helper: block auto-discovery paths so bundled registry is used */
-function blockDiscovery(ws: string) {
-  return (p: string) => {
-    if (p === `${ws}/clawport/agents.json`) return false
-    if (p === `${ws}/SOUL.md`) return false
-    if (p === `${ws}/agents`) return false
-    return false
-  }
-}
+// ---------------------------------------------------------------------------
+// parseSoulHeading -- heading extraction unit tests
+// ---------------------------------------------------------------------------
+
+describe('parseSoulHeading', () => {
+  it('strips "SOUL.md — " prefix', () => {
+    const result = parseSoulHeading('# SOUL.md — VERA\nContent here')
+    expect(result.name).toBe('VERA')
+    expect(result.title).toBeNull()
+  })
+
+  it('strips "SOUL.md - " prefix (regular dash)', () => {
+    const result = parseSoulHeading('# SOUL.md - HERALD\nContent')
+    expect(result.name).toBe('HERALD')
+  })
+
+  it('returns null name for generic "Who You Are" heading', () => {
+    const result = parseSoulHeading('# SOUL.md - Who You Are\nContent')
+    expect(result.name).toBeNull()
+    expect(result.title).toBeNull()
+  })
+
+  it('parses name and title from em-dash separated heading', () => {
+    const result = parseSoulHeading('# ECHO — Community Voice Monitor\nContent')
+    expect(result.name).toBe('ECHO')
+    expect(result.title).toBe('Community Voice Monitor')
+  })
+
+  it('parses name and title from comma-separated heading after prefix strip', () => {
+    const result = parseSoulHeading('# SOUL.md — KAZE, Flight Research Agent\nContent')
+    expect(result.name).toBe('KAZE')
+    expect(result.title).toBe('Flight Research Agent')
+  })
+
+  it('parses name and title from "LUMEN, SEO Team Director" after prefix strip', () => {
+    const result = parseSoulHeading('# SOUL.md — LUMEN, SEO Team Director\nContent')
+    expect(result.name).toBe('LUMEN')
+    expect(result.title).toBe('SEO Team Director')
+  })
+
+  it('parses clean heading without prefix', () => {
+    const result = parseSoulHeading('# CARTOGRAPHER — Keyword Territory Agent\nContent')
+    expect(result.name).toBe('CARTOGRAPHER')
+    expect(result.title).toBe('Keyword Territory Agent')
+  })
+
+  it('parses sub-agent heading', () => {
+    const result = parseSoulHeading('# QUILL — Herald\'s Content Writer\n## Role')
+    expect(result.name).toBe('QUILL')
+    expect(result.title).toBe('Herald\'s Content Writer')
+  })
+
+  it('returns null for content with no heading', () => {
+    const result = parseSoulHeading('No heading here, just text.')
+    expect(result.name).toBeNull()
+    expect(result.title).toBeNull()
+  })
+
+  it('handles en-dash separator', () => {
+    const result = parseSoulHeading('# AGENT – Task Runner\nContent')
+    expect(result.name).toBe('AGENT')
+    expect(result.title).toBe('Task Runner')
+  })
+
+  it('handles simple name with no separator', () => {
+    const result = parseSoulHeading('# MyBot\nContent')
+    expect(result.name).toBe('MyBot')
+    expect(result.title).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parseIdentity
+// ---------------------------------------------------------------------------
+
+describe('parseIdentity', () => {
+  it('extracts name and emoji from IDENTITY.md format', () => {
+    const content = `# IDENTITY.md - Who Am I?
+
+- **Name:** Jarvis
+- **Creature:** AI assistant
+- **Emoji:** 🤖`
+    const result = parseIdentity(content)
+    expect(result.name).toBe('Jarvis')
+    expect(result.emoji).toBe('🤖')
+  })
+
+  it('returns nulls when fields are missing', () => {
+    const result = parseIdentity('# Just a heading\nNo identity fields here.')
+    expect(result.name).toBeNull()
+    expect(result.emoji).toBeNull()
+  })
+
+  it('handles name without emoji', () => {
+    const result = parseIdentity('- **Name:** CustomBot')
+    expect(result.name).toBe('CustomBot')
+    expect(result.emoji).toBeNull()
+  })
+})
 
 // ---------------------------------------------------------------------------
 // Registry loading: bundled fallback vs workspace override vs auto-discovery
@@ -212,7 +303,6 @@ describe('agent registry loading', () => {
     })
 
     const agents = await getAgents()
-    // Should fall back to bundled agents, not crash
     expect(agents.length).toBe(bundledAgents.length)
     expect(agents.map(a => a.id)).toContain('jarvis')
   })
@@ -244,7 +334,6 @@ describe('agent registry loading', () => {
 
     mockExistsSync.mockImplementation((p: string) => {
       if (p === '/tmp/ws/clawport/agents.json') return true
-      // These would trigger discovery, but override takes priority
       if (p === '/tmp/ws/SOUL.md') return true
       if (p === '/tmp/ws/agents') return true
       return false
@@ -265,50 +354,214 @@ describe('agent registry loading', () => {
 // ---------------------------------------------------------------------------
 
 describe('auto-discovery from workspace', () => {
-  it('discovers agents from workspace agents/ directory', async () => {
+  it('discovers agents and uses IDENTITY.md for root name/emoji', async () => {
     vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
 
     mockExistsSync.mockImplementation((p: string) => {
       if (p === '/tmp/ws/clawport/agents.json') return false
       if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/IDENTITY.md') return true
       if (p === '/tmp/ws/agents') return true
-      if (p === '/tmp/ws/agents/bot-a/SOUL.md') return true
-      if (p === '/tmp/ws/agents/bot-b/SOUL.md') return true
+      if (p === '/tmp/ws/agents/echo/SOUL.md') return true
+      if (p === '/tmp/ws/agents/echo/sub-agents') return false
+      if (p === '/tmp/ws/agents/echo/members') return false
       return false
     })
 
     mockReaddirSync.mockReturnValue([
-      { name: 'bot-a', isDirectory: () => true },
-      { name: 'bot-b', isDirectory: () => true },
-      { name: 'README.md', isDirectory: () => false },
+      { name: 'echo', isDirectory: () => true },
     ])
 
     mockReadFileSync.mockImplementation((p: string) => {
-      if (p === '/tmp/ws/SOUL.md') return '# MyOrchestrator'
-      if (p === '/tmp/ws/agents/bot-a/SOUL.md') return '# Bot Alpha\nRole: Data Analyst'
-      if (p === '/tmp/ws/agents/bot-b/SOUL.md') return '# Bot Beta'
+      if (p === '/tmp/ws/IDENTITY.md') return '- **Name:** Jarvis\n- **Emoji:** 🤖'
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md - Who You Are\nContent'
+      if (p === '/tmp/ws/agents/echo/SOUL.md') return '# ECHO — Community Voice Monitor\nContent'
       throw new Error('ENOENT')
     })
 
     const agents = await getAgents()
-    expect(agents).toHaveLength(3) // root + 2 agents
+    const root = agents.find(a => a.reportsTo === null)!
+    expect(root.name).toBe('Jarvis')
+    expect(root.id).toBe('jarvis')
+    expect(root.emoji).toBe('🤖')
+    expect(root.directReports).toContain('echo')
+
+    const echo = agents.find(a => a.id === 'echo')!
+    expect(echo.name).toBe('ECHO')
+    expect(echo.title).toBe('Community Voice Monitor')
+    expect(echo.reportsTo).toBe('jarvis')
+  })
+
+  it('falls back to SOUL.md heading when IDENTITY.md is missing', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/IDENTITY.md') return false
+      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/bot/SOUL.md') return true
+      if (p === '/tmp/ws/agents/bot/sub-agents') return false
+      if (p === '/tmp/ws/agents/bot/members') return false
+      return false
+    })
+
+    mockReaddirSync.mockReturnValue([
+      { name: 'bot', isDirectory: () => true },
+    ])
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md — MyBot\nContent'
+      if (p === '/tmp/ws/agents/bot/SOUL.md') return '# Bot Agent\nContent'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const root = agents.find(a => a.reportsTo === null)!
+    expect(root.name).toBe('MyBot')
+    expect(root.id).toBe('mybot')
+  })
+
+  it('uses "Main" as root name when SOUL.md heading is generic', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/IDENTITY.md') return false
+      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/bot/SOUL.md') return true
+      if (p === '/tmp/ws/agents/bot/sub-agents') return false
+      if (p === '/tmp/ws/agents/bot/members') return false
+      return false
+    })
+
+    mockReaddirSync.mockReturnValue([
+      { name: 'bot', isDirectory: () => true },
+    ])
 
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md - Who You Are\nContent'
+      if (p === '/tmp/ws/agents/bot/SOUL.md') return '# Bot\nContent'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
     const root = agents.find(a => a.reportsTo === null)!
-    expect(root.name).toBe('MyOrchestrator')
-    expect(root.soulPath).toBe('SOUL.md')
-    expect(root.soul).toBe('# MyOrchestrator')
-    expect(root.directReports).toEqual(['bot-a', 'bot-b'])
+    expect(root.name).toBe('Main')
+    expect(root.id).toBe('main')
+  })
+
+  it('discovers sub-agents in sub-agents/ directory', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/IDENTITY.md') return false
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/herald/SOUL.md') return true
+      if (p === '/tmp/ws/agents/herald/sub-agents') return true
+      if (p === '/tmp/ws/agents/herald/sub-agents/QUILL.md') return true
+      if (p === '/tmp/ws/agents/herald/sub-agents/MAVEN.md') return true
+      if (p === '/tmp/ws/agents/herald/members') return false
+      return false
+    })
+
+    // First call: agents/ dir, second call: sub-agents/ dir
+    mockReaddirSync
+      .mockReturnValueOnce([{ name: 'herald', isDirectory: () => true }])
+      .mockReturnValueOnce(['QUILL.md', 'MAVEN.md'])
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/SOUL.md') return '# SOUL.md - Who You Are'
+      if (p === '/tmp/ws/agents/herald/SOUL.md') return '# SOUL.md — HERALD\n## Role'
+      if (p === '/tmp/ws/agents/herald/sub-agents/QUILL.md') return '# QUILL — Content Writer'
+      if (p === '/tmp/ws/agents/herald/sub-agents/MAVEN.md') return '# MAVEN — LinkedIn Strategist'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const herald = agents.find(a => a.id === 'herald')!
+    expect(herald.name).toBe('HERALD')
+    expect(herald.directReports).toContain('herald-quill')
+    expect(herald.directReports).toContain('herald-maven')
+
+    const quill = agents.find(a => a.id === 'herald-quill')!
+    expect(quill.name).toBe('QUILL')
+    expect(quill.title).toBe('Content Writer')
+    expect(quill.reportsTo).toBe('herald')
+
+    const maven = agents.find(a => a.id === 'herald-maven')!
+    expect(maven.name).toBe('MAVEN')
+    expect(maven.title).toBe('LinkedIn Strategist')
+    expect(maven.reportsTo).toBe('herald')
+  })
+
+  it('discovers members/ directory agents', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/seo-team/SOUL.md') return true
+      if (p === '/tmp/ws/agents/seo-team/sub-agents') return false
+      if (p === '/tmp/ws/agents/seo-team/members') return true
+      if (p === '/tmp/ws/agents/seo-team/members/WRITER.md') return true
+      return false
+    })
+
+    mockReaddirSync
+      .mockReturnValueOnce([{ name: 'seo-team', isDirectory: () => true }])
+      .mockReturnValueOnce(['WRITER.md'])
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/agents/seo-team/SOUL.md') return '# SOUL.md — LUMEN, SEO Team Director'
+      if (p === '/tmp/ws/agents/seo-team/members/WRITER.md') return '# WRITER — Conversion-Focused Content Creator'
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    const lumen = agents.find(a => a.id === 'seo-team')!
+    expect(lumen.name).toBe('LUMEN')
+    expect(lumen.title).toBe('SEO Team Director')
+    expect(lumen.directReports).toContain('seo-team-writer')
+
+    const writer = agents.find(a => a.id === 'seo-team-writer')!
+    expect(writer.name).toBe('WRITER')
+    expect(writer.title).toBe('Conversion-Focused Content Creator')
+    expect(writer.reportsTo).toBe('seo-team')
+  })
+
+  it('discovers dirs without SOUL.md if they have sub-agents', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/clawport/agents.json') return false
+      if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/agents') return true
+      if (p === '/tmp/ws/agents/team/SOUL.md') return false // no SOUL.md!
+      if (p === '/tmp/ws/agents/team/sub-agents') return true
+      if (p === '/tmp/ws/agents/team/sub-agents/WORKER.md') return true
+      if (p === '/tmp/ws/agents/team/members') return false
+      return false
+    })
 
-    const botA = agents.find(a => a.id === 'bot-a')!
-    expect(botA.name).toBe('Bot Alpha')
-    expect(botA.title).toBe('Data Analyst')
-    expect(botA.reportsTo).toBe(root.id)
-    expect(botA.soulPath).toBe('agents/bot-a/SOUL.md')
-    expect(botA.soul).toBe('# Bot Alpha\nRole: Data Analyst')
+    mockReaddirSync
+      .mockReturnValueOnce([{ name: 'team', isDirectory: () => true }])
+      .mockReturnValueOnce(['WORKER.md'])
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === '/tmp/ws/agents/team/sub-agents/WORKER.md') return '# WORKER — Task Runner'
+      throw new Error('ENOENT')
+    })
 
-    const botB = agents.find(a => a.id === 'bot-b')!
-    expect(botB.name).toBe('Bot Beta')
-    expect(botB.reportsTo).toBe(root.id)
+    const agents = await getAgents()
+    const team = agents.find(a => a.id === 'team')!
+    expect(team.name).toBe('Team')
+    expect(team.soulPath).toBeNull()
+    expect(team.directReports).toContain('team-worker')
   })
 
   it('discovers agents without root SOUL.md (flat structure)', async () => {
@@ -319,6 +572,8 @@ describe('auto-discovery from workspace', () => {
       if (p === '/tmp/ws/SOUL.md') return false
       if (p === '/tmp/ws/agents') return true
       if (p === '/tmp/ws/agents/worker/SOUL.md') return true
+      if (p === '/tmp/ws/agents/worker/sub-agents') return false
+      if (p === '/tmp/ws/agents/worker/members') return false
       return false
     })
 
@@ -345,59 +600,69 @@ describe('auto-discovery from workspace', () => {
     expect(agents.length).toBe(bundledAgents.length)
   })
 
-  it('skips directories without SOUL.md', async () => {
+  it('uses directory slug as name when SOUL.md has no heading', async () => {
     vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
 
     mockExistsSync.mockImplementation((p: string) => {
       if (p === '/tmp/ws/clawport/agents.json') return false
-      if (p === '/tmp/ws/SOUL.md') return true
+      if (p === '/tmp/ws/SOUL.md') return false
       if (p === '/tmp/ws/agents') return true
-      if (p === '/tmp/ws/agents/valid/SOUL.md') return true
-      if (p === '/tmp/ws/agents/empty/SOUL.md') return false // no SOUL.md
+      if (p === '/tmp/ws/agents/my-bot/SOUL.md') return true
+      if (p === '/tmp/ws/agents/my-bot/sub-agents') return false
+      if (p === '/tmp/ws/agents/my-bot/members') return false
       return false
     })
 
     mockReaddirSync.mockReturnValue([
-      { name: 'valid', isDirectory: () => true },
-      { name: 'empty', isDirectory: () => true },
+      { name: 'my-bot', isDirectory: () => true },
     ])
 
     mockReadFileSync.mockImplementation((p: string) => {
-      if (p === '/tmp/ws/SOUL.md') return '# Root'
-      if (p === '/tmp/ws/agents/valid/SOUL.md') return '# Valid Agent'
+      if (p === '/tmp/ws/agents/my-bot/SOUL.md') return 'No heading here, just text.'
       throw new Error('ENOENT')
     })
 
     const agents = await getAgents()
-    // root + 1 valid agent (empty skipped)
-    expect(agents).toHaveLength(2)
-    expect(agents.map(a => a.id)).not.toContain('empty')
+    expect(agents).toHaveLength(1)
+    expect(agents[0].id).toBe('my-bot')
+    expect(agents[0].name).toBe('My Bot') // slugToName
   })
 
-  it('uses directory name as fallback when SOUL.md has no heading', async () => {
+  it('strips SOUL.md prefix from agent names in discovery', async () => {
     vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
 
     mockExistsSync.mockImplementation((p: string) => {
       if (p === '/tmp/ws/clawport/agents.json') return false
       if (p === '/tmp/ws/SOUL.md') return false
       if (p === '/tmp/ws/agents') return true
-      if (p === '/tmp/ws/agents/my-bot/SOUL.md') return true
+      if (p === '/tmp/ws/agents/vera/SOUL.md') return true
+      if (p === '/tmp/ws/agents/vera/sub-agents') return false
+      if (p === '/tmp/ws/agents/vera/members') return false
+      if (p === '/tmp/ws/agents/kaze/SOUL.md') return true
+      if (p === '/tmp/ws/agents/kaze/sub-agents') return false
+      if (p === '/tmp/ws/agents/kaze/members') return false
       return false
     })
 
     mockReaddirSync.mockReturnValue([
-      { name: 'my-bot', isDirectory: () => true },
+      { name: 'vera', isDirectory: () => true },
+      { name: 'kaze', isDirectory: () => true },
     ])
 
     mockReadFileSync.mockImplementation((p: string) => {
-      if (p === '/tmp/ws/agents/my-bot/SOUL.md') return 'No heading here, just text.'
+      if (p === '/tmp/ws/agents/vera/SOUL.md') return '# SOUL.md — VERA'
+      if (p === '/tmp/ws/agents/kaze/SOUL.md') return '# SOUL.md — KAZE, Flight Research Agent'
       throw new Error('ENOENT')
     })
 
     const agents = await getAgents()
-    expect(agents).toHaveLength(1)
-    expect(agents[0].id).toBe('my-bot')
-    expect(agents[0].name).toBe('My Bot') // slugToName
+    const vera = agents.find(a => a.id === 'vera')!
+    expect(vera.name).toBe('VERA')
+    expect(vera.title).toBe('Agent') // no title from heading alone
+
+    const kaze = agents.find(a => a.id === 'kaze')!
+    expect(kaze.name).toBe('KAZE')
+    expect(kaze.title).toBe('Flight Research Agent')
   })
 })
 
@@ -459,12 +724,12 @@ describe('getAgents', () => {
       // Block auto-discovery, allow SOUL file reads for bundled agents
       if (p === '/tmp/ws/clawport/agents.json') return false
       if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/IDENTITY.md') return false
       if (p === '/tmp/ws/agents') return false
       return true
     })
     mockReadFileSync.mockReturnValue('# Agent SOUL content')
     const agents = await getAgents()
-    // vera has soulPath: 'agents/vera/SOUL.md' which won't conflict with discovery
     const vera = agents.find(a => a.id === 'vera')!
     expect(vera.soul).toBe('# Agent SOUL content')
   })
@@ -474,6 +739,7 @@ describe('getAgents', () => {
     mockExistsSync.mockImplementation((p: string) => {
       if (p === '/tmp/ws/clawport/agents.json') return false
       if (p === '/tmp/ws/SOUL.md') return false
+      if (p === '/tmp/ws/IDENTITY.md') return false
       if (p === '/tmp/ws/agents') return false
       return true
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawport-ui",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.",
   "homepage": "https://clawport.dev",
   "repository": {

package/scripts/setup.mjs

@@ -64,6 +64,34 @@ function detectGatewayToken() {
   }
 }
 
+function checkHttpEndpointEnabled() {
+  const configPath = join(homedir(), '.openclaw', 'openclaw.json')
+  if (!existsSync(configPath)) return null // can't check
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+    return config?.gateway?.http?.endpoints?.chatCompletions?.enabled === true
+  } catch {
+    return null
+  }
+}
+
+function enableHttpEndpoint() {
+  const configPath = join(homedir(), '.openclaw', 'openclaw.json')
+  if (!existsSync(configPath)) return false
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+    if (!config.gateway) config.gateway = {}
+    if (!config.gateway.http) config.gateway.http = {}
+    if (!config.gateway.http.endpoints) config.gateway.http.endpoints = {}
+    if (!config.gateway.http.endpoints.chatCompletions) config.gateway.http.endpoints.chatCompletions = {}
+    config.gateway.http.endpoints.chatCompletions.enabled = true
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8')
+    return true
+  } catch {
+    return false
+  }
+}
+
 async function checkGatewayRunning() {
   try {
     const res = await fetch('http://127.0.0.1:18789/', {
@@ -123,6 +151,24 @@ async function main() {
     console.log(`  ${yellow('!')} Gateway not responding at localhost:18789`)
     console.log(`    ${dim('Start it with: openclaw gateway run')}`)
   }
+
+  // Check HTTP chat completions endpoint
+  const httpEnabled = checkHttpEndpointEnabled()
+  if (httpEnabled === true) {
+    console.log(`  ${green('+')} HTTP chat completions endpoint ${dim('enabled')}`)
+  } else if (httpEnabled === false) {
+    console.log(`  ${yellow('!')} HTTP chat completions endpoint is ${bold('disabled')}`)
+    console.log(`    ${dim('ClawPort needs this to chat with agents.')}`)
+    const enable = await ask(`  ${yellow('?')} Enable it in openclaw.json? (Y/n) `)
+    if (enable.toLowerCase() !== 'n') {
+      if (enableHttpEndpoint()) {
+        console.log(`  ${green('+')} Enabled! ${dim('Restart the gateway for this to take effect.')}`)
+      } else {
+        console.log(`  ${red('x')} Could not update openclaw.json. Enable it manually:`)
+        console.log(`    ${dim('Set gateway.http.endpoints.chatCompletions.enabled = true in ~/.openclaw/openclaw.json')}`)
+      }
+    }
+  }
   console.log()
 
   // Handle missing values