@mcp-b/embedded-agent 0.0.4 → 0.0.5

package/README.md

@@ -1,29 +1,330 @@
-# react-compiler-components-starter
+# @mcp-b/embedded-agent
 
-A starter for creating a React component library with React Compiler.
+React components for embedding an AI agent UI with MCP (Model Context Protocol) tool support and voice mode.
 
-## Development
+## Architecture Overview
 
-- Install dependencies:
+The package follows a **core/widgets** architecture:
+
+- **Core** (`src/core/`): Data layer - providers and hooks, no UI
+- **Widgets** (`src/widgets/`): UI layer - independent components that consume core
 
-```bash
-npm install
+```
+src/
+├── core/                 # DATA LAYER
+│   ├── providers/
+│   │   ├── AgentProvider.tsx    # Unified provider (START HERE)
+│   │   └── index.ts
+│   ├── hooks/
+│   │   ├── useAgent.ts          # Main facade hook (START HERE)
+│   │   └── index.ts
+│   └── index.ts
+│
+├── widgets/              # UI LAYER
+│   ├── pill/                    # Compact floating UI
+│   │   └── index.ts             # Exports AgentPill, PillContainer, etc.
+│   ├── modal/                   # Full chat modal
+│   │   └── index.ts             # Exports AssistantModal, Thread, etc.
+│   ├── shared/                  # Shared components
+│   │   └── index.ts             # Exports ActionList, SummaryBlock, etc.
+│   └── index.ts
+│
+├── components/           # IMPLEMENTATION (internal)
+│   ├── pill/                    # Pill component implementations
+│   │   ├── AgentPill.tsx        # Main pill component
+│   │   ├── PillContainer.tsx    # Morphing container
+│   │   ├── PillVoice.tsx        # Voice mode UI
+│   │   ├── ActionList.tsx       # Action display
+│   │   └── ...
+│   └── ...                      # Other component implementations
+│
+├── hooks/                # INDIVIDUAL HOOKS (internal)
+│   ├── useActions.ts            # Derives actions from tool calls
+│   ├── useVoiceActions.ts       # Voice mode action tracking
+│   ├── useVoiceSummary.ts       # Voice session summary
+│   ├── useVoiceMode.ts          # Voice mode state machine
+│   └── ...
+│
+├── providers/            # INDIVIDUAL PROVIDERS (internal)
+│   ├── MCPToolsProvider.tsx     # MCP tool registry
+│   ├── VoiceModeProvider.tsx    # Voice mode context
+│   └── VoiceMCPBridge.tsx       # Connects MCP tools to voice
+│
+├── services/             # EXTERNAL SERVICES
+│   └── realtime/                # OpenAI Realtime API via WebRTC
+│       ├── openai-realtime-service.ts
+│       ├── webrtc-manager.ts
+│       └── ...
+│
+├── lib/                  # UTILITIES
+│   ├── constants.ts             # Magic numbers live here
+│   ├── utils.ts                 # cn(), etc.
+│   └── ...
+│
+└── index.ts              # PUBLIC EXPORTS
 ```
 
-- Run the playground:
+## Quick Start
 
-```bash
-npm run play
+### Recommended: AgentProvider + Widget
+
+```tsx
+import { AgentPill, AgentProvider } from '@mcp-b/embedded-agent'
+
+function App() {
+	return (
+		<AgentProvider apiBase="https://your-worker.workers.dev">
+			<AgentPill position="bottom-center" showVoiceButton />
+		</AgentProvider>
+	)
+}
 ```
 
-- Run the unit tests:
+### Custom UI with useAgent
 
