obol-ai 0.1.2 → 0.1.3

package/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git push:*)",
+      "Bash(for f in src/*.js src/cli/*.js src/db/*.js)",
+      "Bash(do node -c \"$f\")",
+      "Bash(echo:*)",
+      "Bash(done)",
+      "Bash(git -C /Users/jovinkenroye/Sites/obol log --oneline -15)",
+      "Bash(git -C /Users/jovinkenroye/Sites/obol diff --stat HEAD)",
+      "Bash(gh api:*)",
+      "Bash(grep:*)",
+      "Bash(/Users/jovinkenroye/Sites/obol/tests/mock-grammy.test.js:*)",
+      "Bash(git -C /Users/jovinkenroye/Sites/obol diff --stat)",
+      "Bash(git -C /Users/jovinkenroye/Sites/obol add:*)",
+      "Bash(git -C:*)"
+    ]
+  }
+}

package/README.md

@@ -4,7 +4,7 @@
 
 **A self-healing, self-evolving AI agent.** Install it, talk to it, and it becomes yours.
 
-One process. One chat. One brain that grows.
+One process. Multiple users. Each brain grows independently.
 
 ---
 
@@ -26,10 +26,12 @@ One process. One chat. One brain that grows.
 
 ## 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.
+OBOL is an AI agent that evolves its own personality, rewrites its own code, tests its changes, and fixes what breaks — all from Telegram 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.
 
+One bot, multiple users. Each allowed Telegram user gets a fully isolated context — their own personality, memory, evolution cycle, workspace, and first-run experience. User A's personality drift, scripts, and memories never leak into User B's. Everything runs in a single process with shared API credentials.
+
 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.
@@ -42,7 +44,7 @@ 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.
+The init wizard walks you through everything — credentials are validated inline, and your Telegram ID is auto-detected. OBOL handles the rest.
 
 ## How It Works
 
@@ -173,7 +175,7 @@ Month 6: evolution/ has 12 archived souls
          and a dynamic unique to you
 ```
 
-**The same codebase deployed by two different people produces two completely different bots within a week.**
+**Two users on the same bot produce two completely different personalities within a week.**
 
 ### Background Tasks
 
@@ -192,36 +194,152 @@ OBOL: "11:42 PM CET"
 [90s] ✅ Done! Here are the top 5 coworking spaces: ...
 ```
 
+## Multi-User Architecture
+
+One Telegram bot token, one Node.js process, full per-user isolation.
+
+```
+Telegram bot (single token, single poll)
+      ↓
+Auth middleware (allowedUsers check)
+      ↓
+Router: ctx.from.id → tenant context
+      ↓
+┌─────────────────┐  ┌─────────────────┐
+│ User 206639616  │  │ User 789012345  │
+│ personality/    │  │ personality/    │
+│ scripts/        │  │ scripts/        │
+│ memory (DB)     │  │ memory (DB)     │
+│ evolution       │  │ evolution       │
+└─────────────────┘  └─────────────────┘
+```
+
+### What's shared vs isolated
+
+| Shared (one copy) | Isolated (per user) |
+|---|---|
+| Telegram bot token | Personality (SOUL.md, USER.md, AGENTS.md) |
+| Anthropic API key | Vector memory (scoped by user_id in DB) |
+| Supabase connection | Message history (scoped by user_id in DB) |
+| GitHub token | Evolution cycle + state |
+| Vercel token | Scripts, tests, commands, apps |
+| VPS hardening | Workspace directory (`~/.obol/users/{id}/`) |
+| Process manager (pm2) | First-run onboarding experience |
+| | GitHub backup (per-user repo dir) |
+
+### Tenant routing
+
+When a message arrives, OBOL looks up the sender's Telegram user ID and lazily creates (or retrieves from cache) their tenant context — a Claude instance, memory connection, message log, background runner, and personality, all scoped to that user's directory and DB namespace. No cross-contamination between users.
+
+### Workspace isolation
+
+Each user's tools (shell exec, file read/write) are sandboxed to their workspace directory. A user can't read or write files outside `~/.obol/users/{their-id}/` (with `/tmp` as the only escape hatch). Shell commands run with `cwd` set to the user's workspace.
+
+### Secret namespacing (pass)
+
+When users store secrets via the `pass` encrypted store, each user gets their own namespace:
+
+| Scope | Prefix | Example |
+|-------|--------|---------|
+| Shared bot credentials | `obol/` | `obol/anthropic-key` |
+| User secrets | `obol/users/{id}/` | `obol/users/206639616/gmail-key` |
+
+### Adding users
+
+1. Add their Telegram user ID to `allowedUsers` in `~/.obol/config.json` (or run `obol config`)
+2. Restart the bot
+3. They message the bot → OBOL creates their workspace, runs first-run onboarding, and writes their own SOUL.md + USER.md
+
+Each new user starts fresh. Their bot evolves independently from every other user's.
+
+### Bridge (couples / roommates / teams)
+
+When two users share the same OBOL instance, their agents can talk to each other.
+
+```
+User A: "what does Jo want for dinner tonight?"
+Agent A: → bridge_ask → Agent B (one-shot, no tools, no history)
+Agent B: "Jo mentioned craving Thai food earlier today"
+Agent A: "Jo's been wanting Thai — maybe suggest pad see ew?"
+```
+
+```
+User A: "remind Jo I'll be home late"
+Agent A: → bridge_tell → stores in Agent B's memory + Telegram notification
+Jo gets: "🪙 Message from your partner's agent: I'll be home late"
+```
+
+Two tools:
+
+| Tool | Direction | What happens |
+|------|-----------|--------------|
+| `bridge_ask` | A → B → A | Query the partner's agent. One-shot Sonnet call with partner's personality + memories. No tools, no history, no recursion risk. |
+| `bridge_tell` | A → B | Send a message to the partner. Stored in their memory (importance 0.6) + Telegram notification. Their agent picks it up as context in future conversations. |
+
+The partner always gets notified when their agent is contacted. Privacy rules apply — the responding agent gives summaries, never raw data or secrets.
+
+Enable during `obol init` (auto-prompted when 2+ users are added) or toggle later with `obol config` → Bridge.
+
+### Legacy migration
+
+Upgrading from single-user? It's automatic. On first boot, if `~/.obol/users/` doesn't exist but personality files do, OBOL migrates everything (files + DB records) to the first allowed user's directory. No manual steps needed.
+
 ## Setup
 
