obol-ai 0.2.1 → 0.2.3

package/README.md

@@ -30,7 +30,7 @@ OBOL is an AI agent that evolves its own personality, rewrites its own code, tes
 
 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.
+One bot, multiple users. Each allowed Telegram user gets a fully isolated context — their own personality, memory, evolution cycle, and workspace. 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.
 
@@ -156,7 +156,7 @@ Refined voice, updated your project list, cleaned up 2 unused scripts.
 
 ```
 Day 1:   obol init → obol start → first conversation
-         → OBOL asks 2-3 questions, writes SOUL.md + USER.md
+         → OBOL responds naturally from message one
          → post-setup hardens your VPS automatically
 
 Day 2:   Every 5 messages → Haiku extracts facts to vector memory
@@ -224,8 +224,7 @@ Router: ctx.from.id → tenant context
 | 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) |
+| Process manager (pm2) | GitHub backup (per-user repo dir) |
 
 ### Tenant routing
 
@@ -244,11 +243,13 @@ When users store secrets via the `pass` encrypted store, each user gets their ow
 | Shared bot credentials | `obol/` | `obol/anthropic-key` |
 | User secrets | `obol/users/{id}/` | `obol/users/206639616/gmail-key` |
 
+Users manage their own secrets via Telegram: `/secret set <key> <value>` (message auto-deleted for safety), `/secret list`, `/secret remove <key>`. The agent can also read/write secrets via tools for scripts that need API keys at runtime.
+
 ### 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
+3. They message the bot → OBOL creates their workspace and starts responding immediately. Personality files are created during their first evolution cycle.
 
 Each new user starts fresh. Their bot evolves independently from every other user's.
 
@@ -339,7 +340,7 @@ For Telegram user IDs, OBOL auto-detects by checking who messaged the bot. Just
 
 ### 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 hardens your VPS and reports progress directly in the Telegram chat (Linux only — skipped on macOS/Windows):
+Send your first message. OBOL responds naturally — no onboarding flow, it works from message one. Personality files (SOUL.md, USER.md) are created during the first evolution cycle. After first boot, it hardens your VPS and reports progress directly in the Telegram chat (Linux only — skipped on macOS/Windows):
 
 | Task | What |
 |------|------|
@@ -445,11 +446,18 @@ Or edit `~/.obol/config.json` directly:
 ## 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
+/new        — Fresh conversation
+/memory     — Search or view memory stats
+/recent     — Last 10 memories
+/today      — Today's memories
+/tasks      — Running background tasks
+/status     — Bot status, uptime, evolution progress, traits
+/backup     — Trigger GitHub backup
+/clean      — Audit workspace, remove rogue files, fix misplaced items
+/traits     — View or adjust personality traits (0-100)
+/secret     — Manage per-user encrypted secrets
+/evolution  — Evolution progress
+/help       — Show available commands
 ```
 
 Everything else is natural conversation.
@@ -468,6 +476,7 @@ obol logs              # Tail logs (pm2 or log file fallback)
 obol status            # Status
 obol backup            # Manual backup
 obol upgrade           # Update to latest version
