diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2d49a58 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,46 @@ +# Changelog + +All notable changes to Flynn are documented in this file. + +## [Unreleased] + +### Added + +- **CLI Surface** -- Full command-line interface via `flynn` binary with 6 commands: + `start`, `tui`, `send`, `sessions`, `doctor`, `config` +- **Doctor Diagnostics** -- `flynn doctor` validates config, YAML parsing, schema, + env vars, data directory, session DB, model config, Telegram, MCP servers, and skills +- **Cron Scheduling** -- `automation.cron` config for scheduled agent messages with + output channel routing (e.g. fire a prompt at 9 AM, send the response to Telegram) +- **CronScheduler Channel Adapter** -- Implements `ChannelAdapter` interface for + cron-triggered messages through the standard agent pipeline +- **CLI Shared Utilities** -- Config loading, data dir resolution, secret redaction, + status formatting for all CLI commands +- **CronJobConfig Type Export** -- `CronJobConfig` type available from `config/index.ts` + +### Changed + +- **Entry Points Refactored** -- `src/index.ts` and `src/tui.ts` now delegate to + the CLI module (`src/cli/index.ts`) instead of directly starting the daemon/TUI +- **Daemon Wiring** -- CronScheduler auto-registers in the channel registry when + `automation.cron` jobs are configured + +## [0.1.0] - 2026-02-05 + +### Added + +- **Core Agent** -- NativeAgent with conversation history and iterative tool use +- **Model Providers** -- Anthropic Claude, OpenAI, Ollama, llama.cpp with streaming +- **Model Router** -- Intelligent routing with fallback chains and tier switching +- **Telegram Bot** -- Full Telegram frontend with commands, confirmations, tool status +- **Terminal UI** -- Minimal (readline) and fullscreen (React/Ink) modes with + markdown rendering, streaming, model switching, and session transfer +- **Session Persistence** -- SQLite-backed sessions with multi-frontend support +- **Hook Engine** -- Pattern-based confirmation system for sensitive tool operations +- **Tool Framework** -- Registry, executor, and builtin tools (shell, file, web-fetch) +- **Channel Abstraction** -- Unified ChannelAdapter interface with Telegram and WebChat +- **WebSocket Gateway** -- JSON-RPC protocol with API key auth and web UI dashboard +- **MCP Integration** -- External tool server support via Model Context Protocol +- **Skills System** -- Extensible capability packages (bundled, managed, workspace tiers) +- **Config System** -- YAML config with Zod validation and env var expansion +- **Daemon Lifecycle** -- Graceful shutdown with ordered cleanup handlers diff --git a/README.md b/README.md index c12d7ac..26feeba 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,9 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces. - **Fallback Chains**: Automatic failover when primary model fails - **Hook Engine**: Confirmation system for sensitive operations - **Session Transfer**: Move conversations between frontends +- **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, etc.) +- **Cron Scheduling**: Automated messages on cron schedules with output routing +- **Health Diagnostics**: `flynn doctor` validates config, connectivity, and system state ## Quick Start @@ -24,9 +27,44 @@ cp config/default.yaml ~/.config/flynn/config.yaml # Build and run pnpm build +flynn start + +# Or run without building pnpm start ``` +## CLI Commands + +Flynn provides a full CLI via the `flynn` binary (or `npx tsx src/cli/index.ts` during development): + +| Command | Description | +|---------|-------------| +| `flynn start` | Start the Flynn daemon (Telegram, WebChat, cron) | +| `flynn tui` | Launch the interactive terminal UI | +| `flynn send ` | Send a one-shot message and print the response | +| `flynn sessions` | List active sessions | +| `flynn doctor` | Validate config and check system health | +| `flynn config` | Show resolved configuration (secrets redacted) | + +### Examples + +```bash +# Start daemon with custom config +flynn start --config ~/my-config.yaml + +# One-shot query +flynn send "What's the weather in London?" + +# Check system health +flynn doctor --config ~/.config/flynn/config.yaml + +# Show current config (secrets masked) +flynn config + +# List sessions +flynn sessions +``` + ## Configuration Config location: `~/.config/flynn/config.yaml` (or set `FLYNN_CONFIG`) @@ -151,6 +189,84 @@ hooks: - notify ``` +## Cron Scheduling + +Schedule automated messages on cron schedules. Each job fires an inbound message through the agent pipeline and routes the response to a configured output channel. + +```yaml +automation: + cron: + - name: daily-summary + schedule: "0 9 * * *" # 9 AM daily + message: "Give me a summary of today's tasks" + output: + channel: telegram # Route response to Telegram + peer: "123456789" # Chat ID to send to + timezone: Europe/London # Optional timezone + enabled: true + + - name: hourly-check + schedule: "0 * * * *" # Every hour + message: "Check system status" + output: + channel: telegram + peer: "123456789" + enabled: false # Disabled, won't fire +``` + +### Cron Config Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | yes | Unique job identifier | +| `schedule` | yes | Cron expression (standard 5-field) | +| `message` | yes | Text sent to the agent when the job fires | +| `output.channel` | yes | Channel name to route the response (e.g. `telegram`) | +| `output.peer` | yes | Peer/chat ID on the output channel | +| `timezone` | no | IANA timezone (defaults to system timezone) | +| `enabled` | no | Whether the job is active (default: `true`) | + +## Doctor Diagnostics + +`flynn doctor` runs 10 health checks to validate your setup: + +``` +$ flynn doctor + +Flynn Doctor +============ + +[PASS] Config file exists (/home/user/.config/flynn/config.yaml) +[PASS] Config parses (valid YAML) +[PASS] Config validates (schema valid) +[PASS] Env vars resolved +[PASS] Data directory writable (/home/user/.local/share/flynn) +[PASS] Session DB accessible (sessions.db) +[PASS] Model connectivity (anthropic: claude-sonnet) +[PASS] Telegram bot configured (1 allowed chat(s)) +[SKIP] MCP servers configured (none configured) +[PASS] Skills loaded (3 skill(s)) + +Results: 8 passed, 0 failed, 0 warnings, 1 skipped +``` + +### Check Details + +| Check | What it validates | +|-------|-------------------| +| Config file exists | Config YAML file is present at the expected path | +| Config parses | File is valid YAML syntax | +| Config validates | YAML content passes Zod schema validation | +| Env vars resolved | Any `${VAR}` references in config have values set | +| Data directory writable | Can write to `~/.local/share/flynn/` | +| Session DB accessible | SQLite database opens and queries succeed | +| Model connectivity | Default model provider and model name are configured | +| Telegram bot configured | Bot token is present and reasonable length | +| MCP servers configured | Lists configured MCP tool servers | +| Skills loaded | Discovers and loads skill packages | + +Exit code is `1` if any check fails, `0` otherwise. Checks that depend on a valid config are skipped when config is invalid. + ## Session Management - Sessions persist in `~/.local/share/flynn/sessions.db` @@ -162,14 +278,19 @@ hooks: ``` src/ -├── index.ts # Daemon entry -├── tui.ts # TUI entry -├── config/ # YAML config + validation +├── cli/ # CLI commands (commander) +├── config/ # YAML config + Zod validation ├── models/ # Model providers + router ├── backends/native/ # Agent implementation ├── session/ # SQLite persistence ├── hooks/ # Confirmation engine ├── daemon/ # Lifecycle management +├── channels/ # Channel adapter abstraction +├── automation/ # Cron scheduler +├── gateway/ # WebSocket gateway + web UI +├── mcp/ # MCP tool server integration +├── skills/ # Skill packages +├── tools/ # Builtin tools (shell, file, web) └── frontends/ ├── telegram/ # Telegram bot └── tui/ # Terminal UI