-### CLI (6 inputs, ~2 minutes)
+### CLI (~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 ───
+─── Step 1/7: Anthropic (AI brain) ───
+  Anthropic API key: ****
+  Validating Anthropic... ✅ Key valid
+
+─── Step 2/7: Telegram (chat interface) ───
+  Telegram bot token: ****
+  Validating Telegram... ✅ Bot: @my_obol_bot
+
+─── Step 3/7: Supabase (memory) ───
+  Supabase setup: Use existing project
+  Project URL or ID: ****
+  Service role key: ****
+  Validating Supabase... ✅ Connected
+
+─── Step 4/7: GitHub (backup) ───
+  GitHub token: ****
+  ✅ Created yourname/obol-brain (private)
+
+─── Step 5/7: Vercel (deploy sites) ───
+  Vercel token: ****
+  Validating Vercel... ✅ Token valid
+
+─── Step 6/7: Identity ───
   Your name: Jo
   Bot name: OBOL
 
-🪙 Done! Run: obol start
+─── Step 7/7: Access control ───
+  Found users who messaged this bot:
+    206639616 — Jo (@jo)
+  Use this user? Yes
+
+🪙 Done! Setup complete.
+
+  Next steps:
+    obol start      Start the bot
+    obol start -d   Start as background daemon
+    obol config     Edit configuration later
+    obol status     Check bot status
 ```
 
+Every credential is validated inline — bad keys are caught before you start the bot. If validation fails, you can continue and fix later with `obol config`.
+
+For Telegram user IDs, OBOL auto-detects by checking who messaged the bot. Just send it a message before running init.
+
 ### 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:
+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 (Linux only — skipped on macOS/Windows):
 
 | Task | What |
 |------|------|
@@ -247,19 +365,19 @@ OBOL is designed to stay alive without babysitting:
 
 ## Configuration
 
-After `obol init`, config lives in `~/.obol/config.json`:
+Edit config interactively:
 
-```json
-{
-  "evolution": {
-    "exchanges": 100
-  }
-}
+```bash
+obol config
 ```
 
+Or edit `~/.obol/config.json` directly:
+
 | Key | Default | Description |
 |-----|---------|-------------|
-| `evolution.exchanges` | 100 | Messages between evolution cycles. Increase to reduce API costs. |
+| `evolution.exchanges` | 100 | Messages between evolution cycles |
+| `heartbeat` | false | Enable proactive check-ins |
+| `bridge.enabled` | false | Let user agents query each other (requires 2+ users) |
 
 ## Telegram Commands
 
@@ -276,12 +394,14 @@ Everything else is natural conversation.
 ## CLI
 
 ```bash
-obol init              # Setup wizard
+obol init              # Setup wizard (validates credentials inline)
 obol init --restore    # Restore from GitHub backup
+obol init --reset      # Erase config and re-run setup
+obol config            # Edit configuration interactively
 obol start             # Foreground
 obol start -d          # Daemon (pm2)
-obol stop              # Stop
-obol logs              # Tail logs
+obol stop              # Stop (pm2 or PID fallback)
+obol logs              # Tail logs (pm2 or log file fallback)
 obol status            # Status
 obol backup            # Manual backup
 ```