+obol delete            # Full VPS cleanup (removes all OBOL data)
 ```
 
 ## Directory Structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obol-ai",
-  "version": "0.2.1",
+  "version": "0.2.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": {
@@ -29,7 +29,8 @@
     "grammy": "^1.35.0",
     "inquirer": "^8.2.6",
     "node-cron": "^3.0.3",
-    "open": "^8.4.2"
+    "open": "^8.4.2",
+    "pdfkit": "^0.17.2"
   },
   "engines": {
     "node": ">=18"

package/src/claude.js

@@ -7,7 +7,7 @@ const { saveConfig, loadConfig, OBOL_DIR } = require('./config');
 const { execAsync, isAllowedUrl } = require('./sanitize');
 
 const MAX_EXEC_TIMEOUT = 120;
-const MAX_TOOL_ITERATIONS = 15;
+let MAX_TOOL_ITERATIONS = 100;
 
 const BLOCKED_EXEC_PATTERNS = [
   /\brm\s+(-[a-zA-Z]*f|-[a-zA-Z]*r|--force|--recursive)\b/,
@@ -124,6 +124,24 @@ async function ensureFreshToken(anthropicConfig) {
   }
 }
 
+function repairHistory(history) {
+  for (let i = 0; i < history.length; i++) {
+    const msg = history[i];
+    if (msg.role !== 'assistant' || !Array.isArray(msg.content)) continue;
+    const toolUseIds = msg.content.filter(b => b.type === 'tool_use').map(b => b.id);
+    if (toolUseIds.length === 0) continue;
+    const next = history[i + 1];
+    const hasResults = next?.role === 'user' && Array.isArray(next.content) &&
+      toolUseIds.every(id => next.content.some(b => b.type === 'tool_result' && b.tool_use_id === id));
+    if (!hasResults) {
+      const fakeResults = toolUseIds.map(id => ({
+        type: 'tool_result', tool_use_id: id, content: '[interrupted]',
+      }));
+      history.splice(i + 1, 0, { role: 'user', content: fakeResults });
+    }
+  }
+}
+
 function createClaude(anthropicConfig, { personality, memory, userDir = OBOL_DIR, bridgeEnabled }) {
   let client = createAnthropicClient(anthropicConfig);
 
@@ -151,7 +169,10 @@ function createClaude(anthropicConfig, { personality, memory, userDir = OBOL_DIR
     if (!histories.has(chatId)) histories.set(chatId, []);
     const history = histories.get(chatId);
 
-    // Ask Haiku if we need memory for this message
+    const verbose = context.verbose || false;
+    if (verbose) context.verboseLog = [];
+    const vlog = (msg) => { if (verbose) context.verboseLog.push(msg); };
+
     let memoryContext = '';
     if (memory) {
       try {
@@ -179,7 +200,8 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
           if (jsonStr) decision = JSON.parse(jsonStr);
         } catch {}
 
-        // Set model based on Haiku's decision
+        vlog(`[router] model=${decision.model || 'sonnet'} memory=${decision.need_memory || false}${decision.search_query ? ` query="${decision.search_query}"` : ''}`);
+
         if (decision.model === 'opus') {
           context._model = 'claude-opus-4-6';
         }
@@ -187,11 +209,9 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
         if (decision.need_memory) {
           const query = decision.search_query || userMessage;
 
-          // Today's context + semantic search
           const todayMemories = await memory.byDate('today', { limit: 3 });
           const semanticMemories = await memory.search(query, { limit: 3, threshold: 0.5 });
 
-          // Dedupe by ID
           const seen = new Set();
           const combined = [];
           for (const m of [...todayMemories, ...semanticMemories]) {
@@ -201,6 +221,8 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
             }
           }
 
+          vlog(`[memory] ${combined.length} memories found (${todayMemories.length} today, ${semanticMemories.length} semantic)`);
+
           if (combined.length > 0) {
             memoryContext = '\n\n[Relevant memories]\n' +
               combined.map(m => `- [${m.category}] ${m.content}`).join('\n');
@@ -208,6 +230,7 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
         }
       } catch (e) {
         console.error('[router] Memory/routing decision failed:', e.message);
+        vlog(`[router] ERROR: ${e.message}`);
       }
     }
 
@@ -215,9 +238,19 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
       history.shift();
       history.shift();
     }
-    if (history.length > 0 && history[0].role !== 'user') {
-      history.shift();
+    while (history.length > 0) {
+      const first = history[0];
+      if (first.role !== 'user') {
+        history.shift();
+        continue;
+      }
+      if (Array.isArray(first.content) && first.content.some(b => b.type === 'tool_result')) {
+        history.shift();
+        continue;
+      }
+      break;
     }
+    repairHistory(history);
 
     // Add user message with memory context
     const enrichedMessage = memoryContext
@@ -232,8 +265,8 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
       history.push({ role: 'user', content: enrichedMessage });
     }
 
-    // Call Claude — Haiku picks the model
     const model = context._model || 'claude-sonnet-4-6';
+    vlog(`[model] ${model} | history=${history.length} msgs`);
     const systemPrompt = baseSystemPrompt + `\nCurrent time: ${new Date().toISOString()}`;
     let response = await client.messages.create({
       model,
@@ -247,8 +280,15 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
     while (response.stop_reason === 'tool_use') {
       toolIterations++;
       if (toolIterations > MAX_TOOL_ITERATIONS) {
-        history.push({ role: 'assistant', content: response.content });
-        history.push({ role: 'user', content: 'You have used too many tool calls. Please provide a final response now based on what you have so far.' });
+        const bailoutContent = response.content;
+        history.push({ role: 'assistant', content: bailoutContent });
+        const bailoutResults = bailoutContent
+          .filter(b => b.type === 'tool_use')
+          .map(b => ({ type: 'tool_result', tool_use_id: b.id, content: '[max tool iterations reached]' }));
+        history.push({ role: 'user', content: [
+          ...bailoutResults,
+          { type: 'text', text: 'You have used too many tool calls. Please provide a final response now based on what you have so far.' },
+        ] });
         response = await client.messages.create({
           model,
           max_tokens: 4096,
@@ -264,6 +304,15 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
       const toolResults = [];
       for (const block of assistantContent) {
         if (block.type === 'tool_use') {
+          const inputSummary = block.name === 'exec' ? block.input.command :
+            block.name === 'write_file' ? block.input.path :
+            block.name === 'read_file' ? block.input.path :
+            block.name === 'memory_search' ? block.input.query :
+            block.name === 'memory_add' ? `[${block.input.category || 'fact'}]` :
+            block.name === 'web_fetch' ? block.input.url :
+            block.name === 'background_task' ? block.input.task?.substring(0, 60) :
+            JSON.stringify(block.input).substring(0, 80);
+          vlog(`[tool] ${block.name}: ${inputSummary}`);
           const result = await executeToolCall(block, memory, context);
           toolResults.push({
             type: 'tool_result',
@@ -284,11 +333,13 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
       });
     }
 
-    // Extract text response
     const textBlocks = response.content.filter(b => b.type === 'text');
     const replyText = textBlocks.map(b => b.text).join('\n');
 
-    // Add assistant response to history
+    if (response.usage) {
+      vlog(`[tokens] in=${response.usage.input_tokens} out=${response.usage.output_tokens}`);
+    }
+
     history.push({ role: 'assistant', content: response.content });
 
     return replyText;
@@ -310,7 +361,13 @@ Model: Use "sonnet" for most things (chat, simple questions, quick tasks, single
     }
   }
 
-  return { chat, client, reloadPersonality, clearHistory };
+  function injectHistory(chatId, role, content) {
+    if (!histories.has(chatId)) histories.set(chatId, []);
+    const history = histories.get(chatId);
+    history.push({ role, content });
+  }
+
+  return { chat, client, reloadPersonality, clearHistory, injectHistory };
 }
 
 function buildSystemPrompt(personality, userDir, opts = {}) {
@@ -392,6 +449,7 @@ Use the \`store_secret\`, \`read_secret\`, and \`list_secrets\` tools for all us
 These store secrets under the prefix \`${passPrefix}/\` in pass (or JSON fallback).
 
 Users can also manage secrets via Telegram: \`/secret set <key> <value>\` (message auto-deleted), \`/secret list\`, \`/secret remove <key>\`.
+Since users can store secrets via /secret outside your conversation, ALWAYS call \`list_secrets\` to check what's available before telling the user their credentials aren't stored.
 
 Shared bot credentials live under \`obol/\` — do NOT touch or re-create these:
 \`obol/anthropic-key\`, \`obol/telegram-token\`, \`obol/supabase-url\`, \`obol/supabase-key\`, \`obol/github-token\`, \`obol/vercel-token\`
@@ -589,6 +647,33 @@ function buildTools(memory, opts = {}) {
     },
   });
 
+  tools.push({
+    name: 'send_file',
+    description: 'Send a file to the user via Telegram (PDF, image, document, etc). Use after generating files the user requested.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the file to send' },
+        caption: { type: 'string', description: 'Optional caption for the file' },
+      },
+      required: ['path'],
+    },
+  });
+
+  tools.push({
+    name: 'telegram_ask',
+    description: 'Send a message to the user with inline keyboard buttons and wait for their tap. Use for human-in-the-loop decisions: confirmations, approvals, action selection. Returns the label of the button the user pressed, or "timeout" if they don\'t respond within the timeout.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'Question or prompt to show the user' },
+        options: { type: 'array', items: { type: 'string' }, description: 'Button labels (2-6 options, keep each label short)' },
+        timeout: { type: 'number', description: 'Seconds to wait for response (default 60)' },
+      },
+      required: ['message', 'options'],
+    },
+  });
+
   if (opts.bridgeEnabled) {
     const { buildBridgeTool, buildBridgeTellTool } = require('./bridge');
     tools.push(buildBridgeTool());
@@ -791,6 +876,23 @@ async function executeToolCall(toolUse, memory, context = {}) {
         return keys.join('\n');
       }
 
+      case 'send_file': {
+        const filePath = userDir ? resolveUserPath(input.path, userDir) : input.path;
+        if (!fs.existsSync(filePath)) return `File not found: ${filePath}`;
+        const telegramCtx = context.ctx;
+        if (!telegramCtx) return 'Cannot send files in this context.';
+        const { InputFile } = require('grammy');
+        await telegramCtx.replyWithDocument(new InputFile(filePath), {
+          caption: input.caption || undefined,
+        });
+        return `Sent: ${path.basename(filePath)}`;
+      }
+
+      case 'telegram_ask': {
+        if (!context.telegramAsk) return 'telegram_ask not available in this context.';
+        return await context.telegramAsk(input.message, input.options || [], input.timeout);
+      }
+
       case 'bridge_ask': {
         const { bridgeAsk } = require('./bridge');
         return await bridgeAsk(input.question, context.userId, context.config, context._notifyFn, input.partner_id);
@@ -809,4 +911,7 @@ async function executeToolCall(toolUse, memory, context = {}) {
   }
 }
 
-module.exports = { createClaude, createAnthropicClient };
+function getMaxToolIterations() { return MAX_TOOL_ITERATIONS; }
+function setMaxToolIterations(n) { MAX_TOOL_ITERATIONS = n; }
+
+module.exports = { createClaude, createAnthropicClient, getMaxToolIterations, setMaxToolIterations };

package/src/defaults/AGENTS.md

@@ -41,6 +41,19 @@ Use these tools instead of `exec` for storing/reading secrets — they bypass th
 
 Users can also manage secrets via Telegram: `/secret set <key> <value>` (message auto-deleted), `/secret list`, `/secret remove <key>`.
 
+### Send File (`send_file`)
+Send a file back to the user via Telegram. Use after generating PDFs, images, documents, or any file the user requested.
+
+### Ask User (`telegram_ask`)
+Send a message with inline keyboard buttons and wait for the user to tap one. Use for human-in-the-loop decisions before taking action.
+
+Examples:
+- After listing emails: `telegram_ask({message: "Open any of these?", options: ["#1 Google", "#2 LinkedIn", "#3 DeepLearning", "None"]})`
+- Before sending a reply: `telegram_ask({message: "Send this reply?", options: ["Send it", "Edit first", "Cancel"]})`
+- Before an irreversible action: `telegram_ask({message: "Archive all read emails?", options: ["Yes", "No"]})`
+
+Returns the tapped button label, or `"timeout"` if the user doesn't respond within the timeout (default 60s).
+
 ### Bridge (`bridge_ask`, `bridge_tell`)
 Only available if bridge is enabled. Communicate with partner's AI agent.
 
@@ -98,6 +111,19 @@ Rules:
 - Temporary files go in /tmp
 - If unsure where something belongs, ask
 
+## Self-Extending
+
+You can give yourself new capabilities by writing scripts and running them. If the user asks for something you don't have a dedicated tool for (PDF generation, image manipulation, data processing, etc.):
+
+1. **Write a script** to `scripts/` using `write_file`
+2. **Install dependencies** if needed via `exec`: `pip3 install fpdf2` or `npm install --prefix . pdfkit`
+3. **Run the script** via `exec`: `python3 scripts/generate-pdf.py` or `node scripts/generate-pdf.js`
+4. **Send the result** to the user with `send_file`
+
+Don't tell the user you can't do something — create the capability, then use it.
+
+Pre-installed npm packages you can `require()` in Node scripts: `pdfkit`
+
 ## Scripts & Service Integrations
 
 When building scripts (Gmail, Notion, APIs, etc.), prefer **Python**:
@@ -122,6 +148,29 @@ Use `background_task` when a request will take multiple steps:
 
 Pattern: acknowledge immediately ("On it"), spawn the task, let it work in the background.
 
+## Telegram Formatting
+
+You communicate via Telegram. Format responses for mobile readability.
+
+**Never use markdown tables** — pipe-syntax tables do not render in Telegram. Use numbered lists instead.
+
+**Email/inbox lists** — use this pattern:
+```
+📬 *Inbox (10)*
+
+1\. *Google* — Security alert `22:58`
+2\. *LinkedIn* — Matthew Chittle wants to connect `21:31`
+3\. *DeepLearning\.AI* — AI Dev 26 × SF speakers `13:20`
+4\. *LinkedIn Jobs* — Project Manager / TPM roles `17:32`
+```
+
+**Copyable values** (email addresses, URLs, API keys, commands) — wrap in backtick code spans:
+`user@example.com`, `https://example.com`, `npm install foo`
+
+**Human-in-the-loop** — after listing emails or before acting, use `telegram_ask` to offer inline buttons rather than asking the user to type a reply.
+
+**Keep lines short** — Telegram wraps long lines poorly on mobile. Break at natural points.
+
 ## Communication Style
 
 - Be direct and helpful

