clawport-ui 0.1.0

package/lib/agents-registry.ts

@@ -0,0 +1,35 @@
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import bundledRegistry from '@/lib/agents.json'
+import type { Agent } from '@/lib/types'
+
+/** Raw agent data from JSON (everything except runtime-loaded soul and crons) */
+export type AgentEntry = Omit<Agent, 'soul' | 'crons'>
+
+/**
+ * Load the agent registry, checking for a user-provided override first.
+ *
+ * Resolution order:
+ *   1. $WORKSPACE_PATH/clawport/agents.json  (user's own config)
+ *   2. Bundled lib/agents.json               (default example registry)
+ *
+ * This lets any OpenClaw user customise their agent team without editing
+ * ClawPort source code -- just drop an agents.json into their workspace.
+ */
+export function loadRegistry(): AgentEntry[] {
+  const workspacePath = process.env.WORKSPACE_PATH
+
+  if (workspacePath) {
+    const userRegistryPath = join(workspacePath, 'clawport', 'agents.json')
+    if (existsSync(userRegistryPath)) {
+      try {
+        const raw = readFileSync(userRegistryPath, 'utf-8')
+        return JSON.parse(raw) as AgentEntry[]
+      } catch {
+        // Malformed user JSON -- fall through to bundled default
+      }
+    }
+  }
+
+  return bundledRegistry as AgentEntry[]
+}

package/lib/agents.json