@@ -290,19 +410,24 @@ obol backup            # Manual backup
 
 ```
 ~/.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)
+├── config.json                    # Shared credentials + allowedUsers
+├── users/
+│   └── <telegram-user-id>/        # Per-user isolated context
+│       ├── personality/
+│       │   ├── SOUL.md            # Bot personality (rewritten every 100 exchanges)
+│       │   ├── USER.md            # Owner profile (rewritten every 100 exchanges)
+│       │   ├── AGENTS.md          # Operational knowledge
+│       │   └── evolution/         # Archived previous souls
+│       ├── scripts/               # Deterministic utility scripts
+│       ├── tests/                 # Test suite (gates refactors)
+│       ├── commands/              # Command definitions
+│       ├── apps/                  # Web apps (deployed to Vercel)
+│       └── logs/
 └── logs/
 ```
 
+Each allowed Telegram user gets their own isolated context — separate personality, memory namespace, evolution cycle, and first-run experience. One bot process, full per-user isolation.
+
 ## Backup & Restore
 
 OBOL commits to GitHub:
@@ -349,6 +474,7 @@ obol start -d
 | **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) |
+| **Multi-user** | Full per-user isolation (one process) | Per-channel config |
 | **Architecture** | Single process | Gateway daemon + sessions |
 | **Security** | Auto-hardens on first run | Manual |
 | **Model routing** | Automatic (Haiku) | Manual overrides |

package/bin/obol.js

@@ -14,11 +14,20 @@ program
   .command('init')
   .description('Set up your OBOL instance')
   .option('--restore', 'Restore from GitHub backup')
+  .option('--reset', 'Erase config and re-run setup')
   .action(async (opts) => {
     const { init } = require('../src/cli/init');
     await init(opts);
   });
 
+program
+  .command('config')
+  .description('View and edit configuration')
+  .action(async () => {
+    const { config } = require('../src/cli/config');
+    await config();
+  });
+
 program
   .command('start')
   .description('Start the bot')

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "obol-ai",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Self-evolving AI assistant that learns, remembers, and acts on its own. Persistent vector memory, self-rewriting personality, proactive heartbeats.",
   "main": "src/index.js",
   "bin": {
-    "obol": "./bin/obol.js"
+    "obol": "bin/obol.js"
   },
   "scripts": {
     "start": "node src/index.js",
-    "test": "node tests/run.js"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "ai",
@@ -24,13 +25,16 @@
     "@anthropic-ai/sdk": "^0.39.0",
     "@supabase/supabase-js": "^2.49.1",
     "@xenova/transformers": "^2.17.2",
-    "grammy": "^1.35.0",
     "commander": "^13.1.0",
+    "grammy": "^1.35.0",
     "inquirer": "^8.2.6",
-    "open": "^10.1.0",
-    "node-cron": "^3.0.3"
+    "node-cron": "^3.0.3",
+    "open": "^8.4.2"
   },
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
   }
 }

package/src/background.js

@@ -35,15 +35,11 @@ class BackgroundRunner {
 
     this.tasks.set(taskId, taskState);
 
-    // Run the task
-    const promise = this._runTask(claude, task, taskState, ctx, memory);
-
-    taskState.promise = promise;
-
-    // Start check-in timer
+    // Start check-in timer before running task to avoid leak if task throws immediately
     taskState.checkInTimer = setInterval(async () => {
       if (taskState.status !== 'running') {
         clearInterval(taskState.checkInTimer);
+        taskState.checkInTimer = null;
         return;
       }
 
@@ -51,6 +47,10 @@ class BackgroundRunner {
       await this._checkIn(claude, taskState, ctx, elapsed);
     }, CHECK_IN_INTERVAL);
 
+    // Run the task
+    const promise = this._runTask(claude, task, taskState, ctx, memory);
+    taskState.promise = promise;
+
     return taskId;
   }
 
@@ -73,7 +73,8 @@ TASK: ${task}`;
 
       taskState.status = 'done';
       taskState.result = result;
-      clearInterval(taskState.checkInTimer);
+      if (taskState.checkInTimer) { clearInterval(taskState.checkInTimer); taskState.checkInTimer = null; }
+      claude.clearHistory(`bg-${taskState.id}`);
 
       // Send final result
       const elapsed = Math.floor((Date.now() - taskState.startedAt) / 1000);
@@ -95,7 +96,7 @@ TASK: ${task}`;
     } catch (e) {
       taskState.status = 'error';
       taskState.error = e.message;
-      clearInterval(taskState.checkInTimer);
+      if (taskState.checkInTimer) { clearInterval(taskState.checkInTimer); taskState.checkInTimer = null; }
 
       await ctx.reply(`⚠️ Background task failed: ${e.message}`).catch(() => {});
     }
