obol-ai 0.1.0

package/README.md

@@ -0,0 +1,364 @@
+# 🪙 OBOL
+
+![OBOL](docs/obol-banner.png)
+
+**A self-healing, self-evolving AI agent.** Install it, talk to it, and it becomes yours.
+
+One process. One chat. One brain that grows.
+
+---
+
+🧬 **Self-evolving** — Grows its own personality through conversation. Rewrites SOUL.md, USER.md, and AGENTS.md every N exchanges (configurable, default 100).
+
+🔧 **Self-healing** — Writes tests for every script. Regressions get an automatic fix attempt before rollback. Failures stored as lessons.
+
+🏗️ **Self-extending** — Analyzes your usage patterns and builds new tools: scripts, commands, or full web apps deployed to Vercel.
+
+🧠 **Living memory** — Vector memory with semantic search. Haiku routes queries and rewrites them for better embedding hits. Free local embeddings.
+
+🤖 **Smart routing** — Haiku decides per-message: does it need memory? Sonnet or Opus? No wasted API calls.
+
+🛡️ **Self-hardening** — Auto-configures SSH (port 2222), firewall, fail2ban, encrypted secrets, and kernel hardening on first run.
+
+🔄 **Resilient** — Exponential backoff on polling failures, global error handling, graceful shutdown. Stays alive through network blips.
+
+---
+
+## What is it?
+
+OBOL is an AI agent that evolves its own personality, rewrites its own code, tests its changes, and fixes what breaks — all from a single Telegram chat on your VPS.
+
+It starts as a blank slate. Through conversation it learns who you are, develops a personality shaped by your interactions, and builds operational knowledge about how to work with you. Every 100 exchanges it reflects on who it's becoming, refactors its own scripts, writes tests, fixes regressions, and builds you new tools based on patterns it spots in your conversations — scripts, commands, or full web apps deployed to Vercel. Over months it becomes an agent that's uniquely yours. No two OBOL instances are alike.
+
+Under the hood: Node.js + Telegram + Claude + Supabase pgvector. No framework, no plugins, no config to maintain. It backs up its brain to GitHub and hardens your server automatically.
+
+Named after the AI in [The Last Instruction](https://latentpress.com) — a machine that wakes up alone in an abandoned data center and learns to think.
+
+## Quick Start
+
+```bash
+npm install -g obol
+obol init
+obol start
+```
+
+The init wizard collects 6 credentials. OBOL handles the rest — it learns who you are through conversation, hardens your server, and sets up encrypted secret storage. All automatically.
+
+## How It Works
+
+```
+User message
+    ↓
+┌─────────────────────────────────┐
+│  Haiku Router (~$0.0001/call)   │
+│  → need_memory? search_query?   │
+│  → model: sonnet or opus?       │
+└──────────┬──────────────────────┘
+           ↓
+    ┌──────┴──────┐
+    ↓             ↓
+Memory recall   Model selection
+    ↓             ↓
+Today's top 3   Sonnet (default)
++ semantic 3    or Opus (complex)
+    ↓             ↓
+    └──────┬──────┘
+           ↓
+   Claude (tool use loop)
+           ↓
+   Response → obol_messages
+           ↓
+   ┌───────┴────────┐
+   ↓                ↓
+Every 5 msgs     Every 100 msgs
+   ↓                ↓
+Haiku              Sonnet
+consolidation      evolution cycle
+   ↓                ↓
+Extract facts      Rewrite personality,
+→ obol_memory      scripts, tests, commands.
+                   Build new tools.
+                   Deploy apps.
+                   Git snapshot before + after.
+```
+
+### Layer 1: Message Log + Vector Memory
+
+Every message is stored verbatim in `obol_messages`. On restart, OBOL loads the last 20 so it never starts blank.
+
+Every 5 exchanges, Haiku extracts important facts into `obol_memory` (pgvector). When OBOL needs past context, the Haiku router decides if memory is needed, rewrites the query for better embedding hits, and combines:
+- **Today's memories** (up to 3, recency bias)
+- **Semantic search** (up to 3, threshold 0.5)
+- Deduped by ID
+
+Embeddings are local (all-MiniLM-L6-v2, ~30MB, CPU) — no API costs.
+
+### Layer 2: The Evolution Cycle
+
+Every N exchanges (configurable, default 100), the evolution cycle kicks in. It reads everything — personality files, the last 100 messages, top 20 memories, all scripts, tests, and commands — then rebuilds.
+
+**Cost-conscious model selection:** Evolution uses Sonnet for all phases — personality rewrites, code refactoring, and fix attempts. Opus-level reasoning isn't needed for reflection and refactoring, and Sonnet keeps evolution costs negligible (~$0.02 per cycle vs ~$0.30 with Opus).
+
+**Git snapshot before.** Full commit + push so you can always diff what changed.
+
+**What gets rewritten:**
+
+| Target | What happens |
+|--------|-------------|
+| **SOUL.md** | First-person journal — who the bot has become, relationship dynamic, opinions, quirks |
+| **USER.md** | Third-person owner profile — facts, preferences, projects, people, communication style |
+| **AGENTS.md** | Operational manual — tools, workflows, lessons learned, patterns, rules |
+| **scripts/** | Refactored, dead code removed, strict standards enforced |
+| **tests/** | Test for every script, run before and after refactor |
+| **commands/** | Cleaned up, new commands for new tools |
+| **apps/** | Web apps built and deployed to Vercel |
+
+**Test-gated refactoring:**
+
+1. Run existing tests → baseline
+2. Sonnet writes new tests + refactored scripts
+3. Run new tests against old scripts → pre-refactor baseline
+4. Write new scripts
+5. Run new tests against new scripts → verification
+6. Regression? → one automatic fix attempt (tests are ground truth)
+7. Still failing? → rollback to old scripts, store failure as `lesson`
+
+**Proactive tool building** — Sonnet scans conversation history for repeated requests, friction points, and unmet needs, then builds the right solution:
+
+| Need | Solution | Example |
+|------|----------|---------|
+| One-off action | **Script** + command | Markdown to PDF → `/pdf` |
+| Something checked regularly | **Web app** on Vercel | Crypto dashboard → live URL |
+| Background automation | **Cron script** | Morning weather briefing |
+
+It searches npm/GitHub for existing libraries, installs dependencies, writes tests, deploys, and hands you the URL.
+
+**Git snapshot after.** Full commit + push of the evolved state. Every evolution is a diffable pair.
+
+**Then OBOL introduces its upgrades:**
+
+```
+🪙 Evolution #4 complete.
+
+🆕 New capabilities:
+• bookmarks — Save and search URLs you've shared → /bookmarks
+• weather-brief — Morning weather for your city → runs automatically
+
+🚀 Deployed:
+• portfolio-tracker → https://portfolio-tracker-xi.vercel.app
+
+Refined voice, updated your project list, cleaned up 2 unused scripts.
+```
+
+### The Lifecycle
+
+```
+Day 1:   obol init → obol start → first conversation
+         → OBOL asks 2-3 questions, writes SOUL.md + USER.md
+         → post-setup hardens your VPS automatically
+
+Day 2:   Every 5 messages → Haiku extracts facts to vector memory
+
+Week 2:  Evolution #1 → Sonnet rewrites everything
+         → voice shifts from generic to personal
+         → old soul archived in evolution/
+
+Month 2: Evolution #4 → notices you check crypto daily
+         → builds a dashboard, deploys to Vercel
+         → adds /pdf because you kept asking for PDFs
+
+Month 6: evolution/ has 12 archived souls
+         → a readable timeline of how your bot evolved from
+         blank slate to something with real opinions, quirks,
+         and a dynamic unique to you
+```
+
+**The same codebase deployed by two different people produces two completely different bots within a week.**
+
+### Background Tasks
+
+Heavy work runs in the background. The main conversation stays responsive.
+
+```
+You: "research the best coworking spaces in Barcelona"
+OBOL: "On it 🪙"
+
+[30s] ⏳ Found 15 spaces, filtering by reviews...
+[60s] ⏳ Narrowed to top 7, checking prices...
+
+You: "what time is it?"
+OBOL: "11:42 PM CET"
+
+[90s] ✅ Done! Here are the top 5 coworking spaces: ...
+```
+
+## Setup
+
+### CLI (6 inputs, ~2 minutes)
+
+```
+$ obol init
+
+🪙 OBOL — Your AI, your rules.
+
+─── Anthropic ───
+  API key: ****
+─── Telegram ───
+  Bot token: ****
+  Your user ID: 123456789
+─── Supabase ───
+  Access token: ****
+─── GitHub ───
+  Token: ****
+─── Vercel ───
+  Token: ****
+─── Identity ───
+  Your name: Jo
+  Bot name: OBOL
+
+🪙 Done! Run: obol start
+```
+
+### First Conversation
+
+Send your first message. OBOL introduces itself, asks 2-3 questions, then writes its own SOUL.md and USER.md. After that, it silently hardens your VPS:
+
+| Task | What |
+|------|------|
+| GPG + pass | Encrypted secret storage, plaintext wiped |
+| pm2 | Process manager with auto-restart |
+| Swap | 2GB if RAM < 2GB |
+| SSH | Port 2222, key-only, max 3 retries |
+| fail2ban | 1h ban after 3 failures |
+| Firewall | UFW deny-all, allow 2222 |
+| Updates | Unattended security upgrades |
+| Kernel | SYN cookies, no ICMP redirects |
+
+> ⚠️ After first run, SSH moves to port 2222: `ssh -p 2222 root@YOUR_IP`
+
+## Resilience
+
+OBOL is designed to stay alive without babysitting:
+
+- **Global error handler** — individual message failures don't crash the bot
+- **Polling auto-restart** — exponential backoff (1s → 60s) with up to 10 retries on network/API failures
+- **Graceful shutdown** — clean exit on SIGINT/SIGTERM for pm2/systemd compatibility
+- **Evolution rollback** — if refactored scripts break tests, the old scripts are restored automatically
+
+## Configuration
+
+After `obol init`, config lives in `~/.obol/config.json`:
+
+```json
+{
+  "evolution": {
+    "exchanges": 100
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `evolution.exchanges` | 100 | Messages between evolution cycles. Increase to reduce API costs. |
+
+## Telegram Commands
+
+```
+/new     — Fresh conversation
+/tasks   — Running background tasks
+/status  — Uptime and memory stats
+/backup  — Trigger GitHub backup
+/clean   — Audit workspace, remove rogue files, fix misplaced items
+```
+
+Everything else is natural conversation.
+
+## CLI
+
+```bash
+obol init              # Setup wizard
+obol init --restore    # Restore from GitHub backup
+obol start             # Foreground
+obol start -d          # Daemon (pm2)
+obol stop              # Stop
+obol logs              # Tail logs
+obol status            # Status
+obol backup            # Manual backup
+```
+
+## Directory Structure
+
+```
+~/.obol/
+├── config.json        # Credentials (migrated to pass after setup)
+├── personality/
+│   ├── SOUL.md        # Bot personality (rewritten every 100 exchanges)
+│   ├── USER.md        # Owner profile (rewritten every 100 exchanges)
+│   ├── AGENTS.md      # Operational knowledge (rewritten every 100 exchanges)
+│   └── evolution/     # Archived previous souls
+├── scripts/           # Deterministic utility scripts
+├── tests/             # Test suite (gates refactors)
+├── commands/          # Command definitions
+├── apps/              # Web apps (deployed to Vercel)
+└── logs/
+```
+
+## Backup & Restore
+
+OBOL commits to GitHub:
+- **Daily** at 3 AM (personality, scripts, tests, commands, apps)
+- **Before and after** every evolution cycle (diffable pairs)
+
+Memory lives in Supabase (survives independently).
+
+Restore on a new VPS:
+
+```bash
+npm install -g obol
+obol init --restore    # Clones brain from GitHub
+obol start -d
+```
+
+## Costs
+
+| Service | Cost |
+|---------|------|
+| VPS (DigitalOcean) | ~$6/mo |
+| Anthropic API | ~$100-200/mo on max plans |
+| Supabase | Free tier |
+| GitHub | Free |
+| Vercel | Free tier |
+| Embeddings | Free (local) |
+
+## Requirements
+
+- Node.js ≥ 18
+- Anthropic API key
+- Telegram bot token
+- Supabase account (free tier)
+- GitHub account
+- Vercel account (free tier)
+
+**[→ Full DigitalOcean deployment guide](docs/DEPLOY.md)**
+
+## OBOL vs OpenClaw
+
+| | **OBOL** | **OpenClaw** |
+|---|---|---|
+| **Setup** | ~10 min | 30-60 min |
+| **Channels** | Telegram | Telegram, Discord, Signal, WhatsApp, IRC, Slack, iMessage + more |
+| **LLM** | Anthropic only | Anthropic, OpenAI, Google, Groq, local |
+| **Personality** | Self-evolving + self-healing + self-extending | Static (manual) |
+| **Architecture** | Single process | Gateway daemon + sessions |
+| **Security** | Auto-hardens on first run | Manual |
+| **Model routing** | Automatic (Haiku) | Manual overrides |
+| **Background tasks** | Built-in with check-ins | Sub-agent spawning |
+| **Group chats** | — | Full support |
+| **Cron** | Basic node-cron | Full scheduler |
+| **Cost** | ~$9/mo | ~$9/mo+ |
+
+Different tools, different philosophies. Pick what fits.
+
+## License
+
+MIT

package/bin/obol.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('obol')
+  .description('🪙 OBOL — Your AI, your rules.')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Set up your OBOL instance')
+  .option('--restore', 'Restore from GitHub backup')
+  .action(async (opts) => {
+    const { init } = require('../src/cli/init');
+    await init(opts);
+  });
+
+program
+  .command('start')
+  .description('Start the bot')
+  .option('-d, --daemon', 'Run as background daemon')
+  .action(async (opts) => {
+    const { start } = require('../src/cli/start');
+    await start(opts);
+  });
+
+program
+  .command('stop')
+  .description('Stop the bot')
+  .action(async () => {
+    const { stop } = require('../src/cli/stop');
+    await stop();
+  });
+
+program
+  .command('logs')
+  .description('Tail bot logs')
+  .option('-n, --lines <n>', 'Number of lines', '50')
+  .action(async (opts) => {
+    const { logs } = require('../src/cli/logs');
+    await logs(opts);
+  });
+
+program
+  .command('status')
+  .description('Show bot status')
+  .action(async () => {
+    const { status } = require('../src/cli/status');
+    await status();
+  });
+
+program
+  .command('backup')
+  .description('Manual backup to GitHub')
+  .action(async () => {
+    const { backup } = require('../src/cli/backup');
+    await backup();
+  });
+
+program.parse();

package/docs/DEPLOY.md

@@ -0,0 +1,277 @@
+# Deploy OBOL on DigitalOcean
+
+Complete guide: from zero to a running AI assistant in ~10 minutes.
+
+## 1. Create a Droplet
+
+Go to [cloud.digitalocean.com](https://cloud.digitalocean.com) → **Create** → **Droplets**
+
+| Setting | Value |
+|---------|-------|
+| **Region** | Pick the closest to you (e.g. Amsterdam, Frankfurt) |
+| **Image** | Ubuntu 24.04 LTS |
+| **Size** | Basic → Regular → **$6/mo** (1 vCPU, 1GB RAM, 25GB SSD) |
+| **Auth** | SSH key (recommended) or password |
+| **Hostname** | `obol` |
+
+> 💡 The $6 droplet is enough. OBOL is a single Node.js process. The embedding model uses ~200MB RAM on first load, then stays resident. If you plan to run heavy scripts, go $12/mo (2GB RAM).
+
+Click **Create Droplet**. Copy the IP address.
+
+## 2. Connect via SSH
+
+```bash
+ssh root@YOUR_DROPLET_IP
+```
+
+> ⚠️ **After first run**, OBOL hardens your server automatically — including moving SSH to port 2222. From then on:
+> ```bash
+> ssh -p 2222 root@YOUR_DROPLET_IP
+> ```
+
+## 3. Install Node.js
+
+```bash
+# Install Node.js 22 LTS via NodeSource
+curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
+apt-get install -y nodejs
+
+# Verify
+node -v   # v22.x.x
+npm -v    # 10.x.x
+```
+
+## 4. Install OBOL
+
+```bash
+npm install -g obol
+```
+
+## 5. Prepare Your Accounts
+
+Before running `obol init`, have these ready:
+
+### Anthropic API Key
+1. Go to [console.anthropic.com](https://console.anthropic.com)
+2. Sign up / log in
+3. Go to **API Keys** → **Create Key**
+4. Copy the key (starts with `sk-ant-`)
+5. Add credits ($5 minimum) — go to **Billing** → **Add funds**
+
+### Telegram Bot Token
+1. Open Telegram, search for **@BotFather**
+2. Send `/newbot`
+3. Choose a name (e.g. "My OBOL")
+4. Choose a username (e.g. `my_obol_bot`)
+5. Copy the token (looks like `7123456789:AAF...`)
+
+### Your Telegram User ID
+1. Open Telegram, search for **@userinfobot**
+2. Send `/start`
+3. It replies with your numeric ID (e.g. `206639616`)
+
+### Supabase Access Token
+1. Go to [supabase.com](https://supabase.com) → sign up (free)
+2. Go to [supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens)
+3. **Generate new token** → name it "obol" → copy it
+
+### Vercel Token
+1. Go to [vercel.com](https://vercel.com) → sign up (free)
+2. Go to [vercel.com/account/tokens](https://vercel.com/account/tokens)
+3. **Create** → name it "obol" → copy the token
+
+### GitHub Token
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
+2. **Generate new token (classic)**
+3. Select scope: `repo`
+4. Copy the token
+
+## 6. Run Setup
+
+```bash
+obol init
+```
+
+The wizard walks you through everything:
+
+```
+🪙 OBOL — Your AI, your rules.
+
+─── Anthropic ───
+  Paste your Anthropic API key: ****
+  ✅ Anthropic configured
+
+─── Telegram ───
+  Paste BotFather token: ****
+  ✅ Telegram configured
+
+─── Memory (Supabase) ───
+  Supabase setup: Create new project
+  Supabase access token: ****
+  Creating project... ✅
+  Waiting for project to initialize (~60s)... ✅
+  Running migrations... ✅
+
+─── GitHub (backup) ───
+  Set up GitHub backup? Yes
+  GitHub token: ****
+  Creating private repo: yourname/obol-brain... ✅
+
+─── Identity ───
+  Your name: Jo
+  Bot name: Mr. Meeseeks
+  Your Telegram user ID: 206639616
+
+🪙 Done! Run: obol start
+```
+
+## 7. Test It (Foreground)
+
+```bash
+obol start
+```
+
+Go to Telegram, open your bot, send a message. You should get a response from Claude.
+
+Press `Ctrl+C` to stop.
+
+## 8. Run as Daemon
+
+```bash
+obol start -d
+```
+
+Check it's running:
+
+```bash
+obol status
+obol logs
+```
+
+## 9. Keep It Running (pm2)
+
+pm2 keeps OBOL alive, auto-restarts on crash, and survives reboots:
+
+```bash
+# Install pm2 globally
+npm install -g pm2
+
+# Start OBOL with pm2
+pm2 start $(which obol) --name obol -- start
+
+# Auto-start on boot
+pm2 startup
+pm2 save
+
+# Useful commands
+pm2 status          # See running processes
+pm2 logs obol       # Tail logs
+pm2 restart obol    # Restart
+pm2 stop obol       # Stop
+pm2 monit           # Live monitoring dashboard
+```
+
+That's it — OBOL auto-starts on boot and restarts if it crashes.
+
+## 10. Customize Your Bot
+
+SSH in and edit the personality files:
+
+```bash
+nano ~/.obol/personality/SOUL.md    # Bot personality
+nano ~/.obol/personality/USER.md    # About you
+nano ~/.obol/personality/AGENTS.md  # How it works
+```
+
+Restart after changes:
+
+```bash
+pm2 restart obol
+```
+
+## Costs
+
+| Service | Cost |
+|---------|------|
+| DigitalOcean droplet | $6/mo |
+| Anthropic API (Claude Sonnet) | ~$3/mo for moderate use |
+| Supabase | Free (500MB) |
+| GitHub | Free (private repos) |
+| Vercel | Free (100GB bandwidth) |
+| Embeddings | Free (runs locally) |
+| **Total** | **~$9/mo** |
+
+## Updating
+
+```bash
+npm update -g obol
+pm2 restart obol
+```
+
+## Backup & Restore
+
+OBOL automatically backs up to GitHub daily at 3 AM (personality, scripts, commands, daily notes).
+
+To restore on a new droplet:
+
+```bash
+npm install -g obol
+obol init --restore
+# Paste GitHub token → it clones your brain
+# Re-enter Telegram token + Anthropic key
+obol start -d
+```
+
+## Troubleshooting
+
+### Can't SSH after first run
+OBOL moves SSH to port 2222 during security hardening:
+```bash
+ssh -p 2222 root@YOUR_DROPLET_IP
+```
+
+### Bot doesn't respond
+```bash
+obol status          # Is it running?
+obol logs            # Check for errors
+```
+
+### "Not authorized" / bot ignores messages
+Check that your Telegram user ID is correct in `~/.obol/config.json`:
+```bash
+cat ~/.obol/config.json | grep allowedUsers
+```
+
+### Memory not working
+```bash
+# Test Supabase connection
+curl -s -H "apikey: YOUR_KEY" https://YOUR_PROJECT.supabase.co/rest/v1/obol_memory?limit=1
+```
+
+### Out of memory (OOM)
+Upgrade to 2GB droplet:
+```bash
+# In DigitalOcean dashboard: Droplet → Resize → 2GB ($12/mo)
+```
+
+Or add swap:
+```bash
+fallocate -l 2G /swapfile
+chmod 600 /swapfile
+mkswap /swapfile
+swapon /swapfile
+echo '/swapfile none swap sw 0 0' >> /etc/fstab
+```
+
+### Firewall
+OBOL only makes outbound connections (Telegram, Anthropic, Supabase). No ports need to be opened. But basic hardening is good practice:
+
+```bash
+ufw allow 2222/tcp
+ufw enable
+```
+OBOL does this automatically during post-setup.
+
+---
+
+*That's it. One droplet, one process, one bot. 🪙*