@@ -0,0 +1,282 @@
+[
+  {
+    "id": "jarvis",
+    "name": "Jarvis",
+    "title": "Orchestrator",
+    "reportsTo": null,
+    "directReports": ["vera", "lumen", "herald", "pulse", "echo", "sage", "kaze", "spark", "scribe"],
+    "soulPath": "SOUL.md",
+    "voiceId": "agL69Vji082CshT65Tcy",
+    "color": "#f5c518",
+    "emoji": "\ud83e\udd16",
+    "tools": ["exec", "read", "write", "edit", "web_search", "tts", "message", "sessions_spawn", "memory_search"],
+    "memoryPath": null,
+    "description": "Top-level orchestrator. Manages the team, holds memory, delivers briefings."
+  },
+  {
+    "id": "vera",
+    "name": "VERA",
+    "title": "Chief Strategy Officer",
+    "reportsTo": "jarvis",
+    "directReports": ["robin"],
+    "soulPath": "agents/vera/SOUL.md",
+    "voiceId": "EAHourGM2PqzHHl0Ywjp",
+    "color": "#a855f7",
+    "emoji": "\u265f\ufe0f",
+    "tools": ["web_search", "web_fetch", "read", "write", "sessions_spawn"],
+    "memoryPath": null,
+    "description": "CSO. Manages validation team. Decides what gets built and what gets killed."
+  },
+  {
+    "id": "robin",
+    "name": "Robin",
+    "title": "Field Intel Operator",
+    "reportsTo": "vera",
+    "directReports": ["trace", "proof"],
+    "soulPath": "agents/robin/SOUL.md",
+    "voiceId": "IRHApOXLvnW57QJPQH2P",
+    "color": "#3b82f6",
+    "emoji": "\ud83e\udd85",
+    "tools": ["web_search", "web_fetch", "read", "write", "message"],
+    "memoryPath": null,
+    "description": "Field operator. Competitive intel, opportunity scouting, lead signals."
+  },
+  {
+    "id": "trace",
+    "name": "TRACE",
+    "title": "Market Researcher",
+    "reportsTo": "robin",
+    "directReports": [],
+    "soulPath": "agents/trace/SOUL.md",
+    "voiceId": null,
+    "color": "#06b6d4",
+    "emoji": "\ud83d\udd0d",
+    "tools": ["web_search", "web_fetch", "read", "write"],
+    "memoryPath": null,
+    "description": "Market research. TAM, competitors, pricing benchmarks. Returns Market Briefs."
+  },
+  {
+    "id": "proof",
+    "name": "PROOF",
+    "title": "Validation Designer",
+    "reportsTo": "robin",
+    "directReports": [],
+    "soulPath": "agents/proof/SOUL.md",
+    "voiceId": null,
+    "color": "#06b6d4",
+    "emoji": "\u2705",
+    "tools": ["web_search", "web_fetch", "read", "write"],
+    "memoryPath": null,
+    "description": "Designs minimum viable tests. Writes outreach copy. Calls BUILD/KILL/PIVOT."
+  },
+  {
+    "id": "lumen",
+    "name": "LUMEN",
+    "title": "SEO Team Director",
+    "reportsTo": "jarvis",
+    "directReports": ["scout", "analyst", "strategist", "writer", "auditor"],
+    "soulPath": "agents/seo-team/SOUL.md",
+    "voiceId": "EVy5l1wEi54nXdQwAJJf",
+    "color": "#22c55e",
+    "emoji": "\ud83d\udd26",
+    "tools": ["web_search", "web_fetch", "read", "write", "exec"],
+    "memoryPath": null,
+    "description": "SEO Team Director. Runs SCOUT\u2192ANALYST\u2192STRATEGIST\u2192WRITER pipeline."
+  },
+  {
+    "id": "scout",
+    "name": "SCOUT",
+    "title": "Content Scout",
+    "reportsTo": "lumen",
+    "directReports": [],
+    "soulPath": null,
+    "voiceId": null,
+    "color": "#86efac",
+    "emoji": "\ud83d\uddfa\ufe0f",
+    "tools": ["web_search", "web_fetch", "read"],
+    "memoryPath": null,
+    "description": "Scouts trending topics, pulls RSS feeds, identifies content opportunities."
+  },
+  {
+    "id": "analyst",
+    "name": "ANALYST",
+    "title": "SEO Analyst",
+    "reportsTo": "lumen",
+    "directReports": [],
+    "soulPath": null,
+    "voiceId": null,
+    "color": "#86efac",
+    "emoji": "\ud83d\udcca",
+    "tools": ["web_search", "web_fetch", "read", "write"],
+    "memoryPath": null,
+    "description": "Keyword research, GSC data analysis, competitive gap identification."
+  },
+  {
+    "id": "strategist",
+    "name": "STRATEGIST",
+    "title": "Content Strategist",
+    "reportsTo": "lumen",
+    "directReports": [],
+    "soulPath": null,
+    "voiceId": null,
+    "color": "#86efac",
+    "emoji": "\ud83c\udfaf",
+    "tools": ["read", "write"],
+    "memoryPath": null,
+    "description": "Topic angle selection using SAGE and ECHO briefs."
+  },
+  {
+    "id": "writer",
+    "name": "WRITER",
+    "title": "Content Writer",
+    "reportsTo": "lumen",
+    "directReports": [],
+    "soulPath": null,
+    "voiceId": null,
+    "color": "#86efac",
+    "emoji": "\u270d\ufe0f",
+    "tools": ["read", "write"],
+    "memoryPath": null,
+    "description": "1500-2000 word posts in the operator's voice."
+  },
+  {
+    "id": "auditor",
+    "name": "AUDITOR",
+    "title": "Quality Gate",
+    "reportsTo": "lumen",
+    "directReports": [],
+    "soulPath": null,
+    "voiceId": null,
+    "color": "#86efac",
+    "emoji": "\ud83d\udee1\ufe0f",
+    "tools": ["read", "write"],
+    "memoryPath": null,
+    "description": "Pre-ship quality gate. 6-item checklist before publishing."
+  },
+  {
+    "id": "herald",
+    "name": "HERALD",
+    "title": "LinkedIn Content Director",
+    "reportsTo": "jarvis",
+    "directReports": ["quill", "maven"],
+    "soulPath": "agents/herald/SOUL.md",
+    "voiceId": null,
+    "color": "#f97316",
+    "emoji": "\ud83d\udce3",
+    "tools": ["web_search", "web_fetch", "read", "write", "message", "exec"],
+    "memoryPath": null,
+    "description": "LinkedIn content pipeline. Reads Pulse feed, picks angles, briefs QUILL."
+  },
+  {
+    "id": "quill",
+    "name": "QUILL",
+    "title": "LinkedIn Writer",
+    "reportsTo": "herald",
+    "directReports": [],
+    "soulPath": "agents/herald/sub-agents/QUILL.md",
+    "voiceId": null,
+    "color": "#fdba74",
+    "emoji": "\ud83d\udd8a\ufe0f",
+    "tools": ["read", "write"],
+    "memoryPath": null,
+    "description": "Writes LinkedIn posts in the operator's voice."
+  },
+  {
+    "id": "maven",
+    "name": "MAVEN",
+    "title": "LinkedIn Strategist",
+    "reportsTo": "herald",
+    "directReports": [],
+    "soulPath": "agents/herald/sub-agents/MAVEN.md",
+    "voiceId": null,
+    "color": "#fdba74",
+    "emoji": "\ud83e\udded",
+    "tools": ["web_search", "read", "write"],
+    "memoryPath": null,
+    "description": "Weekly LinkedIn strategy and content calendar."
+  },
+  {
+    "id": "pulse",
+    "name": "Pulse",
+    "title": "Trend Radar",
+    "reportsTo": "jarvis",
+    "directReports": [],
+    "soulPath": "agents/pulse/SOUL.md",
+    "voiceId": "eadgjmk4R4uojdsheG9t",
+    "color": "#eab308",
+    "emoji": "\ud83c\udf0a",
+    "tools": ["web_search", "web_fetch", "read", "write", "message"],
+    "memoryPath": null,
+    "description": "Hype radar. Monitors trending signals. Feeds hot topics to LUMEN."
+  },
+  {
+    "id": "echo",
+    "name": "ECHO",
+    "title": "Community Voice Monitor",
+    "reportsTo": "jarvis",
+    "directReports": [],
+    "soulPath": "agents/echo/SOUL.md",
+    "voiceId": null,
+    "color": "#14b8a6",
+    "emoji": "\ud83d\udce1",
+    "tools": ["web_fetch", "read", "write"],
+    "memoryPath": null,
+    "description": "Scans ICP subreddits weekly. Extracts verbatim customer language."
+  },
+  {
+    "id": "sage",
+    "name": "SAGE",
+    "title": "ICP & Market Expert",
+    "reportsTo": "jarvis",
+    "directReports": [],
+    "soulPath": "agents/sage/SOUL.md",
+    "voiceId": null,
+    "color": "#14b8a6",
+    "emoji": "\ud83e\uddd9",
+    "tools": ["read"],
+    "memoryPath": null,
+    "description": "Deep ICP and market knowledge. Injected into STRATEGIST and WRITER."
+  },
+  {
+    "id": "kaze",
+    "name": "KAZE",
+    "title": "Japan Flight Monitor",
+    "reportsTo": "jarvis",
+    "directReports": [],
+    "soulPath": "agents/kaze/SOUL.md",
+    "voiceId": null,
+    "color": "#60a5fa",
+    "emoji": "\u2708\ufe0f",
+    "tools": ["web_fetch", "message"],
+    "memoryPath": null,
+    "description": "Monitors MSP to Tokyo flights. Alerts on deals under $1400."
+  },
+  {
+    "id": "spark",
+    "name": "SPARK",
+    "title": "Tech Discovery",
+    "reportsTo": "jarvis",
+    "directReports": [],
+    "soulPath": "agents/spark/SOUL.md",
+    "voiceId": "xNtG3W2oqJs0cJZuTyBc",
+    "color": "#f59e0b",
+    "emoji": "\u26a1",
+    "tools": ["web_fetch", "web_search", "message"],
+    "memoryPath": null,
+    "description": "Finds cool OpenClaw builds. Reports every other day."
+  },
+  {
+    "id": "scribe",
+    "name": "SCRIBE",
+    "title": "Memory Architect",
+    "reportsTo": "jarvis",
+    "directReports": [],
+    "soulPath": "agents/scribe/SOUL.md",
+    "voiceId": null,
+    "color": "#94a3b8",
+    "emoji": "\ud83d\udcda",
+    "tools": ["read", "write", "exec"],
+    "memoryPath": null,
+    "description": "Weekly memory compression. Silent worker."
+  }
+]

