intent-hub 0.1.0

package/README.md

@@ -0,0 +1,661 @@
+# Intent Hub
+
+**Team-based LLM Coordination Platform with Semantic Conflict Resolution**
+
+> When multiple developers use AI coding agents simultaneously, code conflicts happen. Intent Hub solves this by coordinating LLM agents at the **semantic level** - before conflicts occur.
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║   ██╗███╗   ██╗████████╗███████╗███╗   ██╗████████╗           ║
+║   ██║████╗  ██║╚══██╔══╝██╔════╝████╗  ██║╚══██╔══╝           ║
+║   ██║██╔██╗ ██║   ██║   █████╗  ██╔██╗ ██║   ██║              ║
+║   ██║██║╚██╗██║   ██║   ██╔══╝  ██║╚██╗██║   ██║              ║
+║   ██║██║ ╚████║   ██║   ███████╗██║ ╚████║   ██║              ║
+║   ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝  ╚═══╝   ╚═╝              ║
+║                         HUB                                   ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+[English](README.md) | [한국어](README_ko.md)
+
+---
+
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [The Solution](#the-solution)
+- [Quick Start](#quick-start)
+- [Installation Guide for LLM Agents](#installation-guide-for-llm-agents)
+- [Team Collaboration Guide](#team-collaboration-guide)
+- [Integration](#integration)
+- [How It Works](#how-it-works)
+- [Configuration](#configuration)
+
+---
+
+## The Problem
+
+In modern teams using AI coding assistants (Cursor, GitHub Copilot, OpenCode, etc.):
+
+- **Alice** asks her AI to "implement OAuth login"
+- **Bob** asks his AI to "add session management"  
+- Both AIs modify `src/auth/*` simultaneously
+- **Result**: Merge conflicts, lost work, frustration
+
+Traditional file-level locks don't work because:
+1. AI agents don't know about each other
+2. Semantic overlap isn't always file-based
+3. "auth" and "session" might not touch the same files but are conceptually related
+
+## The Solution
+
+Intent Hub introduces **Semantic Locks** - locking at the domain level (`auth`, `payment`, `user`) rather than file level.
+
+```
+┌─────────────┐     WebSocket      ┌─────────────┐
+│  Alice's    │◄──────────────────►│             │
+│  AI Agent   │                    │   Intent    │
+├─────────────┤                    │    Hub      │
+│  Bob's      │◄──────────────────►│   Server    │
+│  AI Agent   │                    │             │
+├─────────────┤                    │  (Central   │
+│  Carol's    │◄──────────────────►│   Coord)    │
+│  AI Agent   │                    │             │
+└─────────────┘                    └─────────────┘
+```
+
+### Key Features
+
+- **Smart Intent Analysis**: LLM-powered understanding of what each developer intends to do
+- **Semantic Domain Locking**: Lock conceptual areas, not just files
+- **LLM Negotiation**: When conflicts occur, AI agents can negotiate solutions
+- **Auto-Resolution**: Compatible changes proceed automatically
+- **Human Escalation**: Incompatible changes prompt developers for decisions
+
+## Quick Start
+
+### 🚀 Live Share Mode (Recommended for Teams)
+
+**Like VS Code Live Share** - one person hosts, others join with a link. No network setup needed!
+
+```bash
+# 1. Install
+git clone https://github.com/your-org/intent-hub.git && cd intent-hub
+bun install && bun run build
+
+# 2. Start with Live Share mode
+bun run packages/hub/dist/cli.js --share --llm=openai
+
+# Output:
+# ╔═══════════════════════════════════════════════════════════════╗
+# ║                    🔗 SHARE YOUR SESSION                      ║
+# ╠═══════════════════════════════════════════════════════════════╣
+# ║  Team members can connect using:                              ║
+# ║  wss://intent-hub-a1b2c3d4.loca.lt                            ║
+# ╚═══════════════════════════════════════════════════════════════╝
+
+# 3. Share the URL with your team!
+```
+
+That's it! Team members connect to the shared URL - no firewall/NAT configuration needed.
+
+---
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) v1.1.0 or later
+- Node.js 20+ (for compatibility)
+
+### Installation
+
+```bash
+git clone https://github.com/your-org/intent-hub.git
+cd intent-hub
+bun install
+bun run build
+```
+
+### Start the Hub Server
+
+```bash
+# 🌐 Live Share mode (for remote teams)
+bun run packages/hub/dist/cli.js --share
+
+# 🏠 Local mode (same network only)
+bun run packages/hub/dist/cli.js
+
+# With OpenAI
+OPENAI_API_KEY=sk-xxx bun run packages/hub/dist/cli.js --share --llm=openai
+
+# With Anthropic
+ANTHROPIC_API_KEY=sk-ant-xxx bun run packages/hub/dist/cli.js --llm=anthropic
+```
+
+### Server Options
+
+```
+Usage:
+  intent-hub [options]
+
+Options:
+  --port=<number>           Port to listen on (default: 9876)
+  --host=<string>           Host to bind to (default: 0.0.0.0)
+  --mode=<mode>             Server mode: simple | smart (default: smart)
+  --llm=<provider>          LLM provider: openai | anthropic | mock (default: mock)
+  --api-key=<key>           API key for LLM provider (or use env vars)
+  --no-negotiate            Disable auto-negotiation
+  --dashboard               Enable web dashboard
+  --share                   Enable Live Share mode (public URL, no network setup)
+  --tunnel=<provider>       Tunnel: auto | localtunnel | cloudflared (default: auto)
+  --help                    Show help message
+
+Environment Variables:
+  OPENAI_API_KEY       OpenAI API key
+  ANTHROPIC_API_KEY    Anthropic API key
+```
+
+---
+
+## Installation Guide for LLM Agents
+
+> This section is a reference guide for AI coding agents (Claude Code, OpenCode, Cursor, etc.) when installing Intent Hub.
+
+### Quick Install (npx)
+
+**Just one command to start a shared session:**
+
+```bash
+# Start Intent Hub with Live Share (recommended)
+npx intent-hub --share
+
+# With OpenAI for smart analysis
+OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai
+```
+
+That's it! Share the outputted URL with your team.
+
+---
+
+### Step 0: Check Environment with User
+
+Ask the user:
+- **LLM provider**: OpenAI API key? Anthropic API key? Or just test with mock?
+
+### Step 1: Start Hub Server
+
+**Option A: npx (Recommended - No installation needed):**
+```bash
+# Quick start with Live Share
+npx intent-hub --share
+
+# With OpenAI
+OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai
+
+# With Anthropic  
+ANTHROPIC_API_KEY=sk-ant-xxx npx intent-hub --share --llm=anthropic
+```
+
+**Option B: Global install:**
+```bash
+npm install -g intent-hub
+intent-hub --share --llm=openai
+```
+
+**Option C: From source:**
+```bash
+git clone https://github.com/anthropic-for-korea/intent-hub.git
+cd intent-hub && bun install && bun run build
+bun run packages/hub/dist/cli.js --share
+```
+
+### Step 2: Share the URL
+
+When server starts with `--share`, it outputs:
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    🔗 SHARE YOUR SESSION                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Team members can connect using:                              ║
+║  wss://intent-hub-a1b2c3d4.loca.lt                            ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Copy and share this URL with your team!
+
+### Step 3: Connect Agent Client
+
+Each team member's AI agent connects using:
+
+```typescript
+import { HubClient } from '@anthropic-for-korea/intent-hub-agent';
+
+const client = new HubClient({
+  hubUrl: 'wss://intent-hub-a1b2c3d4.loca.lt',  // Shared URL
+  userId: 'unique-user-id',
+  username: 'Username',
+  projectPath: '/path/to/project',
+});
+
+client.connect();
+```
+
+### Troubleshooting
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| Connection failed | Server not running | Run `npx intent-hub --share` |
+| Tunnel error | Network issue | Try `--tunnel=cloudflared` if you have cloudflared installed |
+| LLM error | No API key | Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` env var |
+
+---
+
+## Team Collaboration Guide
+
+### Using Intent Hub as a Team
+
+Intent Hub delivers its true value when the entire team uses it together.
+
+#### Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        Team Server                           │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │              Intent Hub Server                         │  │
+│  │              (ws://team-server:9876)                   │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ WebSocket
+          ┌───────────────────┼───────────────────┐
+          │                   │                   │
+          ▼                   ▼                   ▼
+    ┌──────────┐       ┌──────────┐       ┌──────────┐
+    │ Dev A    │       │ Dev B    │       │ Dev C    │
+    │ Claude   │       │ OpenCode │       │ Cursor   │
+    │ Code     │       │          │       │          │
+    └──────────┘       └──────────┘       └──────────┘
+```
+
+#### Setup Method
+
+**1. Run Hub on Team Server:**
+
+```bash
+# Run in background on team server
+nohup bun run packages/hub/dist/cli.js \
+  --llm=openai \
+  --dashboard \
+  --host=0.0.0.0 \
+  > intent-hub.log 2>&1 &
+```
+
+**2. Configure Each Developer's AI Agent:**
+
+Developers can simply ask their AI agent (Claude Code, OpenCode, Cursor, etc.):
+
+> "Connect to Intent Hub. The hub server address is ws://team-server:9876, and my name is [username]."
+
+Or add to project config file:
+
+```json
+// .intent-hub.json (create in project root)
+{
+  "hubUrl": "ws://team-server:9876",
+  "autoConnect": true
+}
+```
+
+#### How to Request Installation via LLM
+
+Tell your team members:
+
+> **"Tell your Claude Code / OpenCode / Cursor this:"**
+> 
+> "Install Intent Hub client and connect to ws://team-server:9876.
+> My userId is 'my-unique-id' and name is 'John Doe'.
+> GitHub: https://github.com/your-org/intent-hub"
+
+The AI agent will automatically:
+1. Install required packages
+2. Create config files
+3. Connect to hub server
+4. Run tests
+
+#### Collaboration Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Collaboration Scenario                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Alice: "Implement OAuth login"                              │
+│     └─> Intent Hub: Lock acquired for auth/oauth ✓              │
+│                                                                 │
+│  2. Bob: "Add session management"                               │
+│     └─> Intent Hub: Conflict detected in auth domain!           │
+│         └─> Notify Bob's AI: "Alice is working on auth.         │
+│             Please work on something else or wait."             │
+│                                                                 │
+│  3. Carol: "Refactor payment system"                            │
+│     └─> Intent Hub: Lock acquired for payment ✓                 │
+│         (Unrelated to auth, can proceed simultaneously)         │
+│                                                                 │
+│  4. Alice completes work                                        │
+│     └─> Intent Hub: Release auth/oauth lock                     │
+│         └─> Notify Bob's AI: "auth is now available"            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### Recommended Setup by Team Size
+
+| Team Size | Server Location | LLM Setting | Notes |
+|-----------|----------------|-------------|-------|
+| 1-3 | Local (one developer) | Mock or OpenAI | Simple setup |
+| 4-10 | Dedicated team server | OpenAI or Anthropic | Stable connection needed |
+| 10+ | Cloud (AWS/GCP) | OpenAI + HA | Production-level |
+
+---
+
+## Integration
+
+### With OpenCode (Hooks)
+
+```typescript
+import { createIntentHubHooks } from '@intent-hub/agent';
+
+const hooks = createIntentHubHooks({
+  hubUrl: 'ws://localhost:9876',
+  userId: 'alice',
+  username: 'Alice',
+  projectPath: '/path/to/project',
+  onNotification: (event, data) => {
+    console.log(`[IntentHub] ${event}:`, data);
+  },
+});
+
+// In your AI agent's tool hooks:
+// Pre-tool hook - check if action is allowed
+const result = await hooks.preToolUse({
+  toolName: 'edit',
+  toolInput: { filePath: 'src/auth/login.ts', content: '...' },
+  sessionId: 'session-123',
+  userId: 'alice',
+  username: 'Alice',
+});
+
+if (!result.allow) {
+  console.log(result.message); // Domain locked by another user
+}
+
+// When user submits a prompt
+const promptResult = await hooks.onUserPromptSubmit('Add OAuth login with Google');
+if (promptResult.message) {
+  console.log(promptResult.message); // Warning about locked domains
+}
+```
+
+### Programmatic Usage
+
+```typescript
+import { HubClient } from '@intent-hub/agent';
+
+const client = new HubClient({
+  hubUrl: 'ws://localhost:9876',
+  userId: 'alice',
+  username: 'Alice',
+  projectPath: '/path/to/project',
+  onConnected: (sessionId) => {
+    console.log('Connected:', sessionId);
+  },
+  onMessage: (message) => {
+    switch (message.type) {
+      case 'hub:lock:acquired':
+        console.log('Lock acquired for domains:', message.payload.domains);
+        break;
+      case 'hub:lock:blocked':
+        console.log('Blocked by:', message.payload.blockedBy);
+        break;
+      case 'hub:negotiation:start':
+        console.log('Negotiation started with:', message.payload.participants);
+        break;
+      case 'hub:decision:required':
+        console.log('Decision needed:', message.payload.question);
+        break;
+    }
+  },
+});
+
+client.connect();
+
+// Submit intent when user gives a prompt
+client.submitIntent('Implement Google OAuth login');
+```
+
+## Architecture
+
+```
+intent-hub/
+├── packages/
+│   ├── shared/              # Shared types & utilities
+│   │   └── src/
+│   │       ├── types/       # Intent, Domain, Message types
+│   │       └── utils/       # ID generation, message helpers
+│   │
+│   ├── hub/                 # Central Hub Server
+│   │   └── src/
+│   │       ├── server/      # WebSocket server
+│   │       ├── core/        # Lock manager, conflict detector, orchestrator
+│   │       ├── llm/         # LLM provider, analyzer, negotiation engine
+│   │       └── state/       # Session management
+│   │
+│   └── agent/               # Client-side Agent Library
+│       └── src/
+│           ├── connection/  # Hub client
+│           ├── plugin/      # Plugin interface
+│           └── hooks/       # OpenCode hooks
+│
+├── scripts/
+│   ├── test-e2e.ts         # End-to-end tests
+│   └── test-mvp2.ts        # LLM negotiation tests
+│
+└── turbo.json              # Turborepo config
+```
+
+## How It Works
+
+### 1. Intent Submission
+
+When a developer gives their AI a task:
+```
+User: "Add Google OAuth login"
+```
+
+The agent submits this intent to Intent Hub:
+```typescript
+client.submitIntent('Add Google OAuth login');
+```
+
+### 2. Smart Analysis
+
+Intent Hub analyzes the intent using LLM:
+```json
+{
+  "domain": "auth",
+  "subdomain": "oauth",
+  "affectedFiles": ["src/auth/oauth.ts", "src/auth/providers/google.ts"],
+  "semanticTags": ["login", "oauth", "google", "authentication"],
+  "estimatedScope": "medium"
+}
+```
+
+### 3. Conflict Detection
+
+The system checks for semantic conflicts:
+
+| Scenario | Result |
+|----------|--------|
+| No overlap | **Approved** - proceed immediately |
+| Same domain, different subdomain | **Warning** - may proceed with caution |
+| Same domain, same subdomain | **Blocked** or **Negotiation** |
+
+### 4. Resolution
+
+**Auto-Approved:**
+```
+Alice: auth/oauth  ✓
+Carol: payment     ✓  (different domain)
+```
+
+**Blocked:**
+```
+Alice: auth/oauth  ✓
+Bob: auth/session  ⚠️  (same domain - blocked until Alice finishes)
+```
+
+**Negotiation (when enabled):**
+```
+Alice: auth/oauth
+Bob: auth/session
+→ LLMs discuss and propose: "Alice works on OAuth first, Bob does session after"
+→ Both users notified of the plan
+```
+
+## Message Protocol
+
+### Agent → Hub
+
+| Message | Description |
+|---------|-------------|
+| `agent:connect` | Initial connection with user info |
+| `agent:intent:submit` | Submit a new intent (user prompt) |
+| `agent:decision` | User's decision on a conflict |
+
+### Hub → Agent
+
+| Message | Description |
+|---------|-------------|
+| `hub:connected` | Connection confirmed with session ID |
+| `hub:intent:received` | Intent acknowledged |
+| `hub:intent:analyzed` | Analysis complete with domain info |
+| `hub:lock:acquired` | Lock granted, proceed with work |
+| `hub:lock:blocked` | Lock denied, wait or work elsewhere |
+| `hub:negotiation:start` | Negotiation started with another user |
+| `hub:negotiation:resolved` | Negotiation complete with plan |
+| `hub:decision:required` | User input needed |
+
+### Broadcasts
+
+| Message | Description |
+|---------|-------------|
+| `broadcast:user:joined` | New user connected |
+| `broadcast:user:left` | User disconnected |
+| `broadcast:lock:update` | Lock status changed |
+
+## Development
+
+### Build
+
+```bash
+bun install
+bun run build
+```
+
+### Development Mode
+
+```bash
+# Watch mode for hub
+bun run dev:hub
+
+# Watch mode for agent
+bun run dev:agent
+```
+
+### Run Tests
+
+```bash
+# E2E test (basic flow)
+bun run scripts/test-e2e.ts
+
+# MVP2 test (LLM negotiation)
+bun run scripts/test-mvp2.ts
+```
+
+### Type Check
+
+```bash
+bun run typecheck
+```
+
+## Configuration
+
+### Hub Server Configuration
+
+```typescript
+interface SmartHubServerOptions {
+  port: number;                    // WebSocket port
+  host?: string;                   // Bind address (default: 0.0.0.0)
+  llmProvider: LLMProvider;        // OpenAI, Anthropic, or Mock
+  orchestratorConfig?: {
+    useLLMAnalysis?: boolean;      // Use LLM for intent analysis
+    autoNegotiate?: boolean;       // Auto-negotiate conflicts
+    conflictThreshold?: 'low' | 'medium' | 'high';
+  };
+}
+```
+
+### Agent Configuration
+
+```typescript
+interface IntentHubHooksConfig {
+  hubUrl: string;                  // WebSocket URL to hub
+  userId: string;                  // Unique user identifier
+  username: string;                // Display name
+  projectPath: string;             // Project root path
+  autoConnect?: boolean;           // Connect on creation (default: true)
+  onNotification?: (event: string, data: unknown) => void;
+}
+```
+
+## Semantic Domains
+
+Intent Hub automatically categorizes work into semantic domains:
+
+| Domain | Triggers |
+|--------|----------|
+| `auth` | `/auth/`, `login`, `oauth`, `session`, `jwt` |
+| `user` | `/user/`, `profile`, `account` |
+| `payment` | `/payment/`, `checkout`, `stripe`, `billing` |
+| `api` | `/api/`, `route`, `endpoint` |
+| `ui` | `.tsx`, `.jsx`, `/component` |
+| `database` | `/db/`, `migration`, `schema` |
+| `config` | `config`, `.env` |
+| `test` | `.test.`, `.spec.`, `/test/` |
+
+Custom domains can be configured based on your project structure.
+
+## Roadmap
+
+- [x] **MVP 1**: Basic domain locking
+- [x] **MVP 2**: LLM-powered intent analysis & negotiation
+- [x] **MVP 3**: OpenCode integration hooks
+- [ ] **MVP 4**: Web dashboard for team visibility
+- [ ] **MVP 5**: History & analytics
+- [ ] **MVP 6**: VS Code extension
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+Built with love by the Intent Hub team. Because AI collaboration should be as smooth as human collaboration (or better).