obol-ai 0.2.14 → 0.2.16

package/.claude/settings.local.json

@@ -1,23 +1,9 @@
 {
   "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:*)",
-      "Bash(pass ls:*)",
+      "Bash(*)",
       "mcp__context7__query-docs",
-      "Bash(git stash pop:*)",
       "mcp__context7__resolve-library-id"
     ]
   }
-}
+}

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+## 0.2.16
+- add chat_history tool for retrieving past conversations by date
+- add stop button to status UI with concurrent update processing
+- update status UI to reflect model escalation from haiku to sonnet
+- escalate haiku to sonnet when tool use is requested
+- fix tests to match refactored module APIs
+- refactor claude.js, telegram.js, evolve.js into modular directories
+- auto-cleanup stale npm temp dirs on ENOTEMPTY upgrade failure
+
+## 0.2.15
+- auto-generate changelog on publish + show after upgrade
+
+## 0.2.14
+- prompt caching + consolidation interval tuning for inference cost reduction
+- multi-query memory retrieval with importance-weighted ranking
+- time-based evolution with pre-evolution growth analysis
+- add recurring cron events to scheduler
+
+## 0.2.13
+- delete voice selection messages after choosing a voice or toggling tools
+- switch TTS from node websocket to python edge-tts CLI with auto-install
+- retry TTS synthesis on WebSocket timeout
+- hardcoded TTS samples per language
+
+## 0.2.12
+- drop ffmpeg conversion, cache EdgeTTS import for faster TTS
+- tool toggle system with TTS and voice preview
+
+## 0.2.11
+- futuristic terminal UI for telegram status and commands
+- live tool status via haiku with cached descriptions and 1s timer
+- telegram: dedup, HTML formatting, reply context, processing status, text buffering, media groups
+- pdf extraction via read_file tool instead of hardcoded handling
+- fix telegram formatting instructions to use telegram markdown syntax
+- fix duplicate tool_result handling and stale telegram callback queries
+
+## 0.2.10
+- force text response after tool use, cap tool iterations to 10
+- credential leak protection and improved agent defaults
+- encrypt secrets at rest in config.json and secrets.json when pass is unavailable
+
+## 0.2.8
+- batch migrations into single request with timeout, improve event description prompting
+- run migrations on every startup instead of once
+- store image analysis in memory for semantic retrieval
+- add event scheduling and reminders via heartbeat
+- deep memory consolidation with sonnet during evolution
+- aggressive memory: tags, importance, fix access_count increment
+- drop redundant user_id from obol_messages
+- track token usage and model in message log
+- refactor chat history into turn-based ChatHistory class with atomic pruning
+
+## 0.2.7
+- migrate tool loop to SDK toolRunner
+
+## 0.2.6
+- loosen exec security patterns to only block genuinely destructive commands
+- unblock python3 -c from exec security patterns
+- stream verbose logs to telegram in real-time instead of batching
+- evolution: 15min idle timer + fix double-trigger race condition
+- tune model router criteria per anthropic guidance
+
+## 0.2.5
+- add /upgrade telegram command with post-restart notification
+- feat: haiku model routing + performance comparison in readme
+
+## 0.2.4
+- harden system prompt against evolution drift
+- feat: add haiku to router model choices for trivial messages
+- fix: chat lock, bidirectional history repair, context window in /status
+
+## 0.2.3
+- feat: telegram_ask tool + Telegram-friendly formatting guidelines
+- fix: repair orphaned tool_use blocks and add /toolimit command
+- feat: add /verbose telegram command to toggle debug output
+
+## 0.2.2
+- fix: strip orphaned tool_result messages after history trim
+- feat: add send_file tool, self-extending capability, and secret history injection
+- docs: update README and DEPLOY for removed onboarding, new commands
+- feat: add obol delete command for full VPS cleanup
+- docs: update agent instructions for secret tools and Python scripts
+- feat: add per-user credential scoping with /secret command
+- feat: add evolution bar and traits to /status command
+- fix: security hardening and stability improvements (29 fixes)
+- fix: repair all broken tests (218/218 passing)
+- feat: add personality trait sliders with /traits command and evolution auto-adjustment
+- feat: remove onboarding flow, agent works from message one
+- fix: make post-setup global instead of per-user
+- fix: preserve refresh token when not returned by Anthropic
+- fix: OAuth refresh race condition + add proper OAuth flow to config
+- docs: add obol upgrade to help sections
+- feat: add obol upgrade command + bump to 0.1.5
+- fix: 23 fixes — security, validation, UX, memory leaks across onboarding + core
+- fix: 12 bug fixes — validation, rate limiting, sandboxing, evolution, UX
+- feat: telegram media file handling with vision support
+- test: add 226 tests across 14 test files with vitest
+- fix: security hardening, rate limiting, UX improvements across all modules
+- feat: bridge — let user agents ask and tell each other
+- feat: multi-tenant per-user isolation
+- docs: update README and DEPLOY for onboarding hardening
+- feat: onboarding hardening — validation, pm2 fallbacks, Telegram ID detection
+
+## 0.1.2
+- fix: downgrade inquirer to v8 for CommonJS compat
+- chore: bump 0.1.1
+- chore: rename package to obol-ai for npm, add .npmignore
+- README: simplify API cost estimate
+- README: accurate API pricing breakdown with tier recommendations
+- workspace discipline: folder structure enforcement + /clean command
+- evolution: default 100 exchanges, purge stale Opus references
+- resilience: polling auto-restart, error handling, evolution cost control
+- README: full revision — deduplicated, added git snapshots, tighter structure
+- README: neutral comparison closing
+- evolution: git commit+push before and after every evolution cycle
+- README: Layer 3 → The Evolution Cycle
+- README: feature highlights at the top
+- evolution: proactive web app building + Vercel auto-deploy
+- evolution: proactive tool building + upgrade announcements
+- README: self-healing, self-evolving agent positioning
+- evolution: fix regressions before rollback (3 attempts, tests are ground truth)
+- DRY: shared test-utils.js for all tests (core + Opus-generated)
+- test-driven evolution: Opus writes tests, runs before/after refactor, rollback on regression
+- evolution: Opus now rewrites AGENTS.md + audits scripts/ and commands/
+- clean up: Haiku only extracts memories, Opus owns all personality files
+- remove Haiku SOUL.md updates — personality only via Opus evolution
+- docs: expand Living Brain architecture section in README
+- feat: soul evolution — Opus rewrites SOUL.md every 50 exchanges, archives previous versions
+- feat: SOUL.md evolves from conversation patterns, not just explicit requests
+- docs: README — two-tier memory, self-evolving personality, message logging
+- feat: Haiku auto-evolves USER.md and SOUL.md from conversations
+- feat: two-tier memory — raw message log + Haiku auto-consolidation every 5 exchanges
+- chore: remove daily notes — vector memory in Supabase is source of truth
+- docs: complete README rewrite — routing, background tasks, security, onboarding flow
+- feat: Haiku routes to Sonnet (daily) or Opus (complex tasks)
+- feat: Haiku as memory router — decides if/what to search, optimizes query
+- feat: smarter memory recall — skip short msgs, today + semantic, stricter threshold, dedupe
+- feat: /new command — clears conversation history
+- chore: trim menu to /tasks /status /backup
+- chore: remove /forget from menu
+- feat: auto memory search before every message, remove /start and /memory from menu
+- feat: Telegram command menu + /status /backup /forget /recent /today
+- feat: non-blocking background tasks with 30s progress check-ins
+- docs: add OBOL vs OpenClaw comparison table
+- feat: replace systemd with pm2 — CLI, post-setup, deploy docs
+- feat: SSH on port 2222, update README + deploy docs with security warnings
+- feat: VPS security hardening — SSH, fail2ban, firewall, auto-updates, kernel
+- feat: post-setup tasks — auto-installs pass, migrates secrets, adds swap + firewall
+- feat: add Vercel deploy tools, self-onboarding via first-run conversation
+- feat: add OBOL banner image
+- docs: add DigitalOcean deployment guide
+- feat: initial scaffold — CLI, Telegram, Claude, memory, backup