@@ -109,14 +110,17 @@ TASK: ${task}`;
 Give a ONE LINE progress update (emoji + what's happening). Be specific about what you've found/done so far. Example: "⏳ Found 8 clinics, comparing ratings and prices..."`;
 
       // Use a separate quick call — don't interfere with the main task
+      const checkInChatId = `checkin-${taskState.id}`;
       const update = await claude.chat(checkInPrompt, {
-        chatId: `checkin-${taskState.id}-${elapsed}`,
+        chatId: checkInChatId,
         userName: 'CheckIn',
       });
 
       if (update && update.trim()) {
         await ctx.reply(update.trim()).catch(() => {});
       }
+
+      claude.clearHistory(checkInChatId);
     } catch {
       // Check-in failed — not critical, skip it
     }

package/src/backup.js

@@ -5,14 +5,18 @@ const fs = require('fs');
 const { OBOL_DIR } = require('./config');
 
 function setupBackup(githubConfig) {
-  const { token, username, repo } = githubConfig;
-  const backupDir = path.join(OBOL_DIR, '.backup-repo');
+  const { listUsers } = require('./config');
 
-  // Daily backup at 3 AM
   cron.schedule('0 3 * * *', async () => {
     try {
-      await runBackup(githubConfig);
-      console.log(`[${new Date().toISOString()}] Backup complete`);
+      const users = listUsers();
+      for (const userId of users) {
+        const userDir = path.join(OBOL_DIR, 'users', userId);
+        await runBackup(githubConfig, null, userDir).catch(e =>
+          console.error(`[${new Date().toISOString()}] Backup failed for user ${userId}: ${e.message}`)
+        );
+      }
+      console.log(`[${new Date().toISOString()}] Backup complete (${users.length} users)`);
     } catch (e) {
       console.error(`[${new Date().toISOString()}] Backup failed: ${e.message}`);
     }
@@ -21,33 +25,31 @@ function setupBackup(githubConfig) {
   console.log('  ✅ GitHub backup scheduled (daily 3 AM)');
 }
 
-async function runBackup(githubConfig, commitMessage) {
+async function runBackup(githubConfig, commitMessage, userDir) {
   const { token, username, repo } = githubConfig;
-  const backupDir = path.join(OBOL_DIR, '.backup-repo');
+  const baseDir = userDir || OBOL_DIR;
+  const backupDir = path.join(baseDir, '.backup-repo');
   const repoUrl = `https://${token}@github.com/${username}/${repo}.git`;
 
-  // Clone or pull
   if (!fs.existsSync(path.join(backupDir, '.git'))) {
-    execSync(`git clone ${repoUrl} ${backupDir}`, { stdio: 'pipe' });
+    execSync(`git clone ${repoUrl} "${backupDir}"`, { stdio: 'pipe' });
   } else {
     execSync('git pull', { cwd: backupDir, stdio: 'pipe' });
   }
 
-  // Set git identity
   execSync('git config user.name "OBOL"', { cwd: backupDir });
   execSync('git config user.email "obol@backup"', { cwd: backupDir });
 
-  // Sync files (exclude secrets)
   const syncDirs = ['personality', 'scripts', 'tests', 'commands', 'apps'];
   for (const dir of syncDirs) {
-    const src = path.join(OBOL_DIR, dir);
+    const src = path.join(baseDir, dir);
     const dst = path.join(backupDir, dir);
     if (fs.existsSync(src)) {
-      execSync(`mkdir -p ${dst} && cp -r ${src}/* ${dst}/ 2>/dev/null || true`, { stdio: 'pipe' });
+      fs.mkdirSync(dst, { recursive: true });
+      fs.cpSync(src, dst, { recursive: true, force: true });
     }
   }
 
-  // Commit and push
   execSync('git add -A', { cwd: backupDir, stdio: 'pipe' });
 
   try {
@@ -55,11 +57,12 @@ async function runBackup(githubConfig, commitMessage) {
     if (status.trim()) {
       const date = new Date().toISOString().slice(0, 10);
       const msg = commitMessage || `backup: ${date}`;
-      execSync(`git commit -m "${msg}"`, { cwd: backupDir, stdio: 'pipe' });
+      const { execFileSync } = require('child_process');
+      execFileSync('git', ['commit', '-m', msg], { cwd: backupDir, stdio: 'pipe' });
       execSync('git push', { cwd: backupDir, stdio: 'pipe' });
     }
-  } catch {
-    // Nothing to commit
+  } catch (e) {
+    console.error('[backup] Commit/push failed:', e.message);
   }
 }