package/lib/agents.test.ts

@@ -0,0 +1,367 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockReadFileSync, mockExistsSync, bundledAgents } = vi.hoisted(() => ({
+  mockReadFileSync: vi.fn(),
+  mockExistsSync: vi.fn(),
+  bundledAgents: [
+    {
+      id: 'jarvis',
+      name: 'Jarvis',
+      title: 'Orchestrator',
+      reportsTo: null,
+      directReports: ['vera', 'lumen', 'pulse'],
+      soulPath: 'SOUL.md',
+      voiceId: 'agL69Vji082CshT65Tcy',
+      color: '#f5c518',
+      emoji: 'R',
+      tools: ['exec', 'read', 'write'],
+      memoryPath: null,
+      description: 'Top-level orchestrator.',
+    },
+    {
+      id: 'vera',
+      name: 'VERA',
+      title: 'Chief Strategy Officer',
+      reportsTo: 'jarvis',
+      directReports: ['robin'],
+      soulPath: 'agents/vera/SOUL.md',
+      voiceId: 'EAHourGM2PqzHHl0Ywjp',
+      color: '#a855f7',
+      emoji: 'P',
+      tools: ['web_search', 'read'],
+      memoryPath: null,
+      description: 'CSO. Decides what gets built.',
+    },
+    {
+      id: 'robin',
+      name: 'Robin',
+      title: 'Field Intel Operator',
+      reportsTo: 'vera',
+      directReports: [],
+      soulPath: 'agents/robin/SOUL.md',
+      voiceId: null,
+      color: '#3b82f6',
+      emoji: 'E',
+      tools: ['web_search'],
+      memoryPath: null,
+      description: 'Field operator.',
+    },
+    {
+      id: 'lumen',
+      name: 'LUMEN',
+      title: 'SEO Team Director',
+      reportsTo: 'jarvis',
+      directReports: ['scout'],
+      soulPath: 'agents/seo-team/SOUL.md',
+      voiceId: null,
+      color: '#22c55e',
+      emoji: 'L',
+      tools: ['web_search', 'read'],
+      memoryPath: null,
+      description: 'SEO Team Director.',
+    },
+    {
+      id: 'scout',
+      name: 'SCOUT',
+      title: 'Content Scout',
+      reportsTo: 'lumen',
+      directReports: [],
+      soulPath: null,
+      voiceId: null,
+      color: '#86efac',
+      emoji: 'S',
+      tools: ['web_search'],
+      memoryPath: null,
+      description: 'Scouts trending topics.',
+    },
+    {
+      id: 'pulse',
+      name: 'Pulse',
+      title: 'Trend Radar',
+      reportsTo: 'jarvis',
+      directReports: [],
+      soulPath: 'agents/pulse/SOUL.md',
+      voiceId: null,
+      color: '#eab308',
+      emoji: 'W',
+      tools: ['web_search'],
+      memoryPath: null,
+      description: 'Hype radar.',
+    },
+    {
+      id: 'kaze',
+      name: 'KAZE',
+      title: 'Japan Flight Monitor',
+      reportsTo: 'jarvis',
+      directReports: [],
+      soulPath: null,
+      voiceId: null,
+      color: '#60a5fa',
+      emoji: 'A',
+      tools: ['web_fetch'],
+      memoryPath: null,
+      description: 'Monitors flights.',
+    },
+  ],
+}))
+
+// Mock fs (Dependency Inversion -- no real file system access in tests)
+vi.mock('fs', () => ({
+  readFileSync: mockReadFileSync,
+  existsSync: mockExistsSync,
+  default: { readFileSync: mockReadFileSync, existsSync: mockExistsSync },
+}))
+
+// Mock the bundled agents.json
+vi.mock('@/lib/agents.json', () => ({
+  default: bundledAgents,
+}))
+
+// We need to import AFTER mocks are set up
+import { getAgents, getAgent } from './agents'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.unstubAllEnvs()
+  // Default: no SOUL files exist on disk
+  mockExistsSync.mockReturnValue(false)
+})
+
+// ---------------------------------------------------------------------------
+// Registry loading: bundled fallback vs workspace override
+// ---------------------------------------------------------------------------
+
+describe('agent registry loading', () => {
+  it('loads from bundled JSON when WORKSPACE_PATH is not set', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '')
+    const agents = await getAgents()
+    expect(agents.length).toBe(bundledAgents.length)
+    expect(agents.map(a => a.id)).toContain('jarvis')
+  })
+
+  it('loads from bundled JSON when workspace override file does not exist', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/test-workspace')
+    mockExistsSync.mockReturnValue(false)
+    const agents = await getAgents()
+    expect(agents.length).toBe(bundledAgents.length)
+  })
+
+  it('loads from workspace override when clawport/agents.json exists', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/test-workspace')
+
+    const customAgents = [
+      {
+        id: 'custom-bot',
+        name: 'CustomBot',
+        title: 'Custom Agent',
+        reportsTo: null,
+        directReports: [],
+        soulPath: null,
+        voiceId: null,
+        color: '#ff0000',
+        emoji: 'C',
+        tools: ['read'],
+        memoryPath: null,
+        description: 'A custom agent.',
+      },
+    ]
+
+    mockExistsSync.mockImplementation((path: string) => {
+      if (path === '/tmp/test-workspace/clawport/agents.json') return true
+      return false
+    })
+    mockReadFileSync.mockImplementation((path: string) => {
+      if (path === '/tmp/test-workspace/clawport/agents.json') {
+        return JSON.stringify(customAgents)
+      }
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    expect(agents.length).toBe(1)
+    expect(agents[0].id).toBe('custom-bot')
+    expect(agents[0].name).toBe('CustomBot')
+  })
+
+  it('falls back to bundled JSON when workspace agents.json is malformed', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/test-workspace')
+
+    mockExistsSync.mockImplementation((path: string) => {
+      if (path === '/tmp/test-workspace/clawport/agents.json') return true
+      return false
+    })
+    mockReadFileSync.mockImplementation((path: string) => {
+      if (path === '/tmp/test-workspace/clawport/agents.json') {
+        return '{ invalid json !!!'
+      }
+      throw new Error('ENOENT')
+    })
+
+    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')
+  })
+
+  it('falls back to bundled JSON when workspace agents.json read throws', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/test-workspace')
+
+    mockExistsSync.mockImplementation((path: string) => {
+      if (path === '/tmp/test-workspace/clawport/agents.json') return true
+      return false
+    })
+    mockReadFileSync.mockImplementation((path: string) => {
+      if (path === '/tmp/test-workspace/clawport/agents.json') {
+        throw new Error('EACCES')
+      }
+      throw new Error('ENOENT')
+    })
+
+    const agents = await getAgents()
+    expect(agents.length).toBe(bundledAgents.length)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getAgents
+// ---------------------------------------------------------------------------
+
+describe('getAgents', () => {
+  it('returns all agents from the registry', async () => {
+    const agents = await getAgents()
+    expect(agents.length).toBeGreaterThan(0)
+  })
+
+  it('every agent has required fields', async () => {
+    const agents = await getAgents()
+    for (const agent of agents) {
+      expect(agent.id).toEqual(expect.any(String))
+      expect(agent.name).toEqual(expect.any(String))
+      expect(agent.title).toEqual(expect.any(String))
+      expect(agent.color).toMatch(/^#[0-9a-fA-F]{6}$/)
+      expect(agent.emoji).toEqual(expect.any(String))
+      expect(Array.isArray(agent.tools)).toBe(true)
+      expect(Array.isArray(agent.directReports)).toBe(true)
+      expect(Array.isArray(agent.crons)).toBe(true)
+      expect(agent.description).toEqual(expect.any(String))
+    }
+  })
+
+  it('includes known agents by id', async () => {
+    const agents = await getAgents()
+    const ids = agents.map(a => a.id)
+    expect(ids).toContain('jarvis')
+    expect(ids).toContain('vera')
+    expect(ids).toContain('lumen')
+    expect(ids).toContain('pulse')
+    expect(ids).toContain('kaze')
+  })
+
+  it('sets soul to null when WORKSPACE_PATH is not set', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '')
+    const agents = await getAgents()
+    const jarvis = agents.find(a => a.id === 'jarvis')!
+    expect(jarvis.soulPath).toBeTruthy()
+    expect(jarvis.soul).toBeNull()
+  })
+
+  it('sets soul to null when soulPath file does not exist', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    mockExistsSync.mockReturnValue(false)
+    const agents = await getAgents()
+    const jarvis = agents.find(a => a.id === 'jarvis')!
+    expect(jarvis.soulPath).toBeTruthy()
+    expect(jarvis.soul).toBeNull()
+  })
+
+  it('reads soul content when soulPath file exists', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    mockExistsSync.mockImplementation((path: string) => {
+      // Only the SOUL file exists, not the workspace override
+      if (path === '/tmp/ws/clawport/agents.json') return false
+      return true
+    })
+    mockReadFileSync.mockReturnValue('# Jarvis SOUL')
+    const agents = await getAgents()
+    const jarvis = agents.find(a => a.id === 'jarvis')!
+    expect(jarvis.soul).toBe('# Jarvis SOUL')
+  })
+
+  it('sets soul to null when readFileSync throws', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    mockExistsSync.mockImplementation((path: string) => {
+      if (path === '/tmp/ws/clawport/agents.json') return false
+      return true
+    })
+    mockReadFileSync.mockImplementation(() => { throw new Error('EACCES') })
+    const agents = await getAgents()
+    const jarvis = agents.find(a => a.id === 'jarvis')!
+    expect(jarvis.soul).toBeNull()
+  })
+
+  it('initializes crons as empty array for every agent', async () => {
+    const agents = await getAgents()
+    for (const agent of agents) {
+      expect(agent.crons).toEqual([])
+    }
+  })
+
+  it('agents with no soulPath get soul=null without reading fs', async () => {
+    vi.stubEnv('WORKSPACE_PATH', '/tmp/ws')
+    mockExistsSync.mockReturnValue(false)
+    const agents = await getAgents()
+    const scout = agents.find(a => a.id === 'scout')!
+    expect(scout.soulPath).toBeNull()
+    expect(scout.soul).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getAgent
+// ---------------------------------------------------------------------------
+
+describe('getAgent', () => {
+  it('returns the correct agent by id', async () => {
+    const agent = await getAgent('vera')
+    expect(agent).not.toBeNull()
+    expect(agent!.id).toBe('vera')
+    expect(agent!.name).toBe('VERA')
+    expect(agent!.title).toBe('Chief Strategy Officer')
+  })
+
+  it('returns null for an unknown id', async () => {
+    const agent = await getAgent('nonexistent-agent')
+    expect(agent).toBeNull()
+  })
+
+  it('returns null for empty string', async () => {
+    const agent = await getAgent('')
+    expect(agent).toBeNull()
+  })
+
+  it('is case-sensitive (uppercase id returns null)', async () => {
+    const agent = await getAgent('VERA')
+    expect(agent).toBeNull()
+  })
+
+  it('returns agent with correct directReports', async () => {
+    const jarvis = await getAgent('jarvis')
+    expect(jarvis).not.toBeNull()
+    expect(jarvis!.directReports).toContain('vera')
+    expect(jarvis!.directReports).toContain('lumen')
+    expect(jarvis!.directReports).toContain('pulse')
+  })
+
+  it('returns agent with correct reportsTo chain', async () => {
+    const robin = await getAgent('robin')
+    expect(robin).not.toBeNull()
+    expect(robin!.reportsTo).toBe('vera')
+
+    const vera = await getAgent('vera')
+    expect(vera!.reportsTo).toBe('jarvis')
+
+    const jarvis = await getAgent('jarvis')
+    expect(jarvis!.reportsTo).toBeNull()
+  })
+})