package/README.md

@@ -6,6 +6,12 @@
 
 One process. Multiple users. Each brain grows independently.
 
+```bash
+npm install -g obol-ai
+obol init       # walks you through credentials + Telegram setup
+obol start -d   # runs as background daemon (auto-installs pm2)
+```
+
 ---
 
 🧬 **Self-evolving** — Grows its own personality through conversation. Rewrites SOUL.md, USER.md, and AGENTS.md after 24h + minimum exchanges (configurable). Pre-evolution growth analysis guides personality continuity.
@@ -38,16 +44,6 @@ Under the hood: Node.js + Telegram + Claude + Supabase pgvector. No framework, n
 
 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-ai
-obol init
-obol start -d
-```
-
-The init wizard walks you through everything — credentials are validated inline, and your Telegram ID is auto-detected. `obol start -d` runs as a background daemon via pm2 (auto-installs pm2 if missing).
-
 ## How It Works
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obol-ai",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "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": {
@@ -9,7 +9,8 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "node src/cli/changelog.js"
   },
   "keywords": [
     "ai",
@@ -23,6 +24,7 @@
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
+    "@grammyjs/runner": "^2.0.3",
     "@supabase/supabase-js": "^2.49.1",
     "@xenova/transformers": "^2.17.2",
     "commander": "^13.1.0",

package/src/background.js

@@ -81,7 +81,9 @@ TASK: ${task}`;
           routeInfo = info;
         },
         _onRouteUpdate: (update) => {
-          if (routeInfo) routeInfo.memoryCount = update.memoryCount;
+          if (!routeInfo) return;
+          if (update.memoryCount !== undefined) routeInfo.memoryCount = update.memoryCount;
+          if (update.model) routeInfo.model = update.model;
         },
         _onToolStart: (toolName, inputSummary) => {
           statusText = 'Processing';

package/src/claude/cache.js

@@ -0,0 +1,18 @@
+function withCacheBreakpoints(messages) {
+  if (messages.length < 2) return messages;
+  const result = messages.slice();
+  const idx = result.length - 2;
+  const msg = { ...result[idx] };
+  if (typeof msg.content === 'string') {
+    msg.content = [{ type: 'text', text: msg.content, cache_control: { type: 'ephemeral' } }];
+  } else if (Array.isArray(msg.content)) {
+    const last = msg.content.length - 1;
+    msg.content = msg.content.map((block, i) =>
+      i === last ? { ...block, cache_control: { type: 'ephemeral' } } : block
+    );
+  }
+  result[idx] = msg;
+  return result;
+}
+
+module.exports = { withCacheBreakpoints };

package/src/claude/chat.js

@@ -0,0 +1,242 @@
+const path = require('path');
+const { OBOL_DIR } = require('../config');
+const { ChatHistory } = require('../history');
+const { createAnthropicClient, ensureFreshToken } = require('./client');
+const { routeMessage } = require('./router');
+const { buildSystemPrompt } = require('./prompt');
+const { buildTools, buildRunnableTools } = require('./tool-registry');
+const { withCacheBreakpoints } = require('./cache');
+const { getMaxToolIterations } = require('./constants');
+
+function createClaude(anthropicConfig, { personality, memory, userDir = OBOL_DIR, bridgeEnabled }) {
+  let client = createAnthropicClient(anthropicConfig);
+
+  let baseSystemPrompt = buildSystemPrompt(personality, userDir, { bridgeEnabled });
+
+  const histories = new ChatHistory(50);
+  const chatLocks = new Map();
+  const chatAbortControllers = new Map();
+
+  const tools = buildTools(memory, { bridgeEnabled });
+
+  function acquireChatLock(chatId) {
+    if (!chatLocks.has(chatId)) chatLocks.set(chatId, { promise: Promise.resolve(), busy: false });
+    const lock = chatLocks.get(chatId);
+    let release;
+    const prev = lock.promise;
+    lock.promise = new Promise(r => { release = r; });
+    return prev.then(() => {
+      lock.busy = true;
+      return () => { lock.busy = false; release(); };
+    });
+  }
+
+  function isChatBusy(chatId) {
+    return chatLocks.get(chatId)?.busy || false;
+  }
+
+  async function chat(userMessage, context = {}) {
+    context.userDir = userDir;
+    const chatId = context.chatId || 'default';
+
+    if (isChatBusy(chatId)) {
+      return { text: 'I\'m still working on the previous request. Give me a moment.', usage: null, model: null };
+    }
+
+    const releaseLock = await acquireChatLock(chatId);
+    const abortController = new AbortController();
+    chatAbortControllers.set(chatId, abortController);
+
+    const history = histories.get(chatId);
+
+    try {
+
+    if (anthropicConfig.oauth?.accessToken) {
+      await ensureFreshToken(anthropicConfig);
+      if (anthropicConfig._oauthFailed) {
+        client = createAnthropicClient(anthropicConfig, { useOAuth: false });
+      } else {
+        client = createAnthropicClient(anthropicConfig, { useOAuth: true });
+      }
+    }
+
+    const verbose = context.verbose || false;
+    if (verbose) context.verboseLog = [];
+    const vlog = (msg) => {
+      if (!verbose) return;
+      context.verboseLog.push(msg);
+      context._verboseNotify?.(msg);
+    };
+
+    let memoryBlock = null;
+    if (memory) {
+      const result = await routeMessage(client, memory, userMessage, {
+        vlog,
+        onRouteDecision: context._onRouteDecision,
+        onRouteUpdate: context._onRouteUpdate,
+      });
+      memoryBlock = result.memoryBlock;
+      if (result.model) context._model = result.model;
+    }
+
+    histories.prune(chatId);
+
+    if (context.images?.length) {
+      histories.pushUser(chatId, [...context.images, { type: 'text', text: userMessage }]);
+    } else {
+      histories.pushUser(chatId, userMessage);
+    }
+
+    const model = context._model || 'claude-sonnet-4-6';
+    vlog(`[model] ${model} | history=${history.length} msgs | facts=${memoryBlock ? 'yes' : 'none'}`);
+    const systemPrompt = [
+      { type: 'text', text: baseSystemPrompt, cache_control: { type: 'ephemeral' } },
+      { type: 'text', text: `\nCurrent time: ${new Date().toISOString()}${memoryBlock ? `\n\n${memoryBlock}` : ''}` },
+    ];
+    context._reloadPersonality = reloadPersonality;
+    context._abortSignal = abortController.signal;
+    const runnableTools = buildRunnableTools(tools, memory, context, vlog);
+    let activeModel = model;
+
+    let totalUsage = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
+
+    function trackUsage(usage) {
+      if (!usage) return;
+      totalUsage.input_tokens += usage.input_tokens || 0;
+      totalUsage.output_tokens += usage.output_tokens || 0;
+      totalUsage.cache_creation_input_tokens += usage.cache_creation_input_tokens || 0;
+      totalUsage.cache_read_input_tokens += usage.cache_read_input_tokens || 0;
+      const cacheInfo = (usage.cache_read_input_tokens || usage.cache_creation_input_tokens)
+        ? ` cache_read=${usage.cache_read_input_tokens || 0} cache_create=${usage.cache_creation_input_tokens || 0}`
+        : '';
+      vlog(`[tokens] in=${usage.input_tokens} out=${usage.output_tokens}${cacheInfo}`);
+    }
+
+    if (activeModel.includes('haiku') && runnableTools.length > 0) {
+      const toolDefs = runnableTools.map(({ run, ...def }) => def);
+      const probe = await client.messages.create({
+        model: activeModel,
+        max_tokens: 4096,
+        system: systemPrompt,
+        messages: withCacheBreakpoints([...history]),
+        tools: toolDefs,
+      }, { signal: abortController.signal });
+
+      trackUsage(probe.usage);
+
+      if (probe.stop_reason !== 'tool_use') {
+        histories.pushAssistant(chatId, probe.content);
+        const text = probe.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+        return { text, usage: totalUsage, model: activeModel };
+      }
+
+      vlog('[escalate] haiku → sonnet (tool use requested)');
+      activeModel = 'claude-sonnet-4-6';
+      context._onRouteUpdate?.({ model: 'sonnet' });
+    }
+
+    const runner = client.beta.messages.toolRunner({
+      model: activeModel,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages: withCacheBreakpoints([...history]),
+      tools: runnableTools.length > 0 ? runnableTools : undefined,
+      max_iterations: getMaxToolIterations(),
+    }, { signal: abortController.signal });
+
+    let finalMessage;
+    for await (const message of runner) {
+      finalMessage = message;
+      trackUsage(message.usage);
+      if (abortController.signal.aborted) break;
+    }
+
+    const runnerMessages = runner.params.messages;
+    const newMessages = runnerMessages.slice(history.length);
+    histories.pushMessages(chatId, newMessages);
+
+    if (finalMessage.stop_reason === 'tool_use') {
+      const bailoutResults = finalMessage.content
+        .filter(b => b.type === 'tool_use')
+        .map(b => ({ type: 'tool_result', tool_use_id: b.id, content: '[max tool iterations reached]' }));
+      histories.pushUser(chatId, [
+        ...bailoutResults,
+        { type: 'text', text: 'You have used too many tool calls. Please provide a final response now based on what you have so far.' },
+      ]);
+      const bailoutResponse = await client.messages.create({
+        model: activeModel, max_tokens: 4096, system: systemPrompt, messages: withCacheBreakpoints([...histories.get(chatId)]),
+      }, { signal: abortController.signal });
+      histories.pushAssistant(chatId, bailoutResponse.content);
+      trackUsage(bailoutResponse.usage);
+      const text = bailoutResponse.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+      return { text, usage: totalUsage, model: activeModel };
+    }
+
+    let text = finalMessage.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+
+    if (!text.trim() && newMessages.length > 1) {
+      vlog('[claude] No text in final response after tool use — forcing summary');
+      histories.pushUser(chatId, 'Provide a concise response to the user based on the tool results above.');
+      const summaryResponse = await client.messages.create({
+        model: activeModel, max_tokens: 4096, system: systemPrompt, messages: withCacheBreakpoints([...histories.get(chatId)]),
+      }, { signal: abortController.signal });
+      histories.pushAssistant(chatId, summaryResponse.content);
+      trackUsage(summaryResponse.usage);
+      text = summaryResponse.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+    }
+
+    return { text, usage: totalUsage, model: activeModel };
+
+    } catch (e) {
+      if (e.message === 'Request was aborted.' || e.constructor?.name === 'APIUserAbortError') {
+        return { text: null, usage: null, model: null };
+      }
+      if (e.status === 400 && e.message?.includes('tool_use')) {
+        console.error('[claude] Repairing corrupted history after 400 error');
+        histories.repair(chatId);
+      }
+      throw e;
+    } finally {
+      chatAbortControllers.delete(chatId);
+      releaseLock();
+    }
+  }
+
+  function stopChat(chatId) {
+    const controller = chatAbortControllers.get(chatId);
+    if (controller) {
+      controller.abort();
+      return true;
+    }
+    return false;
+  }
+
+  function reloadPersonality() {
+    const pDir = userDir ? path.join(userDir, 'personality') : undefined;
+    const newPersonality = require('../personality').loadPersonality(pDir);
+    for (const key of Object.keys(personality)) delete personality[key];
+    Object.assign(personality, newPersonality);
+    baseSystemPrompt = buildSystemPrompt(personality, userDir, { bridgeEnabled });
+  }
+
+  function clearHistory(chatId) {
+    if (chatId) {
+      histories.delete(chatId);
+    } else {
+      histories.clear();
+    }
+  }
+
+  function injectHistory(chatId, role, content) {
+    histories.inject(chatId, role, content);
+  }
+
+  function getContextStats(chatId) {
+    const id = chatId || 'default';
+    return histories.estimateTokens(id, baseSystemPrompt.length);
+  }
+
+  return { chat, client, reloadPersonality, clearHistory, injectHistory, getContextStats, stopChat };
+}
+
+module.exports = { createClaude };

package/src/claude/client.js

@@ -0,0 +1,90 @@
+const Anthropic = require('@anthropic-ai/sdk');
+const { refreshTokens, isExpired } = require('../oauth');
+const { saveConfig, loadConfig } = require('../config');
+
+function createAnthropicClient(anthropicConfig, { useOAuth = true } = {}) {
+  if (useOAuth && anthropicConfig.oauth?.accessToken) {
+    return new Anthropic({
+      apiKey: null,
+      authToken: anthropicConfig.oauth.accessToken,
+      defaultHeaders: {
+        'anthropic-dangerous-direct-browser-access': 'true',
+        'anthropic-beta': 'claude-code-20250219,oauth-2025-04-20',
+      },
+    });
+  }
+  if (anthropicConfig.apiKey) {
+    return new Anthropic({ apiKey: anthropicConfig.apiKey });
+  }
+  throw new Error('No Anthropic credentials configured. Run: obol config');
+}
+
+let _refreshPromise = null;
+
+async function ensureFreshToken(anthropicConfig) {
+  if (!anthropicConfig.oauth?.accessToken) return;
+  if (!isExpired(anthropicConfig.oauth)) return;
+  if (!anthropicConfig.oauth.refreshToken) {
+    if (anthropicConfig.apiKey) {
+      anthropicConfig._oauthFailed = true;
+      return;
+    }
+    const err = new Error('OAuth token expired and no refresh token available. Re-authenticate with: obol config → Anthropic → OAuth');
+    err.isOAuthExpiry = true;
+    throw err;
+  }
+
+  if (_refreshPromise) {
+    try {
+      await _refreshPromise;
+    } catch {}
+    if (!isExpired(anthropicConfig.oauth)) return;
+    if (anthropicConfig._oauthFailed) return;
+  }
+
+  _refreshPromise = (async () => {
+    try {
+      const tokens = await refreshTokens(anthropicConfig.oauth.refreshToken);
+      console.log('[oauth] Refresh succeeded, new refresh token:', !!tokens.refreshToken);
+      anthropicConfig.oauth.accessToken = tokens.accessToken;
+      if (tokens.refreshToken) anthropicConfig.oauth.refreshToken = tokens.refreshToken;
+      anthropicConfig.oauth.expires = tokens.expires;
+      delete anthropicConfig._oauthFailed;
+
+      const config = loadConfig({ resolve: false });
+      if (config) {
+        config.anthropic.oauth = anthropicConfig.oauth;
+        saveConfig(config);
+      }
+    } catch (e) {
+      console.warn('[oauth] Refresh failed, checking disk for updated tokens:', e.message);
+      const diskConfig = loadConfig({ resolve: false });
+      if (diskConfig?.anthropic?.oauth?.accessToken &&
+          diskConfig.anthropic.oauth.accessToken !== anthropicConfig.oauth.accessToken &&
+          !isExpired(diskConfig.anthropic.oauth)) {
+        anthropicConfig.oauth.accessToken = diskConfig.anthropic.oauth.accessToken;
+        anthropicConfig.oauth.refreshToken = diskConfig.anthropic.oauth.refreshToken;
+        anthropicConfig.oauth.expires = diskConfig.anthropic.oauth.expires;
+        delete anthropicConfig._oauthFailed;
+        return;
+      }
+
+      if (anthropicConfig.apiKey) {
+        console.warn('[oauth] Token refresh failed, falling back to API key:', e.message);
+        anthropicConfig._oauthFailed = true;
+      } else {
+        const err = new Error(`OAuth token expired and refresh failed: ${e.message}`);
+        err.isOAuthExpiry = true;
+        throw err;
+      }
+    }
+  })();
+
+  try {
+    await _refreshPromise;
+  } finally {
+    _refreshPromise = null;
+  }
+}
+
+module.exports = { createAnthropicClient, ensureFreshToken };

package/src/claude/constants.js

@@ -0,0 +1,64 @@
+const MAX_EXEC_TIMEOUT = 120;
+let MAX_TOOL_ITERATIONS = 10;
+
+const OPTIONAL_TOOLS = {
+  text_to_speech: {
+    label: 'Text to Speech',
+    tools: ['text_to_speech', 'tts_voices'],
+    config: {
+      voice: { label: 'Voice', default: 'en-US-JennyNeural' },
+    },
+  },
+  create_pdf: {
+    label: 'PDF Generator',
+    tools: ['create_pdf'],
+    config: {},
+  },
+  vercel: {
+    label: 'Vercel Deploy',
+    tools: ['vercel_deploy', 'vercel_list'],
+    config: {},
+  },
+  scheduler: {
+    label: 'Scheduler',
+    tools: ['schedule_event', 'list_events', 'cancel_event'],
+    config: {},
+  },
+  background: {
+    label: 'Background Tasks',
+    tools: ['background_task'],
+    config: {},
+  },
+};
+
+const BLOCKED_EXEC_PATTERNS = [
+  /\brm\s+(-[a-zA-Z]*f|-[a-zA-Z]*r|--force|--recursive)\b/,
+  /\bshutdown\b/, /\breboot\b/, /\bpoweroff\b/,
+  /\bmkfs\b/, /\bdd\s+if=/, /\b:()\{\s*:|:&\s*\};:/,
+  /\bchmod\s+(-R\s+)?[0-7]*\s+\/[^t]/,
+  />\s*\/etc\//, />\s*\/boot\//,
+  /\bcurl\b.*\|\s*(ba)?sh/, /\bwget\b.*\|\s*(ba)?sh/,
+  /\bnc\s+-e\b/, /\bncat\b.*-e\b/,
+  />\s*\/dev\/sd/,
+];
+
+const SENSITIVE_READ_PATHS = [
+  /\/etc\/(passwd|shadow|sudoers)/,
+  /\/etc\/ssh\//,
+  /\.(env|pem|key|crt|p12|pfx)(\s|$)/,
+  /~\/\.ssh\//,
+  /~\/\.gnupg\//,
+  /\/root\//,
+];
+
+function getMaxToolIterations() { return MAX_TOOL_ITERATIONS; }
+function setMaxToolIterations(n) { MAX_TOOL_ITERATIONS = n; }
+
+module.exports = {
+  MAX_EXEC_TIMEOUT,
+  OPTIONAL_TOOLS,
+  BLOCKED_EXEC_PATTERNS,
+  SENSITIVE_READ_PATHS,
+  getMaxToolIterations,
+  setMaxToolIterations,
+};

package/src/claude/index.js

@@ -0,0 +1,5 @@
+const { createClaude } = require('./chat');
+const { createAnthropicClient } = require('./client');
+const { getMaxToolIterations, setMaxToolIterations, OPTIONAL_TOOLS } = require('./constants');
+
+module.exports = { createClaude, createAnthropicClient, getMaxToolIterations, setMaxToolIterations, OPTIONAL_TOOLS };