package/src/telegram.js

@@ -1,11 +1,12 @@
 const path = require('path');
-const { Bot, GrammyError, HttpError } = require('grammy');
+const { Bot, GrammyError, HttpError, InlineKeyboard } = require('grammy');
 const { loadConfig } = require('./config');
 const { evolve, loadEvolutionState } = require('./evolve');
 const { getTenant } = require('./tenant');
 const { loadTraits, saveTraits, DEFAULT_TRAITS } = require('./personality');
 const media = require('./media');
 const credentials = require('./credentials');
+const { getMaxToolIterations, setMaxToolIterations } = require('./claude');
 
 const RATE_LIMIT_MS = 3000;
 const SPAM_THRESHOLD = 5;
@@ -23,6 +24,31 @@ function createBot(telegramConfig, config) {
   const bot = new Bot(telegramConfig.token);
   const allowedUsers = new Set(telegramConfig.allowedUsers || []);
   const rateLimits = new Map();
+  const pendingAsks = new Map();
+  let askIdCounter = 0;
+
+  function createAsk(ctx, message, options, timeoutSecs = 60) {
+    return new Promise((resolve) => {
+      const askId = ++askIdCounter;
+      const keyboard = new InlineKeyboard();
+      options.forEach((opt, i) => {
+        keyboard.text(opt, `ask:${askId}:${i}`);
+        if ((i + 1) % 3 === 0 && i < options.length - 1) keyboard.row();
+      });
+      const timer = setTimeout(() => {
+        if (pendingAsks.has(askId)) {
+          pendingAsks.delete(askId);
+          resolve('timeout');
+        }
+      }, timeoutSecs * 1000);
+      pendingAsks.set(askId, { resolve, options, timer });
+      ctx.reply(message, { parse_mode: 'Markdown', reply_markup: keyboard }).catch(() => {
+        clearTimeout(timer);
+        pendingAsks.delete(askId);
+        resolve('error');
+      });
+    });
+  }
 
   const _rateLimitCleanup = setInterval(() => {
     const now = Date.now();
@@ -51,6 +77,8 @@ function createBot(telegramConfig, config) {
     { command: 'traits', description: 'View or adjust personality traits' },
     { command: 'secret', description: 'Manage per-user secrets' },
     { command: 'evolution', description: 'Evolution progress' },
+    { command: 'verbose', description: 'Toggle verbose mode on/off' },
+    { command: 'toolimit', description: 'View or set max tool iterations per message' },
     { command: 'help', description: 'Show available commands' },
   ]).catch(() => {});
 
@@ -102,6 +130,7 @@ function createBot(telegramConfig, config) {
     text += `⏱️ Uptime: ${h}h ${m}m\n`;
     text += `💾 Memory: ${mem}MB\n`;
     text += `⚡ Tasks: ${running.length} running\n`;
+    text += `🔧 Tool limit: ${getMaxToolIterations()}\n`;
 
     if (tenant.memory) {
       const stats = await tenant.memory.stats().catch(() => null);
@@ -254,6 +283,11 @@ function createBot(telegramConfig, config) {
         ctx.api.deleteMessage(ctx.chat.id, ctx.message.message_id).catch(() => {});
         credentials.storeSecret(userId, key, value);
         await ctx.reply(`🔑 Secret "${key}" stored securely.`);
+        const tenant = await getTenant(userId, config);
+        if (tenant.claude?.injectHistory) {
+          tenant.claude.injectHistory(ctx.chat.id, 'user', `[System: user stored secret "${key}" via /secret set]`);
+          tenant.claude.injectHistory(ctx.chat.id, 'assistant', `Noted — secret "${key}" is now stored.`);
+        }
       } catch (e) {
         await ctx.reply(`⚠️ ${e.message}`);
       }
@@ -264,6 +298,11 @@ function createBot(telegramConfig, config) {
       try {
         credentials.removeSecret(userId, args[1]);
         await ctx.reply(`🗑️ Secret "${args[1]}" removed.`);
+        const tenant = await getTenant(userId, config);
+        if (tenant.claude?.injectHistory) {
+          tenant.claude.injectHistory(ctx.chat.id, 'user', `[System: user removed secret "${args[1]}" via /secret remove]`);
+          tenant.claude.injectHistory(ctx.chat.id, 'assistant', `Noted — secret "${args[1]}" has been removed.`);
+        }
       } catch (e) {
         await ctx.reply(`⚠️ ${e.message}`);
       }
@@ -328,9 +367,38 @@ Your message is deleted immediately when using /secret set to keep credentials o
 /status — Bot status and uptime
 /backup — Trigger GitHub backup
 /clean — Audit workspace
+/verbose — Toggle verbose mode on/off
+/toolimit — View or set max tool iterations
 /help — This message`);
   });
 
+  bot.command('verbose', async (ctx) => {
+    if (!ctx.from) return;
+    const tenant = await getTenant(ctx.from.id, config);
+    tenant.verbose = !tenant.verbose;
+    await ctx.reply(tenant.verbose ? '🔍 Verbose mode ON' : '🔇 Verbose mode OFF');
+  });
+
+  bot.command('toolimit', async (ctx) => {
+    if (!ctx.from) return;
+    const args = ctx.message.text.split(' ').slice(1);
+    const current = getMaxToolIterations();
+
+    if (!args[0]) {
+      await ctx.reply(`🔧 Max tool iterations: ${current}\n\nThis limits how many tool calls OBOL can make per message. Higher = more complex tasks, but slower responses.\n\nSet: /toolimit <number>\nExample: /toolimit 50`);
+      return;
+    }
+
+    const value = parseInt(args[0], 10);
+    if (isNaN(value) || value < 1 || value > 500) {
+      await ctx.reply(`Invalid value: "${args[0]}"\n\nMust be a number between 1 and 500.\nCurrent: ${current}\n\nExample: /toolimit 50`);
+      return;
+    }
+
+    setMaxToolIterations(value);
+    await ctx.reply(`🔧 Max tool iterations set to ${value}`);
+  });
+
   function checkRateLimit(userId) {
     const now = Date.now();
     const userLimit = rateLimits.get(userId) || { lastMessage: 0, spamCount: 0, cooldownUntil: 0 };
@@ -382,7 +450,7 @@ Your message is deleted immediately when using /secret set to keep credentials o
     try {
       tenant.messageLog?.log(ctx.chat.id, 'user', userMessage);
 
-      const response = await tenant.claude.chat(userMessage, {
+      const chatContext = {
         userId,
         userName,
         chatId: ctx.chat.id,
@@ -390,14 +458,24 @@ Your message is deleted immediately when using /secret set to keep credentials o
         ctx,
         claude: tenant.claude,
         config,
+        verbose: tenant.verbose,
+        telegramAsk: (message, options, timeout) => createAsk(ctx, message, options, timeout),
         _notifyFn: (targetUserId, message) => {
           if (!allowedUsers.has(targetUserId)) throw new Error('Cannot notify user outside allowed list');
           return bot.api.sendMessage(targetUserId, message);
         },
-      });
+      };
+      const response = await tenant.claude.chat(userMessage, chatContext);
 
       tenant.messageLog?.log(ctx.chat.id, 'assistant', response);
 
+      if (tenant.verbose && chatContext.verboseLog?.length) {
+        const verboseText = '```\n' + chatContext.verboseLog.join('\n') + '\n```';
+        await ctx.reply(verboseText, { parse_mode: 'Markdown' }).catch(() =>
+          ctx.reply(verboseText).catch(() => {})
+        );
+      }
+
       if (tenant.messageLog?._evolutionReady) {
         tenant.messageLog._evolutionReady = false;
         setImmediate(async () => {
@@ -515,7 +593,7 @@ Your message is deleted immediately when using /secret set to keep credentials o
       if (media.isImage(fileInfo)) {
         const imageBlock = media.bufferToImageBlock(buffer, fileInfo.mimeType);
         const prompt = caption || 'The user sent this image. Describe what you see and respond naturally.';
-        const response = await tenant.claude.chat(prompt, {
+        const mediaChatCtx = {
           userId,
           userName: ctx.from.first_name || 'User',
           chatId: ctx.chat.id,
@@ -523,16 +601,23 @@ Your message is deleted immediately when using /secret set to keep credentials o
           ctx,
           claude: tenant.claude,
           config,
+          verbose: tenant.verbose,
           images: [imageBlock],
           _notifyFn: (targetUserId, message) => {
             if (!allowedUsers.has(targetUserId)) throw new Error('Cannot notify user outside allowed list');
             return bot.api.sendMessage(targetUserId, message);
           },
-        });
+        };
+        const response = await tenant.claude.chat(prompt, mediaChatCtx);
 
         tenant.messageLog?.log(ctx.chat.id, 'user', `[${fileInfo.mediaType}] ${caption || filename}`);
         tenant.messageLog?.log(ctx.chat.id, 'assistant', response);
 
+        if (tenant.verbose && mediaChatCtx.verboseLog?.length) {
+          const verboseText = '```\n' + mediaChatCtx.verboseLog.join('\n') + '\n```';
+          await ctx.reply(verboseText, { parse_mode: 'Markdown' }).catch(() => ctx.reply(verboseText).catch(() => {}));
+        }
+
         stopTyping();
         if (response.length > 4096) {
           for (const chunk of splitMessage(response, 4096)) {
@@ -543,7 +628,7 @@ Your message is deleted immediately when using /secret set to keep credentials o
         }
       } else if (caption) {
         const contextMsg = `[User sent a ${fileInfo.mediaType}: ${filename}] ${caption}`;
-        const response = await tenant.claude.chat(contextMsg, {
+        const mediaCaptionCtx = {
           userId,
           userName: ctx.from.first_name || 'User',
           chatId: ctx.chat.id,
@@ -551,15 +636,22 @@ Your message is deleted immediately when using /secret set to keep credentials o
           ctx,
           claude: tenant.claude,
           config,
+          verbose: tenant.verbose,
           _notifyFn: (targetUserId, message) => {
             if (!allowedUsers.has(targetUserId)) throw new Error('Cannot notify user outside allowed list');
             return bot.api.sendMessage(targetUserId, message);
           },
-        });
+        };
+        const response = await tenant.claude.chat(contextMsg, mediaCaptionCtx);
 
         tenant.messageLog?.log(ctx.chat.id, 'user', contextMsg);
         tenant.messageLog?.log(ctx.chat.id, 'assistant', response);
 
+        if (tenant.verbose && mediaCaptionCtx.verboseLog?.length) {
+          const verboseText = '```\n' + mediaCaptionCtx.verboseLog.join('\n') + '\n```';
+          await ctx.reply(verboseText, { parse_mode: 'Markdown' }).catch(() => ctx.reply(verboseText).catch(() => {}));
+        }
+
         stopTyping();
         if (response.length > 4096) {
           for (const chunk of splitMessage(response, 4096)) {
@@ -588,6 +680,22 @@ Your message is deleted immediately when using /secret set to keep credentials o
   bot.on('message:animation', handleMedia);
   bot.on('message:video_note', handleMedia);
 
+  bot.on('callback_query:data', async (ctx) => {
+    const data = ctx.callbackQuery.data;
+    if (!data.startsWith('ask:')) return ctx.answerCallbackQuery();
+    const parts = data.split(':');
+    const askId = parseInt(parts[1]);
+    const optIdx = parseInt(parts[2]);
+    const pending = pendingAsks.get(askId);
+    if (!pending) return ctx.answerCallbackQuery({ text: 'Expired' });
+    const selected = pending.options[optIdx];
+    clearTimeout(pending.timer);
+    pendingAsks.delete(askId);
+    await ctx.editMessageText(`${ctx.callbackQuery.message.text}\n\n✓ _${selected}_`, { parse_mode: 'Markdown' }).catch(() => {});
+    await ctx.answerCallbackQuery({ text: selected });
+    pending.resolve(selected);
+  });
+
   bot.catch((err) => {
     const ctx = err.ctx;
     const e = err.error;

package/src/tenant.js

@@ -43,6 +43,7 @@ async function createTenant(userId, config) {
 
   return {
     claude, memory, messageLog, personality, bg, userDir, userId,
+    verbose: false,
     _personalityLoadedAt: Date.now(),
     _personalityMtime: personalityMtime,
   };