diff --git a/AGENTS.md b/AGENTS.md index 21ebe5e..d71128f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ Flynn is a multi-channel AI assistant daemon. Messages flow: **Channel Adapter ### Core Abstractions -**ModelClient** (`src/models/types.ts`): `chat(request): Promise`. Providers: Anthropic, OpenAI, Gemini, Bedrock, Ollama, llama.cpp, GitHub Models, OpenRouter, Zhipu. Factory in `src/daemon/index.ts` (`createClientFromConfig()`). **ModelRouter** (`src/models/router.ts`) manages tiers (default/fast/complex/local) with fallback chains. +**ModelClient** (`src/models/types.ts`): `chat(request): Promise`. Providers: Anthropic, OpenAI, Gemini, Bedrock, Ollama, llama.cpp, GitHub Models, OpenRouter, Zhipu, xAI. Factory in `src/daemon/index.ts` (`createClientFromConfig()`). **ModelRouter** (`src/models/router.ts`) manages tiers (default/fast/complex/local) with fallback chains. **ChannelAdapter** (`src/channels/types.ts`): `connect()`, `disconnect()`, `send()`, `onMessage()`. Adapters: Telegram, Discord, Slack, WhatsApp, WebChat. Registered in `ChannelRegistry`, each channel+sender pair gets its own session. @@ -62,7 +62,8 @@ Registration chain: tool file → `src/tools/builtin/index.ts` → `src/tools/in - **Hooks**: Pattern-based confirmation engine (`src/hooks/`). Actions: confirm/log/silent. - **Sandbox**: Docker per-session containers (`src/sandbox/manager.ts`). - **Automation**: Cron scheduler, webhooks (HMAC), heartbeat monitor, Gmail watcher (`src/automation/`). -- **Gateway**: WebSocket JSON-RPC + HTTP server + vanilla JS dashboard (`src/gateway/`). +- **Gateway**: WebSocket JSON-RPC + HTTP server + vanilla JS dashboard (`src/gateway/`). Lane queue, gateway lock, Tailscale Serve. +- **Pairing**: DM pairing codes for unknown sender auth (`src/channels/pairing.ts`). Gateway handlers + TUI command. - **System Prompt**: Template search for SOUL.md/AGENTS.md/IDENTITY.md/USER.md/TOOLS.md (`src/prompt/template.ts`). ## Code Style Guidelines diff --git a/CHANGELOG.md b/CHANGELOG.md index 034fd22..60ec568 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,35 @@ All notable changes to Flynn are documented in this file. ### Added +- **xAI (Grok) Provider** -- xAI as OpenAI-compatible model provider with + `provider: xai` config. Supports grok-3, grok-3-mini, grok-2, grok-2-mini, + grok-3-fast. Uses `XAI_API_KEY` env var or config `api_key`. +- **Voyage AI Embeddings** -- Voyage AI embedding provider for memory vector + search. OpenAI-compatible API at `https://api.voyageai.com/v1`, defaults to + 1024 dimensions. Uses `VOYAGE_API_KEY` env var. +- **Lane Queue** -- Per-session FIFO queue in the gateway that serializes + concurrent requests instead of rejecting them. Ensures ordered execution + within each session. 9 tests. +- **Credential Redaction** -- Expanded `redactConfig()` from 2 to 18+ secret + fields: all channel tokens, model tier api_keys, embedding keys, webhook + secrets, Gmail credentials, MCP server env vars. +- **Web UI Token Dashboard** -- New Usage page in the web dashboard SPA with + summary cards (total tokens, cost, sessions), per-session breakdown table, + and 10s auto-refresh. New `system.tokenUsage` gateway endpoint. +- **Gateway Lock** -- Single-client mode for the WebSocket gateway. When + `server.lock: true`, only one connection allowed at a time; additional + connections rejected with close code 4003. Web UI detects locked state. 4 tests. +- **Shell Completion** -- `flynn completion ` command generating bash, + zsh, and fish completions. `--install` flag writes to the appropriate shell + config file. 11 tests. +- **Tailscale Serve** -- Auto-expose gateway via `tailscale serve` on daemon + start. `isTailscaleAvailable()` check, auto-start/stop lifecycle, `flynn + doctor` integration. 6 tests. +- **DM Pairing Codes** -- PairingManager with time-limited codes for + authenticating unknown DM senders. Integrated into all 4 channel adapters + (Telegram, Discord, Slack, WhatsApp). Gateway handlers (`pairing.generate`, + `pairing.list`, `pairing.revoke`). TUI `/pair` command. Configurable TTL + and code length. 22 tests. - **Zhipu AI (GLM) Provider** -- Support for Zhipu AI's GLM models (glm-4.5, glm-4.7, etc.) via their OpenAI-compatible API at `https://api.z.ai/api/paas/v4`. Uses `provider: zhipuai` in config with `api_key` or `ZHIPUAI_API_KEY` env var. diff --git a/CLAUDE.md b/CLAUDE.md index bd0e2f4..d94ed6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ Flynn is a multi-channel AI assistant daemon. Messages flow: **Channel Adapter ### Core Abstractions -**ModelClient** (`src/models/types.ts`): `chat(request): Promise`. Providers: Anthropic, OpenAI, Gemini, Bedrock, Ollama, llama.cpp, GitHub Models, OpenRouter, Zhipu. Factory in `src/daemon/index.ts` (`createClientFromConfig()`). **ModelRouter** (`src/models/router.ts`) manages tiers (default/fast/complex/local) with fallback chains. +**ModelClient** (`src/models/types.ts`): `chat(request): Promise`. Providers: Anthropic, OpenAI, Gemini, Bedrock, Ollama, llama.cpp, GitHub Models, OpenRouter, Zhipu, xAI. Factory in `src/daemon/index.ts` (`createClientFromConfig()`). **ModelRouter** (`src/models/router.ts`) manages tiers (default/fast/complex/local) with fallback chains. **ChannelAdapter** (`src/channels/types.ts`): `connect()`, `disconnect()`, `send()`, `onMessage()`. Adapters: Telegram, Discord, Slack, WhatsApp, WebChat. Registered in `ChannelRegistry`, each channel+sender pair gets its own session. @@ -47,7 +47,8 @@ Registration chain: tool file → `src/tools/builtin/index.ts` → `src/tools/in - **Hooks**: Pattern-based confirmation engine (`src/hooks/`). Actions: confirm/log/silent. - **Sandbox**: Docker per-session containers (`src/sandbox/manager.ts`). - **Automation**: Cron scheduler, webhooks (HMAC), heartbeat monitor, Gmail watcher (`src/automation/`). -- **Gateway**: WebSocket JSON-RPC + HTTP server + vanilla JS dashboard (`src/gateway/`). +- **Gateway**: WebSocket JSON-RPC + HTTP server + vanilla JS dashboard (`src/gateway/`). Lane queue for per-session request serialization. Gateway lock for single-client mode. Tailscale Serve integration. +- **Pairing**: DM pairing codes for unknown sender authentication (`src/channels/pairing.ts`). Gateway handlers + TUI `/pair` command. - **System Prompt**: Template search for SOUL.md/AGENTS.md/IDENTITY.md/USER.md/TOOLS.md (`src/prompt/template.ts`). ## Code Conventions diff --git a/README.md b/README.md index 64b8da5..e619d98 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces. ## Features - **Multi-Frontend**: Telegram bot + Terminal UI (minimal & fullscreen modes) + Web UI dashboard -- **Multi-Model**: Anthropic Claude, OpenAI, GitHub Copilot, Gemini, Bedrock, Zhipu AI (GLM), Ollama, llama.cpp with intelligent routing +- **Multi-Model**: Anthropic Claude, OpenAI, GitHub Copilot, Gemini, Bedrock, Zhipu AI (GLM), xAI (Grok), Ollama, llama.cpp with intelligent routing - **Multi-Channel**: Telegram, Discord, Slack, WhatsApp with unified adapter interface -- **Web Dashboard**: SPA control panel with health monitoring, chat, session browser, and settings editor +- **Web Dashboard**: SPA control panel with health monitoring, chat, session browser, usage stats, and settings editor - **Model Switching**: Switch between cloud/local models on demand - **Session Persistence**: SQLite-backed conversation history - **Fallback Chains**: Automatic failover when primary model fails @@ -17,16 +17,21 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces. - **Multi-Agent Routing**: Config-driven agent selection per sender/channel with tool profiles - **Media Pipeline**: Image analysis, outbound attachments, audio transcription across all channels - **Session Transfer**: Move conversations between frontends -- **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, etc.) +- **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, `completion`, etc.) +- **Shell Completion**: Auto-generated completions for bash, zsh, and fish with `--install` flag - **Cron Scheduling**: Automated messages on cron schedules with output routing - **Inbound Webhooks**: HTTP endpoints that trigger agent processing with HMAC auth and template rendering - **Heartbeat Monitor**: Periodic health checks (gateway, model, channels, memory, disk) with failure notifications - **Gmail Pub/Sub Watcher**: Monitor Gmail inbox via Google Cloud Pub/Sub push notifications with polling fallback -- **Vector Memory Search**: Hybrid keyword + semantic search with embeddings (OpenAI, Gemini, Ollama, llama.cpp) +- **Vector Memory Search**: Hybrid keyword + semantic search with embeddings (OpenAI, Gemini, Ollama, llama.cpp, Voyage AI) - **Docker Deployment**: Multi-stage Dockerfile and docker-compose.yml for production containers - **Health Diagnostics**: `flynn doctor` validates config, connectivity, and system state - **MCP Integration**: External tool servers via Model Context Protocol - **Skills System**: Extensible capability packages (bundled, managed, workspace tiers) +- **Gateway Lock**: Single-client mode — reject additional WebSocket connections when one is active +- **Tailscale Serve**: Auto-expose gateway via Tailscale Serve on daemon start with lifecycle management +- **DM Pairing Codes**: Allow unknown senders to pair with the bot via time-limited codes across all channels +- **Lane Queue**: Per-session FIFO queue serializes concurrent gateway requests ## Quick Start @@ -58,6 +63,7 @@ Flynn provides a full CLI via the `flynn` binary (or `npx tsx src/cli/index.ts` | `flynn sessions` | List active sessions | | `flynn doctor` | Validate config and check system health | | `flynn config` | Show resolved configuration (secrets redacted) | +| `flynn completion ` | Generate shell completions (bash, zsh, fish) | ### Examples @@ -76,6 +82,11 @@ flynn config # List sessions flynn sessions + +# Generate shell completions +flynn completion bash # Print bash completions to stdout +flynn completion zsh --install # Install zsh completions to ~/.zshrc +flynn completion fish --install # Install fish completions to config ``` ## Configuration @@ -114,6 +125,7 @@ hooks: | Bedrock | `provider: bedrock`, AWS credentials | | Ollama | `provider: ollama`, `model`, optional `endpoint` | | Zhipu AI (GLM) | `provider: zhipuai`, `api_key` or `ZHIPUAI_API_KEY`, optional `endpoint` | +| xAI (Grok) | `provider: xai`, `api_key` or `XAI_API_KEY` | | llama.cpp | `provider: llamacpp`, `endpoint` | ### Model Tiers @@ -150,6 +162,7 @@ Flynn includes a built-in web control dashboard served by the WebSocket gateway. | **Dashboard** | System health cards, channel status, usage stats. Auto-refreshes every 10s | | **Chat** | Session selector, streaming tool events, markdown rendering with syntax highlighting | | **Sessions** | Browse all sessions, view message history, delete sessions | +| **Usage** | Token usage summary cards, per-session breakdown table, auto-refresh | | **Settings** | Edit hook patterns (confirm/log/silent), view tools, channels, and redacted config | The dashboard is a vanilla JS SPA with no build step — hash-based routing, ES modules, and the existing WebSocket JSON-RPC protocol. @@ -171,6 +184,13 @@ pnpm tui:fs | `/help` | Show help | | `/reset` | Clear history | | `/status` | Show session info | +| `/compact` | Compact conversation context | +| `/usage` | Show token usage and cost | +| `/verbose` | Toggle verbose output mode | +| `/local` | Switch to local model | +| `/cloud` | Switch to cloud model | +| `/model` | Show model info and options | +| `/pair` | Generate/list/revoke DM pairing codes | | `/fullscreen` | Switch to fullscreen mode | | `/transfer telegram` | Transfer session to Telegram | | `/quit` | Exit | @@ -425,6 +445,7 @@ memory: | Gemini | `provider: gemini`, `api_key`, `model` | | Ollama | `provider: ollama`, `endpoint` (default: localhost:11434), `model` | | llama.cpp | `provider: llamacpp`, `endpoint`, optional `model` | +| Voyage AI | `provider: voyageai`, `api_key` or `VOYAGE_API_KEY`, `model` (default: `voyage-3-large`) | Embeddings are indexed in the background — when memory is written, the namespace is marked dirty and re-indexed within 30 seconds. The vector index is stored in `vectors.db` alongside the session database. @@ -438,13 +459,88 @@ When embeddings are disabled or the provider is unreachable, search falls back g | `provider` | no | Embedding provider (default: `openai`) | | `model` | no | Embedding model name (default: `text-embedding-3-small`) | | `endpoint` | no | Provider endpoint (required for `ollama`/`llamacpp`) | -| `api_key` | no | API key (required for `openai`/`gemini`) | +| `api_key` | no | API key (required for `openai`/`gemini`/`voyageai`) | | `dimensions` | no | Vector dimensions (auto-detected from model if not set) | | `chunk_size` | no | Max tokens per chunk (default: `512`) | | `chunk_overlap` | no | Token overlap between chunks (default: `50`) | | `top_k` | no | Number of vector results to return (default: `5`) | | `hybrid_weight` | no | Vector vs keyword weight, 0.0-1.0 (default: `0.7`) | +## Gateway Lock + +Single-client mode for the WebSocket gateway. When enabled, only one WebSocket connection is allowed at a time. Additional connections are rejected with close code `4003`. + +```yaml +server: + lock: true +``` + +The web UI detects the locked state and disables auto-reconnect when rejected. + +## Tailscale Serve + +Automatically expose the gateway via Tailscale Serve when the daemon starts. Requires Tailscale to be installed and authenticated on the host. + +```yaml +server: + tailscale: + serve: true +``` + +When enabled, Flynn runs `tailscale serve` on startup to expose the gateway port over your tailnet, and cleans up on shutdown. The `flynn doctor` command includes a Tailscale availability check. + +## DM Pairing Codes + +Allow unknown senders to authenticate with the bot via time-limited pairing codes. Works across all channel adapters (Telegram, Discord, Slack, WhatsApp). + +```yaml +pairing: + enabled: true + code_ttl: "10m" # Code expiry time (default: 10 minutes) + code_length: 6 # Code length (default: 6 digits) +``` + +### How it works + +1. Generate a code via the TUI (`/pair generate`), gateway API (`pairing.generate`), or web dashboard +2. Share the code with the user +3. The user sends the code as their first DM to the bot +4. If valid, the user's sender ID is permanently approved for that channel +5. Approved users can be listed (`/pair list`) and revoked (`/pair revoke `) + +### TUI Commands + +| Command | Description | +|---------|-------------| +| `/pair` | Generate a new pairing code | +| `/pair generate [label]` | Generate a code with optional label | +| `/pair list` | List pending codes and approved senders | +| `/pair revoke ` | Revoke an approved sender | + +### Gateway API + +| Method | Description | +|--------|-------------| +| `pairing.generate` | Generate a new pairing code (optional `label` param) | +| `pairing.list` | List pending codes and approved senders | +| `pairing.revoke` | Revoke an approved sender (`channel` + `senderId` params) | + +## Shell Completion + +Generate shell completions for bash, zsh, or fish: + +```bash +# Print completions to stdout +flynn completion bash +flynn completion zsh +flynn completion fish + +# Install directly to shell config +flynn completion bash --install # Appends to ~/.bashrc +flynn completion zsh --install # Appends to ~/.zshrc +flynn completion fish --install # Writes to ~/.config/fish/completions/flynn.fish +``` + ## Docker Deployment Flynn includes a production-ready Dockerfile with multi-stage build. @@ -549,7 +645,9 @@ src/ ├── auth/ # OAuth flows (GitHub Copilot) ├── backends/native/ # Agent implementation + orchestrator ├── channels/ # Channel adapters (Telegram, Discord, Slack, WhatsApp, WebChat) +│ └── pairing.ts # DM pairing code manager ├── cli/ # CLI commands (commander) +│ └── completion.ts # Shell completion generator (bash/zsh/fish) ├── config/ # YAML config + Zod validation ├── context/ # Token estimation + compaction ├── daemon/ # Lifecycle management + routing @@ -557,9 +655,11 @@ src/ │ ├── telegram/ # Telegram bot │ └── tui/ # Terminal UI (minimal + fullscreen) ├── gateway/ # WebSocket gateway + web UI dashboard -│ ├── handlers/ # JSON-RPC method handlers +│ ├── handlers/ # JSON-RPC method handlers (agent, sessions, system, pairing, tools, config) +│ ├── tailscale.ts # Tailscale Serve lifecycle management +│ ├── lane-queue.ts # Per-session FIFO request queue │ └── ui/ # SPA dashboard (vanilla JS) -│ ├── pages/ # Dashboard, Chat, Sessions, Settings +│ ├── pages/ # Dashboard, Chat, Sessions, Usage, Settings │ └── lib/ # WebSocket RPC client ├── hooks/ # Confirmation engine ├── mcp/ # MCP tool server integration