clew-code 0.2.1

package/docs/PLAN.md

@@ -0,0 +1,304 @@
+# Multi-Agent Chat System — PLAN.md
+
+## สถานะปัจจุบัน (Current Status)
+
+### ทำเสร็จแล้ว ✅
+
+| # | Component | Status | File |
+|---|-----------|--------|------|
+| 1 | IPC `inject` type ใน supervisor | ✅ เสร็จ | `src/services/Supervisor/supervisor.ts` |
+| 2 | `handleInject()` handler | ✅ เสร็จ | `src/services/Supervisor/supervisor.ts` |
+| 3 | Session input pipe helper | ✅ เสร็จ | `src/services/Supervisor/supervisor.ts` |
+| 4 | Spawn ด้วย stdin pipe (ไม่ ignore) | ✅ เสร็จ | `src/services/Supervisor/supervisor.ts` |
+| 5 | `injectMessage()` ใน ipcClient | ✅ เสร็จ | `src/services/Supervisor/ipcClient.ts` |
+| 6 | Chat CLI command | ✅ เสร็จ | `src/commands/chat.tsx` |
+| 7 | TUI Chat Input | ✅ เสร็จ | `src/commands/chat.tsx` |
+| 8 | `/team` command - ดู sessions พร้อมบทบาท | ✅ เสร็จ | `src/commands/team.tsx` |
+| 9 | `/send` command - ส่งข้อความระหว่าง session | ✅ เสร็จ | `src/commands/send.tsx` |
+| 10 | Register commands ใน commands.ts | ✅ เสร็จ | `src/commands.ts` |
+| 11 | CLI argument parsing ใน main.tsx | ✅ เสร็จ | `src/main.tsx` |
+
+### ยังไม่ได้ทำ ❌
+
+| # | Component | Status | File |
+|---|-----------|--------|------|
+| 12 | Test end-to-end | ❌ | — |
+| 13 | Auto-forward messages จาก worker ไป lead | ❌ | — |
+
+---
+
+## Multi-Agent Chat Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Multi-Agent Chat System                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   Lead Session                         Worker Sessions           │
+│   ┌─────────────┐                    ┌─────────────┐           │
+│   │  /team      │ ◄──────inject─────▶│  Worker 1   │           │
+│   │  /send      │                    │  (code)     │           │
+│   │  (coordinator)│                   └─────────────┘           │
+│   └──────┬──────┘                    ┌─────────────┐           │
+│          │                           │  Worker 2   │           │
+│          │                           │  (test)     │           │
+│          │                           └─────────────┘           │
+│          │                           ┌─────────────┐           │
+│          └──────────inject──────────▶│  Worker 3   │           │
+│                                      │  (review)   │           │
+│                                      └─────────────┘           │
+│                                                                  │
+│   Communication: IPC inject messages via Supervisor              │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Commands
+
+### `/team` - ดู Sessions และกำหนดบทบาท
+
+```bash
+# ดู sessions ทั้งหมดพร้อมบทบาท
+/team
+
+# กำหนดบทบาท
+/team role <sessionId> lead     # ตั้งเป็น lead
+/team role <sessionId> worker   # ตั้งเป็น worker
+/team role <sessionId> idle     # ลบบทบาท
+```
+
+**Output ตัวอย่าง:**
+```
+📋 Running Sessions:
+
+👑 Leaders:
+  abc12345  Main Session  [running]
+
+⚙️  Workers:
+  def67890  Code Writer   [running]
+  ghi23456  Test Runner   [running]
+
+💤 Idle:
+  jkl78901  Reviewer      [stopped]
+```
+
+---
+
+### `/send` - ส่งข้อความระหว่าง Session
+
+```bash
+# ส่งไปยัง session เฉพาะ
+/send <sessionId> "ข้อความที่ต้องการ"
+
+# ส่งไปยัง lead session ทั้งหมด
+/send lead "งานเสร็จแล้ว"
+
+# ส่งไปยัง worker session ทั้งหมด
+/send worker "กรุณาตรวจสอบโค้ด"
+
+# Broadcast ไปยังทุก session
+/send all "ประชุมใน 5 นาที"
+```
+
+---
+
+## IPC Protocol
+
+### Request Type: `inject`
+
+```json
+{
+  "type": "inject",
+  "sessionId": "abc12345",
+  "prompt": "What is the current status?"
+}
+```
+
+### Response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "sessionId": "abc12345",
+    "injected": "What is the current status?",
+    "timestamp": 1717000000000
+  }
+}
+```
+
+---
+
+## Named Pipe Per Session
+
+### Windows
+```
+\\.\pipe\claude-session-input-{sessionId}
+```
+
+### Unix
+```
+/tmp/claude-session-input-{sessionId}.sock
+```
+
+### Behavior
+- สร้างเมื่อ session เริ่มทำงาน (`spawnSessionProcess`)
+- ลบเมื่อ session หยุด (`child.on('exit')`)
+- Supervisor listens สำหรับ connection
+- Messages ที่เขียนไป pipe จะถูก forward ไปยัง session's stdin
+
+---
+
+## Session stdin Behavior
+
+**Before:** `stdio: ['ignore', 'pipe', 'pipe']`
+**After:**  `stdio: ['pipe', 'pipe', 'pipe']`
+
+อนุญาตให้ส่ง external input ไปยัง session process ผ่าน stdin
+
+---
+
+## Role System
+
+### Roles
+
+| Role | Description |
+|------|-------------|
+| `lead` | ผู้ประสานงาน - สั่งงานและดูแล worker |
+| `worker` | ผู้ทำงาน - รับคำสั่งจาก lead |
+| `idle` | ไม่มีบทบาทเฉพาะ |
+
+### Auto-forward (Future)
+
+Worker sessions สามารถ auto-forward messages ไปยัง lead session ได้:
+- เมื่อ worker ทำงานเสร็จ → ส่งรายงานไป lead
+- เมื่อ worker มีคำถาม → ส่งไป lead
+- เมื่อ worker พบปัญหา → ส่งไป lead
+
+Roles are persisted in `~/.claude/daemon/team-roles.json`, so role assignments survive separate CLI processes and can be used by `/send lead` or `/send worker` from any active session.
+
+---
+
+## วิธีใช้งาน
+
+### 1. เริ่ม Multi-Agent Session
+
+```bash
+# Terminal 1: Start lead session
+bun run src/main.tsx
+
+# Terminal 2: Start worker session 1
+bun run src/main.tsx --name "Code Writer"
+
+# Terminal 3: Start worker session 2
+bun run src/main.tsx --name "Test Runner"
+```
+
+### 2. กำหนดบทบาท
+
+```bash
+# ใน lead session
+/team role abc12345 lead
+/team role def67890 worker
+/team role ghi23456 worker
+```
+
+### 3. ส่งข้อความ
+
+```bash
+# Lead สั่งงาน worker
+/send def67890 "Please implement the user authentication module"
+
+# Worker รายงาน lead
+/send lead "I've completed the authentication module"
+
+# Broadcast ไปทุก session
+/send all "Meeting in 5 minutes"
+```
+
+หรือสั่งด้วยภาษาปกติใน TUI ได้โดยไม่ต้องใช้ slash command:
+
+```text
+lead ไปสั่งงาน session 3 ให้รัน test หน่อย
+บอก worker ทุกตัวให้ review diff
+ตั้ง abc12345 เป็น lead
+โชว์ team sessions ทั้งหมด
+```
+
+โมเดลจะใช้ `MultiAgent` tool เพื่อ list sessions, assign role, หรือส่งข้อความให้ session เป้าหมายเอง
+
+### 4. ดูสถานะ
+
+```bash
+# ดู sessions ทั้งหมด
+/team
+```
+
+### 5. ใช้ผ่าน CLI โดยตรง
+
+```bash
+clew team
+clew team role abc12345 worker
+clew send worker "Please run the test suite"
+clew chat abc12345
+clew chat abc12345 "status update?"
+```
+
+---
+
+## Files Modified/Created
+
+### Modified ✅
+- `src/services/Supervisor/supervisor.ts` — Added `inject` IPC type, `handleInject()`, `setupSessionInputPipe()`, `forwardInputToSession()`, `cleanupSessionInputPipe()`, changed spawn to `['pipe', 'pipe', 'pipe']`
+- `src/services/Supervisor/ipcClient.ts` — Added `injectMessage()` function
+- `src/commands.ts` — Added imports and registered `team`, `send`, `chat` commands
+- `src/main.tsx` — Added CLI parsing for `team`, `send`, and `chat` commands
+
+### Created ✅
+- `src/commands/chat.tsx` — Chat CLI command handler
+- `src/commands/team.tsx` — `/team` command for session management
+- `src/commands/send.tsx` — `/send` command for inter-session messaging
+- `src/tools/MultiAgentTool/MultiAgentTool.ts` — Model-callable natural-language team coordination tool
+- `docs/PLAN.md` — This file
+
+---
+
+## Validation Workflow
+
+### End-to-End Test
+
+```bash
+# Start supervisor daemon
+bun run src/main.tsx daemon start
+
+# Spawn background sessions
+bun run src/main.tsx --bg "Task 1"
+bun run src/main.tsx --bg "Task 2"
+
+# Open lead session
+bun run src/main.tsx
+
+# In lead session:
+/team                          # See all sessions
+/team role <id> worker         # Assign roles
+/send <id> "Do this task"     # Send commands
+```
+
+### Future: Auto-Forward
+
+Add auto-forward logic in session message handler:
+- When session receives response → check if it's a worker
+- If worker → forward summary to lead session
+- Use `injectMessage()` to send
+
+---
+
+## Notes
+
+- ใช้ IPC inject สำหรับส่งข้อความระหว่าง sessions
+- ไม่ต้องมี Web UI สำหรับ basic usage (ใช้ CLI commands ได้เลย)
+- Web UI เป็น optional สำหรับ visual overview
+- Role system persist ข้าม process ผ่าน `~/.claude/daemon/team-roles.json`
+- Auto-forward ยังเป็น future work

package/docs/_config.yml

@@ -0,0 +1,3 @@
+title: Claude Code Documentation
+description: Multi-provider AI CLI with extensible plugin architecture
+show_downloads: false

package/docs/architecture.html

@@ -0,0 +1,144 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Architecture — Clew</title>
+  <meta name="description" content="Runtime architecture, layered design, and data flow for Clew CLI.">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="css/styles.css">
+</head>
+<body>
+<header class="header"><div class="header-inner"><a href="index.html" class="logo"><span>Clew</span></a><nav class="header-nav"><a href="index.html">Home</a><a href="index.html#features">Features</a><a href="index.html#commands">Commands</a><a href="quick-start.html" class="active">Docs</a><a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a></nav><button class="menu-btn" id="menuToggle" aria-label="Toggle navigation"><span></span><span></span><span></span></button></div></header>
+<div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
+<div class="content-wrap"><main class="content">
+  <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Architecture</span></div>
+  <h1>Architecture</h1>
+  <p class="section-subtitle">Clew is a terminal-based AI coding assistant — a React/Ink TUI, Commander.js CLI, multi-provider AI engine, and extensible tool/plugin runtime all in one process.</p>
+
+  <h2>Layered Design</h2>
+  <p>The application is structured as four cooperative layers:</p>
+
+  <h3>1. Terminal UI (React 19 + Ink 6)</h3>
+  <p>Renders the interactive REPL: prompt input, streaming markdown output, status bar with context meter, arc spinner, permission dialogs, file explorer, inline images, buddy (duck) companion, and fullscreen mode. Components live in <code>src/components/</code>, state management in <code>src/state/</code>, and React context in <code>src/context/</code>.</p>
+
+  <h3>2. CLI &amp; Command Layer (Commander.js 13)</h3>
+  <p>Entry point at <code>src/main.tsx</code> — parses CLI flags (<code>--model</code>, <code>--print</code>, <code>--permission-mode</code>, <code>--mcp-config</code>, etc.), loads config, initializes providers and telemetry, then launches the REPL or print-mode query. Slash commands are registered in <code>src/commands.ts</code> and implemented under <code>src/commands/</code>. Commands are categorized as <code>local</code> (runs in-terminal), <code>prompt</code> (skills that expand to text), or <code>local-jsx</code> (Ink UI panels).</p>
+
+  <h3>3. AI Provider &amp; Adapter Layer</h3>
+  <p><strong>ProviderManager</strong> (<code>src/services/ai/ProviderManager.ts</code>) resolves API keys, selects models, and manages provider config. Provider metadata is declared in <code>src/services/ai/providers.json</code> — currently 27 providers with model listings, capabilities, base URLs, and env key mappings. Non-Anthropic providers are wrapped by the <strong>AnthropicAdapter</strong> or <strong>GoogleAdapter</strong>, which normalize content blocks (<code>contentBlockUtils.ts</code>), tool calls (<code>toolCallParser.ts</code>), errors (<code>errorNormalizer.ts</code>), and usage (<code>usageNormalizer.ts</code>) to a uniform format.</p>
+
+  <h3>4. Tool Execution &amp; Query Loop</h3>
+  <p>Tools use Zod schemas and are executed by the <strong>StreamingToolExecutor</strong> (<code>src/services/tools/StreamingToolExecutor.ts</code>). Permission gating via hooks in <code>src/utils/permissions/permissions.ts</code>. The query loop in <code>src/query.ts</code> + <code>src/QueryEngine.ts</code> orchestrates message building, context management, streaming, and tool call cycling. MCP tools (<code>src/services/mcp/</code>) are discovered at runtime and merged into the tool pool.</p>
+
+  <h2>Data Flow</h2>
+  <pre><code>  Terminal input
+       |
+       v
+  + Query Engine (query.ts + QueryEngine.ts)
+  |    Message building and context assembly
+  |    Tool call loop (model tool results)
+  |    Streaming response handling
+  |
+  + Provider Manager Adapter AI Model API
+  |    27 providers via providers.json
+  |    AnthropicAdapter / GoogleAdapter normalization
+  |
+  + Tool Executor (StreamingToolExecutor)
+  |    Permission check (permissions.ts)
+  |    Pre/Post tool hooks (plugins)
+  |    Tool execution result
+  |
+  + Terminal UI (React/Ink)
+       Streaming text and tool renders
+       Status bar, spinner, context meter
+       Permission dialogs</code></pre>
+
+  <h2>Key Subsystems</h2>
+
+  <h3>MCP (Model Context Protocol)</h3>
+  <p><code>src/services/mcp/</code> — manages external MCP server connections, tool discovery, resource access, and paginated <code>tools/list</code> responses. Servers configured via <code>--mcp-config</code> or <code>/mcp</code> command. See <a href="mcp.html">MCP</a> for detailed setup and configuration.</p>
+
+  <h3>Plugins &amp; Hooks</h3>
+  <p><code>src/services/plugins/</code> — plugin loading, installation, marketplace reconciliation, and hook dispatch. Hook points: <code>PreToolUse</code>, <code>PostToolUse</code>, <code>PreBash</code>, <code>PostPrompt</code>, <code>PreAcceptEdit</code>. Plugins can provide commands, agents, skills, MCP servers, and LSP integrations.</p>
+
+  <h3>LSP (Language Server Protocol)</h3>
+  <p><code>src/services/lsp/</code> — language-aware code intelligence via LSP servers. Diagnostics, completions, and symbol navigation. Enable with <code>ENABLE_LSP_TOOL=1</code>.</p>
+
+  <h3>Bridge Mode</h3>
+  <p><code>src/bridge/bridgeMain.ts</code> — WebSocket remote control and collaboration. Gated behind <code>BRIDGE_MODE=1</code>. Remote clients can send commands and receive responses.</p>
+
+  <h3>Session System</h3>
+  <p><code>src/services/SessionBridge/</code> — cross-session context persistence. <code>src/services/SessionMemory/</code> — persistent knowledge with cross-lingual semantic search and auto-memory capture.</p>
+
+  <h3>GrowthBook Feature Flags</h3>
+  <p><code>src/services/analytics/growthbook.js</code> — A/B testing and feature flag platform. Initialized at startup, evaluates flags locally with caching.</p>
+
+  <h3>Agent Runtime</h3>
+  <p><code>src/agentRuntime/</code> — manages multi-agent orchestration. The <strong>orchestrator</strong> coordinates agent sessions, <strong>runStore</strong> persists agent run data, <strong>toolGateway</strong> routes tools between agents, and <strong>workflowRegistry</strong> / <strong>agentRegistry</strong> declare named workflows and agent configurations.</p>
+
+  <h3>Autonomous / Daemon</h3>
+  <p><code>src/services/autonomous/</code> — enables 24/7 background execution. The <strong>taskQueue</strong> is a file-backed queue with priorities, leases, and dead-letter handling. <strong>agentLoop</strong> runs the continuous dequeue spawn worker monitor retry cycle. <strong>daemonMode</strong> provides the supervisor-managed background process entry point, and <strong>supervisorIntegration</strong> handles health checks and auto-respawn. See <a href="daemon.html">Daemon Mode</a> for detailed configuration and usage.</p>
+
+  <h3>Coordinator (Multi-Agent)</h3>
+  <p><code>src/coordinator/</code> — supports multi-agent collaboration. <strong>coordinatorMode</strong> delegates tasks to sub-agents, and <strong>workerAgent</strong> provides standalone workers for delegated subtasks.</p>
+
+  <h3>Research &amp; Memory</h3>
+  <p><code>src/research/</code> — built-in deep research capabilities: citation extraction, claim verification, dossier generation, truth checking, and source ranking. <code>src/memdir/</code> — semantic memory with text embedding search, memory age tracking, auto-memory capture, and cross-session recall. See <a href="research-memory.html">Research &amp; Memory</a> for detailed usage.</p>
+
+  <h3>Voice Mode</h3>
+  <p><code>src/voice/</code> — compile-time gated voice input support (<code>VOICE_MODE=1</code>). Provides speech-to-text and voice command processing for hands-free operation.</p>
+
+  <h3>State Management</h3>
+  <p>The app uses a lightweight observable store pattern (<code>createStore&lt;T&gt;</code> in <code>src/state/store.ts</code>). Stores are plain functions with <code>getState</code>, <code>setState</code>, and <code>subscribe</code>. React components subscribe via the <strong>AppState</strong> React context (<code>src/state/AppState.tsx</code>).</p>
+
+  <h2>Important Source Paths</h2>
+  <table>
+    <tr><th>Path</th><th>Role</th></tr>
+    <tr><td><code>src/main.tsx</code></td><td>CLI entry, Commander program, option parsing, REPL launch</td></tr>
+    <tr><td><code>src/query.ts</code></td><td>Core query processing, message building, tool call loop</td></tr>
+    <tr><td><code>src/QueryEngine.ts</code></td><td>Query orchestration, caching, deduplication, rate limiting</td></tr>
+    <tr><td><code>src/commands.ts</code></td><td>Slash command registry (80+ commands)</td></tr>
+    <tr><td><code>src/tools.ts</code></td><td>Tool registry (40+ built-in tools)</td></tr>
+    <tr><td><code>src/Tool.ts</code></td><td>Base tool types, schemas, buildTool() helper</td></tr>
+    <tr><td><code>src/services/ai/ProviderManager.ts</code></td><td>Provider selection, API key resolution</td></tr>
+    <tr><td><code>src/services/ai/providers.json</code></td><td>Declarative provider config (27 providers)</td></tr>
+    <tr><td><code>src/services/ai/adapter/</code></td><td>AnthropicAdapter, GoogleAdapter</td></tr>
+    <tr><td><code>src/services/tools/StreamingToolExecutor.ts</code></td><td>Streaming tool execution</td></tr>
+    <tr><td><code>src/utils/permissions/permissions.ts</code></td><td>Permission evaluation logic</td></tr>
+    <tr><td><code>src/services/mcp/</code></td><td>MCP server management</td></tr>
+    <tr><td><code>src/services/plugins/</code></td><td>Plugin loader and hook dispatch</td></tr>
+    <tr><td><code>src/state/store.ts</code></td><td>Lightweight observable store (createStore&lt;T&gt;)</td></tr>
+    <tr><td><code>src/state/AppState.tsx</code></td><td>Root app state (React context)</td></tr>
+    <tr><td><code>src/state/AppStateStore.ts</code></td><td>App state store implementation</td></tr>
+    <tr><td><code>src/state/selectors.ts</code></td><td>State selectors</td></tr>
+    <tr><td><code>src/agentRuntime/</code></td><td>Agent orchestration, run store, tool gateway</td></tr>
+    <tr><td><code>src/services/autonomous/</code></td><td>Task queue, agent loop, daemon mode, supervisor</td></tr>
+    <tr><td><code>src/coordinator/</code></td><td>Multi-agent coordinator and worker agents</td></tr>
+    <tr><td><code>src/research/</code></td><td>Deep research, dossier generation, truth checking</td></tr>
+    <tr><td><code>src/memdir/</code></td><td>Semantic memory search and storage</td></tr>
+    <tr><td><code>src/voice/</code></td><td>Voice mode support (compile-time gated)</td></tr>
+    <tr><td><code>src/entrypoints/init.ts</code></td><td>Startup initialization (Sentry, configs, telemetry)</td></tr>
+    <tr><td><code>src/entrypoints/cli.tsx</code></td><td>Alternative CLI entry point (Commander-based)</td></tr>
+    <tr><td><code>src/entrypoints/mcp.ts</code></td><td>MCP server entry point</td></tr>
+  </table>
+
+  <h2>Build System</h2>
+  <p>Built with Bun bundler — <code>bun run build</code> outputs a single binary to <code>dist/</code>. TypeScript with strict mode and ESM/NodeNext module resolution. External dependencies include Electron, chromium-bidi, AWS SDK, Google Auth, and platform-specific native modules. Lint/format via Biome 2.4.</p>
+
+  <footer class="footer">
+    <span>Clew v0.1.2 — Open Source</span>
+    <div class="footer-links">
+      <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
+      <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
+    </div>
+  </footer>
+</main>
+<nav class="toc-sidebar"></nav>
+</div>
+</div>
+<script src="js/main.js"></script>
+</body>
+</html>