-```bash
-npm run test
+```tsx
+import { AgentProvider, useAgent } from '@mcp-b/embedded-agent'
+
+function CustomUI() {
+	const agent = useAgent()
+
+	return (
+		<div>
+			{agent.isRunning && <p>Processing...</p>}
+			{agent.activeActions.map((action) => (
+				<div key={action.id}>{action.label}</div>
+			))}
+			{agent.voice?.isActive && <button onClick={agent.voice.stop}>End Voice</button>}
+		</div>
+	)
+}
+
+function App() {
+	return (
+		<AgentProvider apiBase="https://...">
+			<CustomUI />
+		</AgentProvider>
+	)
+}
+```
+
+## Core API
+
+### AgentProvider
+
+**File:** `src/core/providers/AgentProvider.tsx`
+
+Unified provider that sets up:
+
+- MCP tool registry (`MCPToolsProvider`)
+- Voice mode bridge (`VoiceMCPBridge`)
+- Chat runtime (`AssistantRuntimeProvider` from @assistant-ui/react)
+
+```tsx
+interface AgentProviderProps {
+	children: ReactNode
+	apiBase?: string // Backend URL
+	tokenEndpoint?: string // Voice token endpoint (defaults to {apiBase}/api/realtime/session)
+	autoConnectLocal?: boolean // Auto-connect to local MCP source (default: true)
+	onToolsChange?: (tools: ToolWithSource[]) => void
+	onVoiceError?: (error: string) => void
+	onVoiceConnect?: () => void
+	onVoiceDisconnect?: (duration: number) => void
+}
+```
+
+### useAgent Hook
+
+**File:** `src/core/hooks/useAgent.ts`
+
+Main facade hook - combines all agent capabilities into one interface.
+
+```tsx
+interface AgentState {
+	// Thread
+	messages: ReadonlyArray<ThreadMessage>
+	isRunning: boolean
+	hasMessages: boolean
+
+	// Actions (from tool calls)
+	actions: Action[] // All text mode actions
+	currentAction: Action | null // Currently running
+	recentActions: Action[] // Last 3 completed
+
+	// Voice mode actions
+	voiceActions: Action[] // Actions from voice mode
+	activeActions: Action[] // Voice or text depending on mode
+
+	// Summary
+	summary: string | null // Latest summary text
+	voiceSummary: VoiceSummary | null
+
+	// Voice controls (null if not configured)
+	voice: {
+		isActive: boolean
+		isConnecting: boolean
+		isError: boolean
+		isMuted: boolean
+		error?: string
+		audioLevel?: AudioLevelData
+		transcript?: TranscriptData
+		start: () => Promise<void>
+		stop: () => void
+		toggleMute: (muted?: boolean) => void
+		sendMessage: (text: string) => void
+	} | null
+
+	// MCP tools (null if not in context)
+	tools: {
+		list: ToolWithSource[]
+		call: (name: string, args: Record<string, unknown>) => Promise<CallToolResult>
+	} | null
+
+	// Derived
+	isVoiceActive: boolean
+}
+```
+
+## Widgets
+
+### AgentPill
+
+**File:** `src/components/pill/AgentPill.tsx`
+
+Compact, morphing floating UI. Shows actions, voice mode, and composer.
+
+```tsx
+interface AgentPillProps {
+	position?: 'bottom-center' | 'bottom-right'
+	onOpenHistory?: () => void
+	showVoiceButton?: boolean
+	autoCollapse?: boolean // Auto-collapse after 30s inactivity
+	className?: string
+}
+```
+
+### AssistantModal
+
+**File:** `src/components/assistant-modal.tsx`
+
+Traditional chat modal with full message thread.
+
+```tsx
+// No props - uses context from AgentProvider
+<AssistantModal />
 ```
 
-- Build the library:
+## Key Implementation Details
+
+### Action Tracking
+
+**Files:** `src/hooks/useActions.ts`, `src/hooks/useVoiceActions.ts`
+
+Actions are derived from tool calls in assistant messages. The `useActions` hook:
+
+1. Subscribes to thread messages via `useThread`
+2. Extracts tool calls from assistant messages
+3. Maps tool calls to Action objects with status (running/success/error)
+
+Voice actions work similarly but track tool calls from the realtime voice API.
+
+### Voice Mode
+
+**Files:**
+
+- `src/hooks/useVoiceMode.ts` - State machine for voice sessions
+- `src/services/realtime/` - OpenAI Realtime API integration
+- `src/providers/VoiceMCPBridge.tsx` - Connects MCP tools to voice mode
+
+Voice mode uses WebRTC to connect to OpenAI's Realtime API. The VoiceMCPBridge:
+
+1. Watches MCP tools from MCPToolsProvider
+2. Converts them to RegisteredTool format
+3. Provides tool executor that calls through MCP
+
+### MCP Tools
+
+**File:** `src/providers/MCPToolsProvider.tsx`
+
+Manages MCP tool sources (local tab, remote servers). Key exports:
+
+- `useMCPTools()` - Required context hook
+- `useOptionalMCPTools()` - Returns null if not in provider
+
+### Constants
+
+**File:** `src/lib/constants.ts`
+
+All magic numbers are centralized here:
+
+- `VOICE_ACTIONS_RETENTION_MS` (3000ms) - How long voice actions persist
+- `VOICE_SUMMARY_RETENTION_MS` (30000ms) - How long voice summary persists
+- `TOOL_CALL_DISPLAY_DURATION_MS` (2000ms) - Tool status display time
+- etc.
+
+## Legacy API
+
+The `EmbeddedAgent` component is preserved for backward compatibility but wraps the new architecture internally.
+
+```tsx
+// Legacy (still works)
+import { EmbeddedAgent } from '@mcp-b/embedded-agent'
+
+<EmbeddedAgent
+  appId="your-app"
+  apiBase="https://..."
+  viewMode="pill"
+/>
+
+// New (recommended)
+import { AgentProvider, AgentPill } from '@mcp-b/embedded-agent'
+
+<AgentProvider apiBase="https://...">
+  <AgentPill />
+</AgentProvider>
+```
+
+## Development
 
 ```bash
-npm run build
+# Build
+pnpm build
+
+# Type check
+pnpm check:types
+
+# Lint
+pnpm check:lint
+
+# Test
+pnpm test
+
+# Run playground
+pnpm play
 ```
+
+## Exports Reference
+
+### From `@mcp-b/embedded-agent`
+
+**Core:**
+
+- `AgentProvider`, `AgentProviderProps`
+- `useAgent`, `AgentState`, `AgentVoice`, `AgentTools`
+- `useActions`, `useCurrentAction`, `useRecentActions`, `Action`
+- `useVoiceActions`, `useVoiceSummary`, `VoiceSummary`
+- `useMCPTools`, `useOptionalMCPTools`, `MCPToolsContextValue`
+
+**Widgets:**
+
+- `AgentPill`, `AgentPillProps`, `PillPosition`
+- `AssistantModal`
+- `ActionList`, `SummaryBlock`, `CurrentActivity`
+- `PillContainer`, `PillComposer`, `PillVoice`
+- `LiveWaveform`, `VoiceIndicator`, `ToolStatusBorder`
+
+**Legacy:**
+
+- `EmbeddedAgent`, `EmbeddedAgentProps`
+
+See `src/index.ts` for the complete export list.